Namespace and repository overhaul

docs/api/README.md

@@ -9,10 +9,8 @@ instance, including the API versions and features supported by that
 instance and the [default namespace](../concepts/namespaces.md#default-namespaces) of the instance. 
 The response object of this endpoint contains a `versions` property, which is an object with API
 version numbers as keys and the configuration objects for the specific API version as values.
-For API version `v2` (AddonScript major release 2) the configuration object contains a `default_namespace`
-property, which is the [default namespace](../concepts/namespaces.md#default-namespaces) of the API
-instance, and a `features` property, which is an array containing all [API features](#features)
-available on this API instance.
+For API version `v2` (AddonScript major release 2) the configuration object contains a `features` 
+property, which is an array containing all [API features](#features) available on this API instance.
 
 ### Example response body:
 
@@ -20,8 +18,7 @@ available on this API instance.
 {
     "versions": {
         "v2": {
-            "default_namespace": "com.example",
-            "features": ["listing", "filters", "com.example.customfeature"]
+            "features": ["addons", "env", "com.example.customfeature"]
         }
     }
 }

docs/api/features/addons.md

@@ -12,7 +12,7 @@ of the addon.
 
 #### Path variales:
 
-- `namespace`: A [namespace](../../concepts/namespaces.md) which contains the addon
+- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
 - `addon`: The ID of the addon
 
 #### Responses:
@@ -29,7 +29,7 @@ This endpoint can be used to retrieve the manifest of a specific version of an a
 
 #### Path variables:
 
-- `namespace`: The namespace which contains the addon
+- `namespace`: The [namespace](../../concepts/namespaces.md#repository-namespaces) of a repository which contains the addon
 - `addon`: The ID of the addon
 - `version`: The [version number](../../concepts/versioning.md) of the requested version
 
@@ -37,4 +37,15 @@ This endpoint can be used to retrieve the manifest of a specific version of an a
 
 - `200 OK`: This version of the addon is available in this addon repository.
 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.
+- `404 Not Found`: This version of the addon is not available in this addon repository.
+
+### Get namespaces
+
+`GET {base URL}/v2/namespaces` 
+
+This endpoint can be used to get a list of [repository namespaces](../../concepts/namespaces.md#repository-namespaces),
+which can be found on this API instance. It MAY be incomplete or empty at all. 
+
+#### Responses:
+
+- `200 OK`: The response body MUST be a JSON array of namespace strings.

docs/concepts/namespaces.md

@@ -1,6 +1,7 @@
 # Namespaces
 
-Namespaces are used in conjunction with addon IDs to uniquely identify an addon.
+Namespaces are used in conjunction with addon IDs to uniquely identify an addon as well as
+an identifier for repositories.
 
 ## Format
 
@@ -9,18 +10,24 @@ They SHOULD be in a reversed domain name format. A namespace SHOULD specify the
 (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`).
 
+## Repository Namespaces
+
+A repository namespace describes an addon repository across [API instances](../api/). A repository
+contains different addons and MAY be hosted on multiple API instances (mirrors). The ID of an addon
+MUST be unique in a repository, so an addon can be resolved by the addon ID in conjuction with the
+repository namespace. Since the same addon MAY be contained in multiple repositories, it MUST have a
+[canonical namespace](#canonical-namespaces), so it can be identified globally. The repository
+described by the canonical namespace of an addon MUST also contain that addon. If different API
+instances return contradicting information about a repository, for example an addon with the same
+ID in the same repository has different canonical namespaces on different instances, the AddonScript
+implementation decides, which instance is more trustworthy. This MAY be done by comparing the
+repository namespace to the API URL or by asking the user.
+
 ## Canonical Namespaces
 
-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).
+While an addon MAY be included in multiple repository 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 
 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, 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
-are no ID conflicts in the repository. The default namespace does not need
-to be the canonical namespace of these addons. 
+even if the addon was requested from another repository namespace. To check, if two addons
+are the same addon, their canonical namespace and their ID MUST be equal.

docs/schema/manifest.md

@@ -52,7 +52,8 @@ This is an array of [relation objects](relation.md) which represent addons in re
 ### repositories
 
 This is an array of [repository objects](repository.md). Each repository object defines one repository from which files or
-addons can be retrieved.
+addons can be retrieved. Each AddonScript manifest SHOULD have a repository for the [canonical namespace](#namespace) of 
+that manifest, from which AddonScript implementations MAY check for updates for this addon.
 
 ### env_api
 

docs/schema/relation.md

@@ -25,14 +25,15 @@ of the related addon are targeted by this relation.
 
 ### namespace
 
-This is the [namespace](../concepts/namespaces.md) of the related addon. This property will be implicitly equal to the 
-[namespace of the addon](manifest.md#namespace), if it was not set explicitly.
+This is the [canonical namespace](../concepts/namespaces.md#canonical-namespaces) of the related addon. If this property is not set,
+AddonScript will resolve the namespace via the [addon endpoint](../api/features/addons.md#get-addon) of a [repository](#repositories).
 
 ### repositories
 
-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](manifest.md#repositories).
+This is an array of [repository namespaces](repository.md#namespace). 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 from
+the repository described by the [manifest namespace](manifest.md#namespace). The repository described the the [canonical namespace](#namespace) of this
+relation has always precedence before these repositories.
 
 ### flags
 

docs/schema/repository.md

@@ -2,17 +2,20 @@
 
 ```json
 {
-  "id": "asrepo",
-  "url": "https://api.addonscript.net"
+  "namespace": "net.addonscript",
+  "instances": ["https://api.addonscript.net"]
 }
 ```
 
 ## Required properties
 
-### id
+### namespace
 
-This is the ID of the repository. It MUST be unique in the [manifest](manifest.md).
+This is the [namespace](../concepts/namespaces.md), which describes this repository.
 
-### url
+### instances
 
-This is the base URL of an [AddonScript API](../api) instance.
+This is an array of base URLs of [AddonScript API](../api) instances, on which this
+repository can be found. To get an addon from this repository, AddonScript will
+try to get it from the [addon endpoint](../api/features/addons.md#get-addon)
+of these API instances in the order, in which they are specified in this array.