basic namespace spec

docs/api/README.md

@@ -6,7 +6,7 @@
 
 The index endpoint can be used to get basic information about an API
 instance, including the API versions and features supported by that
-instance and the default namespace of the instance. 
+instance and the default [namespace](../concepts/namespaces.md) of the instance. 
 
 #### Example response body:
 
@@ -23,12 +23,12 @@ instance and the default namespace of the instance.
 ### `GET {base URL}/v1/addons/:namespace/:addon`
 
 This endpoint can be used to retrieve information about a specific addon,
-including metadata, all available versions and the canonical namespace of
-the addon. 
+including metadata, all available versions and the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) 
+of the addon. 
 
 #### Path variales:
 
-- `namespace`: The namespace which contains the addon
+- `namespace`: A [namespace](../concepts/namespaces.md) which contains the addon
 - `addon`: The ID of the addon
 
 #### Example response body:
@@ -48,7 +48,7 @@ the addon.
 ```
 
 The [meta object](../schema/meta.md) is the same as in the AddonScript files,
-exept, that it only includes `addon` and `additional` metadata and not `version`
+except, that it only includes `addon` and `additional` metadata and not `version`
 specific metadata.
 
 ### `GET {base URL}/v1/addons/:namespace/:addon/:version`

docs/concepts/namespaces.md

@@ -1 +1,26 @@
 # Namespaces
+
+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
+(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
+namespace, which is defined in the [addon object](../schema/addon.md#namespace).
+An [API instance](../api/README.md) must also return the canonical namespace of 
+the addon on the [addon endpoint](../api/README.md#get-base-urlv1addonsnamespaceaddon)
+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.
+
+## Default Namespaces
+
+Each [API instance](../api/README.md) has a default namespace. Addons in the 
+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/schema/addon.md

@@ -33,6 +33,10 @@ This is the [version number](../concepts/versioning.md) of this version. Version
 [Maven version order rules](../concepts/versioning.md#version-order-specification).
 If this version number is valid semver, the `semver` property is implicitly equal to `version` if `semver` was not explicitly set.
 
+### namespace
+
+This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the addon.
+
 ### flags
 
 This is an array of [flags](../concepts/flags.md) for this version.
@@ -43,11 +47,6 @@ This is an array of [flags](../concepts/flags.md) for this version.
 
 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).
 
-### namespace
-
-This is the [namespace](../concepts/namespaces.md) of the addon, which should be in a reversed domain name format. 
-Used to identify addons across repositories.
-
 ### files
 
 This is an array of [file objects](file.md) including the files belonging to this addon.