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

Reviewed-on: addonscript/addonscript-spec#24

docs/api/README.md

@@ -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:

docs/api/features/addons.md

@@ -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.

docs/api/features/files.md

@@ -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.

docs/concepts/flags.md

@@ -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`.

docs/concepts/install.md

@@ -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

docs/concepts/instance.md

@@ -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.

docs/concepts/links.md

@@ -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)

docs/concepts/namespaces.md

@@ -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. 

docs/concepts/versioning.md

@@ -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
 

docs/packaging/zip.md

@@ -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

docs/schema/api_addon.md

@@ -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
 

docs/schema/api_file.md

@@ -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).

docs/schema/file.md

@@ -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
 

docs/schema/install.md

@@ -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
 

docs/schema/manifest.md

@@ -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
 

docs/schema/meta.md

@@ -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
 

docs/schema/relation.md

@@ -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
 

docs/schema/repository.md

@@ -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