Merge pull request 'Spec rephrasing to use requirement keywords' (#24) from tilera/addonscript-spec:master into master

Reviewed-on: addonscript/addonscript-spec#24
This commit is contained in:
Timo Ley 2022-09-05 16:07:19 +00:00
commit 65408a2b21
18 changed files with 52 additions and 52 deletions

View file

@ -30,7 +30,7 @@ available on this API instance.
## Features
API features can be either part of the specification itself or
are specified by third parties. Third-party API features should
are specified by third parties. Third-party API features SHOULD
be in a namespace-like format (reversed domain name).
These API features are part of the AddonScript specification itself:

View file

@ -18,7 +18,7 @@ of the addon.
#### Responses:
- `200 OK`: The addon is available in this addon repository.
The response body must be an [API Addon Object](../../schema/api_addon.md).
The response body MUST be an [API Addon Object](../../schema/api_addon.md).
- `404 Not Found`: The addon is not available in this addon repository.
### Get addon manifest
@ -36,5 +36,5 @@ This endpoint can be used to retrieve the manifest of a specific version of an a
#### Responses:
- `200 OK`: This version of the addon is available in this addon repository.
The response body must be an [Addon Manifest](../../schema/manifest.md).
The response body MUST be an [Addon Manifest](../../schema/manifest.md).
- `404 Not Found`: This version of the addon is not available in this addon repository.

View file

@ -7,7 +7,7 @@
`GET {base URL}/v2/files/:namespace/:addon/:version/:qualifier`
This endpoint can be used to retrieve information about a specific file.
If the instance don't know this file, it must respond with status code 404.
If the instance don't know this file, it MUST respond with status code 404.
#### Path variables:
@ -20,7 +20,7 @@ of the addon to which the file belongs to
#### Responses:
- `200 OK`: The file is available in this file repository.
The response body must be an [API File Object](../../schema/api_file.md).
The response body MUST be an [API File Object](../../schema/api_file.md).
- `404 Not Found`: The file is not available in this file repository.
### Get a file by hash
@ -29,7 +29,7 @@ The response body must be an [API File Object](../../schema/api_file.md).
This endpoint can be used to retrieve information about a file from the hash value of the file.
If the instance can't find the file by the hash or does not know the specified hash algorithm,
it must respond with status code 404.
it MUST respond with status code 404.
#### Path variables:
@ -39,6 +39,6 @@ it must respond with status code 404.
#### Responses:
- `200 OK`: The file is available in this file repository.
The response body must be an [API File Object](../../schema/api_file.md).
The response body MUST be an [API File Object](../../schema/api_file.md).
- `404 Not Found`: The file is either not available in this file repository
or the hash algorithm is unknown to the API instance.

View file

@ -23,10 +23,10 @@ addon manifest, including for which side it is available and for which side it i
- `required` This flag specifies, that the related addon or file is required for the addon. If the addon gets installed,
than any relation or file, which has this flag set, also has to be installed.
- `optional` This flag specifies, that the related addon or file is optional for this addon. If the addon gets installed,
the user should be able to choose, whether he wants to install the relation or file with this flag, or not.
the user SHOULD be able to choose, whether he wants to install the relation or file with this flag, or not.
- `included` This flag is only valid for relations. It specifies, that the related addon is included in this one.
This also means, that if some addon requires the related addon, it can also be installed with this addon instead.
Relations with this flag must have an exact version specified, a version range, which includes multiple versions
Relations with this flag MUST have an exact version specified, a version range, which includes multiple versions
is not allowed. If this flag is used together with `required` or `optional`, the files of the related addon will
be installed like if the relation wouldn't have this flag, relations of the related addon will however be ignored
since AddonScript assumes, that they are already covered by this addon.
@ -34,9 +34,9 @@ addon manifest, including for which side it is available and for which side it i
that they can't be installed together in the same instance. For a file this flag specifies, that the file can't be
installed on the side which has this flag set.
- `launch` This flag is only valid for instance addons. For a relation this flag specifies, that the launch configuration
should be delegated to the related addon. The related addon must also be an instance addon on that side. For a file this
flag specifies, that the file should be the launch file of this addon. On the client side the launch file must be a
will be delegated to the related addon. The related addon MUST also be an instance addon on that side. For a file this
flag specifies, that the file will be the launch file of this addon. On the client side the launch file MUST be a
[client JSON file](https://minecraft.fandom.com/wiki/Client.json) which contains the client launch configuration.
On the server side the launch file must be an executable jar file, which should be executed to start the server.
On the server side the launch file MUST be an executable jar file, which will be executed to start the server.
This jar file will implicitly be installed by being moved to the root of the server directory. This flag always
also implies any effect of `required`.

View file

@ -8,8 +8,7 @@ args:
- `[location]`
`move` is simplest install action of all. It just moves the file to
the given location.
`move` moves the file to the given location.
### extract
@ -32,13 +31,13 @@ args:
`inject` can be used with zip or jar files, to inject the contents of that file
into the server launch jar on server side or into the client jar on client side.
In contrast to libraries, `inject` will not add that file to the classpath, but
In contrast to libraries, `inject` will not add just that file to the classpath, but
will also overwrite classes, which are already contained in the game jar, if they
are also in injected file.
## Locations
Locations are specified as a relative path from the Minecraft directory to which the file should be installed.
Locations are specified as a relative path from the Minecraft directory to which the file will be installed.
For example `./mods` would point to the mods directory of the Minecraft instance.
## Directories

View file

@ -1,16 +1,16 @@
# Instance addons
Instance addons represent instances of Minecraft itself, while non-instance addons
have to be installed into an existing instance of Minecraft. An instance addon requires
have to be installed into an existing instance of Minecraft. An instance addon MUST have
a launch configuration for each side for which it is available. This means, that an instance
addon must have exactly one [file](../schema/file.md) or [relation](../schema/relation.md)
for each side, which has the `launch` [flag](flags.md) flag. A file can not have this flag
on both sides, since the file type is different for each side, while a relation may have
addon MUST have exactly one [file](../schema/file.md) or [relation](../schema/relation.md)
for each side, which has the `launch` [flag](flags.md) flag. A file MUST NOT have this flag
on both sides, since the file type is different for each side, while a relation MAY have
it on both sides, as long as the related addon is itself an instance addon for both sides.
## Instance addons as relations
If an instance addon is a relation of another instance addon, each side of that
relation requires to have at least one of the [flags](flags.md) `included`, `launch`
or `incompatible`. Non-instance addons may have instance addons as relations without
relation MUST have at least one of the [flags](flags.md) `included`, `launch`
or `incompatible`. Non-instance addons MAY have instance addons as relations without
this restrictions.

View file

@ -1,6 +1,6 @@
# Links
AddonScript uses links to point to specific files. AddonScript specifies three link types, which can be used
AddonScript uses links to point to specific files. AddonScript specifies two link types, which can be used
to point to files.
## http(s)

View file

@ -4,23 +4,23 @@ Namespaces are used in conjunction with addon IDs to uniquely identify an addon.
## Format
Namespaces may only contain lowercase alphanumeric characters, hyphens (should be avoided) and dots.
They should be in a reversed domain name format. A namespace should specify the distribution source
Namespaces MUST only contain lowercase alphanumeric characters, hyphens (SHOULD be avoided) and dots.
They SHOULD be in a reversed domain name format. A namespace SHOULD specify the distribution source
(i.e. `com.example.repository`) or the author (i.e. `com.author.website`) of the addon and
optionally also the addon type (i.e. `com.example.repository.mods`, `com.author.website.modpacks`).
## Canonical Namespaces
While an addon can have multiple namespaces, it must have exactly one canonical
While an addon MAY have multiple namespaces, it MUST have exactly one canonical
namespace, which is defined in the [addon manifest](../schema/manifest.md#namespace).
An [API instance](../api/) must also return the canonical namespace of
An [API instance](../api/) MUST also return the canonical namespace of
the addon on the [addon endpoint](../api/features/addons.md#get-addon)
even if the addon was requested from another namespace. To check, if two addons
are the same addon, thier canonical namespace and their ID must be equal.
are the same addon, their canonical namespace and their ID MUST be equal.
## Default Namespaces
Each [API instance](../api/) has a default namespace. Addons in the
repository of that API instance should have that namespace, as long as there
repository of that API instance SHOULD have that namespace, as long as there
are no ID conflicts in the repository. The default namespace does not need
to be the canonical namespace of these addons.

View file

@ -1,7 +1,7 @@
# AddonScript Versioning
Version numbers in AddonScript are based on Maven version numbers. The only difference to the Maven versioning specification is,
that AddonScript version numbers may only contain non-space ASCII characters.
that AddonScript version numbers MUST only contain non-space ASCII characters.
## Maven Versioning Specification

View file

@ -1,7 +1,7 @@
# Zip Packaging
With zip packaging, the AddonScript file and the associated files are contained in
a zip file. The AddonScript file has to be called `addon.json` and can either be placed
a zip file. The AddonScript file MUST be named `addon.json` and MUST either be placed
at the root of the zip file or, if there is just one directory in the root of the zip file,
in this directory. All files and directories inside the zip file can be accessed from AddonScript
using the [file links](../concepts/links.md#file). The path from the file URL is relative to the location of

View file

@ -20,7 +20,7 @@
This is the ID of the addon.
It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format.
### namespace

View file

@ -16,8 +16,8 @@
### link
This is an array of [links](../concepts/links.md), which are pointing to the actual file. This must be a http(s) link.
All of these links must have the same file type.
This is an array of [links](../concepts/links.md), which are pointing to the actual file. These MUST be a http(s) links.
All of these links MUST have the same file type.
## Optional properties
@ -31,4 +31,4 @@ Supported hash algorithms:
### meta
This is a [meta object](meta.md) containing metadata about the file. it may only contain [additional metadata](meta.md#additional).
This is a [meta object](meta.md) containing metadata about the file. it SHOULD only contain [additional metadata](meta.md#additional).

View file

@ -17,7 +17,7 @@
### qualifier
This is the qualifier of this file.
It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format.
The qualifier has to be unique to this addon version. The namespace, addon ID, version and qualifier
can together be used to uniquely identify a file.
@ -26,8 +26,8 @@ can together be used to uniquely identify a file.
This is an array of [links](../concepts/links.md), which are pointing to the actual file. All of these links must
have the same file type. Since AddonScript treats directories and zip files equally,
they can be mixed in the same link array. When downloading the file,
the first link in this array should be used with the other links as fallback, if the first doesn't work.
If none of the specified links works or the array is empty, the file link should be retrieved by it's identifier
the first link in this array SHOULD be used with the other links as fallback, if the first doesn't work.
If none of the specified links works or the array is empty, the file link SHOULD be retrieved by it's identifier
from one of the [repositories](repository.md), but only, if a `sha1` hash is specified, so that it can be
verified, that the downloaded file is correct.
@ -35,8 +35,8 @@ verified, that the downloaded file is correct.
### install
This is an array of [install objects](install.md). They describe how the file should be installed to the game.
The order in the array corresponds to the order in which the installation steps should be applied.
This is an array of [install objects](install.md). They describe how the file will be installed to the game.
The order in the array corresponds to the order in which the installation steps will be applied.
### flags

View file

@ -11,7 +11,7 @@
### action
This is the [install action](../concepts/install.md), which should be used at this installation step.
This is the [install action](../concepts/install.md), which will be used at this installation step.
## Optional properties

View file

@ -25,7 +25,7 @@ This is an [AddonScript object](addonscript.md) containing information about the
This is the ID of the addon.
It should be written in the `kebab-case` format, meaning lowercase only and using `-` instead of spaces.
It MUST only contains lowercase alphanumeric characters and hyphens and SHOULD be written in the `kebab-case` format.
### version
@ -45,7 +45,7 @@ This is an [flags object](flags.md) which contains [manifest flags](../concepts/
### semver
This is the version number of this version in semver format. It must follow the [semver versioning specifications](https://semver.org/spec/v2.0.0.html).
This is the version number of this version in semver format. It MUST follow the [semver versioning specifications](https://semver.org/spec/v2.0.0.html).
### files

View file

@ -41,17 +41,17 @@ This object can contain any arbitrary data,
### name
The full, human-readable name of the addon. This is what a program such as a launcher should
The full, human-readable name of the addon. This is what a program such as a launcher SHOULD
display to the user.
### icon
A [link](../concepts/links.md) to the icon of the addon. This path should point to an image file of small resolution
which is ideally square. It can be dispayed to users in programs.
A [link](../concepts/links.md) to the icon of the addon. This path SHOULD point to an image file of small resolution
which is ideally square. It MAY be dispayed to users in programs.
### description
A [link](../concepts/links.md) to a description file for the addon. The file should be in CommonMark markdown.
A [link](../concepts/links.md) to a description file for the addon. The file SHOULD be in CommonMark markdown.
### summary
@ -75,7 +75,8 @@ The type of the addon, for example `mod`, `modpack` or `resourcepack`.
### contributors
An array of people who have contributed to the addon.
An array of people who have contributed to the addon. Each contributor is represented by an object, which
MUST have a `name` and a `email` property.
# Version Meta Object

View file

@ -26,7 +26,7 @@ This is the [namespace](../concepts/namespaces.md) of the related addon. This pr
### version
This is a [maven version range](../concepts/versioning.md#dependancy-version-requirement-specification) that specifies, which versions
of the related addon are targeted by this relation. You can either set this property or `semver`, but exactly one of them has to be set.
of the related addon are targeted by this relation. You can either set this property or `semver`, but exactly one of them MUST be set.
### semver
@ -35,9 +35,9 @@ It will only allow versions of the related addon, which have a valid semver vers
### repositories
This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript should try to get this relation from,
This is an array of [repository](repository.md) IDs. These are the repositories, from which AddonScript will try to get this relation from,
in the order as they are specified in the array. If this property is not set or the array is empty, AddonScript will try to resolve the relation by
the namespace from all defined repositories.
the namespace from all [defined repositories](manifest.md#repositories).
### flags

View file

@ -11,7 +11,7 @@
### id
This is the ID of the repository. It has to be unique to the AddonScript file.
This is the ID of the repository. It MUST be unique in the [manifest](manifest.md).
### url