Initial schema for AS v2

This commit is contained in:
Timo Ley 2021-06-23 22:06:21 +02:00
commit 3bdbe4693e
11 changed files with 243 additions and 0 deletions

2
.gitignore vendored Normal file
View file

@ -0,0 +1,2 @@
book
.idea

6
book.toml Normal file
View file

@ -0,0 +1,6 @@
[book]
authors = ["AddonScript Team", "Timo Ley"]
language = "en"
multilingual = false
src = "docs"
title = "AddonScript"

14
docs/SUMMARY.md Normal file
View file

@ -0,0 +1,14 @@
# AddonScript
# Schema
- [Addon Object](schema/root.md)
- [AddonScript Object](schema/addonscript.md)
- [Version Object](schema/version.md)
- [File Object](schema/file.md)
- [Relation Object](schema/relation.md)
- [Repository Object](schema/repository.md)
- [Index Object](schema/index.md)
- [Meta Object](schema/meta.md)

View file

@ -0,0 +1,10 @@
# AddonScript Object
``` json
{
"version": 2
}
```
Currently the AddonScript object only contains the version of AddonScript, the file ist using.
In future versions there may be other information in this.

43
docs/schema/file.md Normal file
View file

@ -0,0 +1,43 @@
# File Object
``` json
{
"id": "modfile",
"url": "https://example.com/mymod.jar",
"flags": [],
"install": [
"move mods"
],
"sha1": "somesha1checksum"
}
```
## Required properties
### id
This is the ID of the file. It should only contain lowercase letters, numbers and dashes.
If multiple file objects in the same array have the same ID, they are treated as the same file,
which means, that the first one of them in the array will be used unless it can't be retrieved from the URL,
in which case the next one will be used as fallback.
### url
This is URL, which points to the actual file. The URL can have one of the schemes listed [here](../schemes.md).
### install
This is an array of [install steps](../install.md). They describe, how the file should be installed to the game.
The order in the array correspond to the order, in which the install steps should be applied.
## Optional properties
### flags
This is an array of [flags](../flags.md) for this file. If this property is not present in a file object, the file
will have the flags, which are set as default for files or, if no default was set, it will inherit the flags from the
associated version, which are applicable for files.
### sha1
This is the sha1 checksum of the file. Although the checksum is optional, it is recommended to use it.

25
docs/schema/index.md Normal file
View file

@ -0,0 +1,25 @@
# Index Object
```json
{
"versions": {
"1.0": "https://example.json/mymod-1.0.json"
},
"addons": {
"othermod": "https://example.com/othermod.json"
}
}
```
## Optional Properties
### versions
This is a map, with version numbers as keys and URLs to AddonScript files as values. The AddonScript file, to which the URL
points, must include the version number, which is the key in the map, and its addon ID must match the addon ID of the AddonScript
file, which includes the index object.
### addons
This is a map, with addon IDs as keys and URLs to AddonScript files as values. The addon ID of the AddonScript file, to
which the URL points, must match the key in the map.

7
docs/schema/meta.md Normal file
View file

@ -0,0 +1,7 @@
# Meta Object
Meta objects can be included in [addon](root.md) and [version](version.md) objects.
They should be used, to give information about the addon or the version, like a name,
a description or a changelog. The specification does not require a specific format
for meta objects, therefore you can add any property you want to it. It is however
recommended, to follow conventions for it.

27
docs/schema/relation.md Normal file
View file

@ -0,0 +1,27 @@
# Relation Object
```json
{
"id": "namespace:othermod",
"version": "[1.0,)",
"flags": []
}
```
## Required properties
### id
This is the ID or namespaced ID of the addon, this relation refers to.
### version
This is a [maven version range](https://maven.apache.org/enforcer/enforcer-rules/versionRanges.html) of supported versions of this relation.
## Optional properties
### flags
This is an array of [flags](../flags.md) for this relation. If this property is not present in a relation object, the relation
will have the flags, which are set as default for relations or, if no default was set, it will inherit the flags from the
associated version, which are applicable for relations.

24
docs/schema/repository.md Normal file
View file

@ -0,0 +1,24 @@
# Repository Object
```json
{
"id": "asrepo",
"type": "api",
"link": "https://addonscript.net/repo"
}
```
## Required properties
### id
This is the ID of the repository. It has to be unique to the AddonScript file.
### type
This is the type of the repository. Possible values are ```api``` or ```maven```.
### link
This is the base URL of the repository. While other URLs in AddonScript can have different schemes,
the base URL has to be a http(s) URL.

48
docs/schema/root.md Normal file
View file

@ -0,0 +1,48 @@
# Addon Object
``` json
{
"addonscript": {},
"id": "myaddon",
"versions": [],
"repositories": [],
"index": {},
"flags": {},
"meta": {}
}
```
## Required properties
### addonscript
This is an [AddonScript object](addonscript.md) containing information about the version of AddonScript used in this file.
### id
This is the ID of your addon. It should only contain lowercase letters, numbers and dashes.
## Optional properties
### versions
This is an array of [version objects](version.md). It is possible to define multiple versions of the addon in one AddonScript file,
but in the most cases, there should be just one version per file. Although this property is optional, as you can define versions
in the [index](index.md), it can be used to define a list of versions, which can be found in the index.
### repositories
This is an array of [repository objects](repository.md). Each repository object defines one repository, from which files or
addons can be retrieved.
### index
This is an [index object](index.md), which includes links to other versions of this addon or to other related addons.
### flags
Not yet specified
### meta
This is a [meta object](meta.md).

37
docs/schema/version.md Normal file
View file

@ -0,0 +1,37 @@
# Version Object
```json
{
"version": "1.0",
"files": [],
"relations": [],
"flags": ["server", "client"],
"meta": {}
}
```
## Required properties
### version
This is the version number of this version. It should follow [Maven version naming conventions](https://docs.oracle.com/middleware/1212/core/MAVEN/maven_version.htm),
as they are used to comparing versions.
## Optional properties
### files
This is an array of [file objects](file.md), including the files, belonging to this version.
### relations
This is an array of [relation objects](relation.md), which represents related addons.
### flags
This is an array of [flags](../flags.md) for this version. If this property is not present in a version object, the version
will have the flags, which are set as default for versions.
### meta
This is a [meta object](meta.md).