feat: add did doc registration and align well-known version endpoint (#122)

Author: arnoweiss

artifacts/src/main/resources/catalog/catalogservice-did-service-schema.json

@@ -0,0 +1,48 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema",
+  "title": "CatalogServiceDidServiceSchema",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "#/definitions/CatalogServiceDidService"
+    }
+  ],
+  "$id": "https://w3id.org/dspace/2025/1/catalog/catalogservice-did-service-schema.json",
+  "definitions": {
+    "CatalogServiceDidService": {
+      "type": "object",
+      "properties": {
+        "@context": {
+          "allOf": [
+            {
+              "$ref": "https://w3id.org/dspace/2025/1/common/context-schema.json"
+            },
+            {
+              "type": "array",
+              "contains": {
+                "type": "string",
+                "const": "https://www.w3.org/ns/did/v1"
+              }
+            }
+          ]
+        },
+        "type": {
+          "type": "string",
+          "const": "CatalogService"
+        },
+        "id": {
+          "type": "string"
+        },
+        "serviceEndpoint": {
+          "type": "string",
+          "pattern": "https?://.*?/catalog$"
+        }
+      },
+      "required": [
+        "id",
+        "type",
+        "serviceEndpoint"
+      ]
+    }
+  }
+}

artifacts/src/main/resources/catalog/example/catalogservice-did-service.json

@@ -0,0 +1,9 @@
+{
+  "@context": [
+    "https://w3id.org/dspace/2025/1/context.jsonld",
+    "https://www.w3.org/ns/did/v1"
+  ],
+  "id":"some:id",
+  "type": "CatalogService",
+  "serviceEndpoint": "https://bar.example.com/some/path/catalog"
+}

artifacts/src/main/resources/context/dspace.jsonld

@@ -427,6 +427,17 @@
         }
       }
     },
+    "CatalogService": {
+      "@id":"dspace:CatalogService",
+      "@context": {
+        "id": "@id",
+        "type": "@type",
+        "serviceEndpoint": {
+          "@id": "https://www.w3.org/ns/did#serviceEndpoint",
+          "@type": "@id"
+        }
+      }
+    },
     "ACCEPTED": "dspace:ACCEPTED",
     "FINALIZED": "dspace:FINALIZED",
     "REQUESTED": "dspace:REQUESTED",

specifications/catalog/catalog.protocol.md

@@ -157,3 +157,13 @@ upstream [=Catalog Services=] and advertises their
 respective [=Catalogs=] as a
 single [=Catalog Service=]. The broker is expected to honor upstream access
 control requirements.
+
+### Discovery of [=Catalog Services=]
+
+A Participant may publicize their [=Catalog Service=] via a DID document, see [[?did-core]]. In that case, the 
+Participant MUST add an entry to the DID document's `service` array adhering to the corresponding [JSON schema](message/schema/catalogservice-did-service-schema.json).
+
+<aside class="example" title="Catalog Service Did Service Example">
+    <pre class="json" data-include="message/example/catalogservice-did-service.json">
+    </pre>
+</aside>

specifications/common/common.protocol.md

@@ -8,41 +8,50 @@ does not require authorization.
 
 ## Schemas & Contexts
 
-All protocol [=Messages=] are normatively defined by a [[json-schema]]. This specification also uses JSON-LD 1.1 and provides
-a JSON-LD context to serialize data structures and [=Message=] types as it facilitates extensibility. The JSON-LD context is
-designed to produce [=Message=] serializations using compaction that validate against the Json Schema for the given [=Message=]
-type. This allows implementations to choose whether to process [=Messages=] as plain JSON or as JSON-LD and maintain
-interoperability between those approaches. Extensions that use JSON-LD are encouraged to provide similar contexts that
-facilitate this approach to interoperability.
+All protocol [=Messages=] are normatively defined by a [[json-schema]]. This specification also uses JSON-LD 1.1 and
+provides a JSON-LD context to serialize data structures and [=Message=] types as it facilitates extensibility. The
+JSON-LD context is designed to produce [=Message=] serializations using compaction that validate against the Json Schema
+for the given [=Message=] type. This allows implementations to choose whether to process [=Messages=] as plain JSON or
+as JSON-LD and maintain interoperability between those approaches. Extensions that use JSON-LD are encouraged to provide
+similar contexts that facilitate this approach to interoperability.
 
 ## Exposure of Versions {#exposure-of-dataspace-protocol-versions}
 
 ### Generic Definition
 
-[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions. Therefore, it is necessary that
-they can discover the supported versions of each other reliably and unambiguously. Each [=Connector=] must expose
-information of at least one Dataspace Protocol Version it supports. The specifics of how this information is obtained
+[=Connectors=] implementing the [=Dataspace Protocol=] may operate on different versions. Therefore, it is necessary
+that they can discover the supported versions of each other reliably and unambiguously. Each [=Connector=] must expose
+information of at least one Dataspace Protocol version it supports. The specifics of how this information is obtained
 its defined by specific protocol bindings.
 
 A [=Connector=] must respond to a respective request by providing a JSON object containing an array of supported
 versions with at least one item. The item connects the version tag (`version` attribute) with the absolute URL path
-segment of the root path for all endpoints of this version. The following example specifies that this [=Connector=]
-offers version `1.0` endpoints at `<host>/some/path/v1`.
+segment of the domain-only path for all endpoints of this version. The following example specifies that
+this [=Connector=] offers version `2024-1` endpoints at `<host>/some/path/2024-1`, the `2025-1` endpoints at
+`<host>/some/path/2025-1` and another [=Connector=] on the same host under `<host>/different/path/2025-1`.
 
 ```json
 {
   "protocolVersions": [
     {
-      "version": "1.0",
-      "path": "/some/path/v1"
+      "version": "2024-1",
+      "path": "/some/path/2024-1"
+    },
+    {
+      "version": "2025-1",
+      "path": "/some/path/2025-1"
+    },
+    {
+      "version": "2025-1",
+      "path": "/different/path/2025-1"
     }
   ]
 }
 ```
 
-This data object must comply to the [JSON Schema](message/schema/protocol-version-schema.json). The requesting [=Connector=] may select
-from the endpoints in the response. If the [=Connector=] can't identify a matching Dataspace Protocol Version, it must
-terminate the communication.
+This data object must comply to the [JSON Schema](message/schema/protocol-version-schema.json). The requesting
+[=Connector=] may select from the endpoints in the response. If the [=Connector=] can't identify a matching Dataspace
+Protocol Version, it must terminate the communication.
 
 ### HTTPS Binding
 
@@ -55,9 +64,5 @@ Resource Identifier [[rfc8615]] at the top of the path hierarchy:
 /.well-known/dspace-version
 ```
 
-The contents of the response is a JSON object defined in section [[[#exposure-of-dataspace-protocol-versions]]].
-
-Note that if multiple [=Connectors=] are hosted under the same base URL, a path segment appended to the base well-known
-URL can be used, for example, `https://example.com/.well-known/dspace-version/connector1.`
-
-The version endpoint MUST be unprotected and unversioned.
+The contents of the response is a JSON object defined in section [[[#exposure-of-dataspace-protocol-versions]]]. The
+version endpoint MUST be unversioned and unauthenticated.