From 61ff1386cdb6284089055c696c69e098ffed7f12 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 13 Jun 2025 09:40:17 +0200 Subject: [PATCH 1/3] ResourceDiscovery: This patch adds a new resource discovery mechanism. The intention is to allow for a way to advertise the existence of resources at the OCM server. Signed-off-by: Micke Nordin --- IETF-RFC.md | 95 +++++++++++++++++++++++++++++++++++++++++++++++++++++ spec.yaml | 4 +++ 2 files changed, 99 insertions(+) diff --git a/IETF-RFC.md b/IETF-RFC.md index a8d1dea..2420a44 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -668,6 +668,9 @@ contain the following information about its OCM API: this endpoint. Example: `"https://cloud.example.org/ocm"` * OPTIONAL: provider (string) - A friendly branding name of this endpoint. Example: `"MyCloudStorage"` +* OPTIONAL: resourceAdvertismentUri (string) - A URI that, + if accessed, will advertise available resources at this + endpoint. * REQUIRED: resourceTypes (array) - A list of all resource types this server supports in both the Sending Server role and the Receiving Server role, with their access protocols. Each item in this list @@ -1398,6 +1401,10 @@ Signatures](https://tools.ietf.org/html/rfc9421)", February 2024. Representation of Contact Data]( https://datatracker.ietf.org/doc/html/rfc9553), May 2024" +[ROCRATE] Soiland-Reyes, S. et al., "[RO-Crate +specification 1.1 - Data Entities]( +https://www.researchobject.org/ro-crate/specification/1.1/data-entities.html)" + # Appendix A: Multi-factor Authentication @@ -1966,6 +1973,94 @@ The complete changelog is updated in the OCM-API GitHub repository. * Added JSContact extension to IANA Considerations. * Changed example domain to use cloud.example.org per RFC 2606. +# Appendix D: Resource Discovery Service + +An OCM Server MAY publicly advertise available resources. +This is done via the `resourceAdvertismentUri`. It is +expected to expose, via anonymous HTTP GET, a JSON document +with the following format: + + * REQUIRED: `server` - a human-readable name for the + Servers providing the Resource Discovery Service + * REQUIRED: `resources` - a JSON array of objects to + describe the list of OCM Servers with the following + fields: + * OPTIONAL: `displayName` - the human-readable name + of the OCM Server + * OPTIONAL: `publicUrl` - a public URL that can be + used for direct download via anonymous HTTP GET + * OPTIONAL: `rocrate` - an embedded JSON object + following the [ROCRATE] data-entities + specification. + * REQUIRED: `id` - the unique identifier of the + resource at the OCM Server + Example: + ```json + { + "server": "OCM Server 1", + "resources": [ + { + "publicUrl": "https://ocm-server-1.fqdn/s/1234567890abcdef", + "displayName": "Public Dataset 1", + "id": "1234567890abcdef", + "rocrate": { + "@context": "https://w3id.org/ro/crate/1.1/context", + "@graph": [ + { + "@id": "ro-crate-metadata.json", + "@type": "CreativeWork", + "conformsTo": { + "@id": "https://w3id.org/ro/crate/1.1" + }, + "about": { + "@id": "./" + } + }, + { + "@id": "./", + "@type": "Dataset", + "name": "A RO-Crate embedded in OCM" + }, + { + "@id": "https://ocm-server-1.fqdn/s/1234567890abcdef", + "@type": "File", + "name": "Public data file" + } + ] + } + }, + { + "displayName": "Private Data Set 1", + "id": "0987654321fedcba", + "rocrate": { + "@context": "https://w3id.org/ro/crate/1.1/context", + "@graph": [ + { + "@id": "ro-crate-metadata.json", + "@type": "CreativeWork", + "conformsTo": { + "@id": "https://w3id.org/ro/crate/1.1" + }, + "about": { + "@id": "./" + } + }, + { + "@id": "./", + "@type": "Dataset", + "name": "A RO-Crate embedded in OCM" + }, + { + "@id": "0987654321fedcba", + "@type": "File", + "name": "Private data file" + } + ] + } + } + ] + } +``` # Acknowledgements diff --git a/spec.yaml b/spec.yaml index f1fa552..123e7d7 100644 --- a/spec.yaml +++ b/spec.yaml @@ -308,6 +308,10 @@ components: type: string description: A friendly branding name of this endpoint example: MyCloudStorage + resourceadvertismenturi: + type: string + description: the uri of the ocm resources advertised at this endpoint + example: https://my-cloud-storage.org/ocm/resources resourceTypes: type: array description: | From 0b4b62c6eef70854eb29054c5b842623fea45085 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Fri, 22 Aug 2025 17:07:46 +0200 Subject: [PATCH 2/3] Update IETF-RFC.md Co-authored-by: Mahdi Baghbani --- IETF-RFC.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index 2420a44..f75a6d2 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -1992,8 +1992,8 @@ with the following format: * OPTIONAL: `rocrate` - an embedded JSON object following the [ROCRATE] data-entities specification. - * REQUIRED: `id` - the unique identifier of the - resource at the OCM Server + * REQUIRED: `providerId` - the unique identifier + of the resource at the OCM Server Example: ```json { From 5a9ec438c56139a6c5dbb717b8c131f972280923 Mon Sep 17 00:00:00 2001 From: Micke Nordin Date: Thu, 26 Mar 2026 14:46:56 +0100 Subject: [PATCH 3/3] Align with new additons to the spec, especially signing --- IETF-RFC.md | 13 ++++++++----- spec.yaml | 2 +- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/IETF-RFC.md b/IETF-RFC.md index f75a6d2..a6ab31b 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -1973,12 +1973,15 @@ The complete changelog is updated in the OCM-API GitHub repository. * Added JSContact extension to IANA Considerations. * Changed example domain to use cloud.example.org per RFC 2606. -# Appendix D: Resource Discovery Service +# Appendix E: Resource Discovery Service An OCM Server MAY publicly advertise available resources. This is done via the `resourceAdvertismentUri`. It is -expected to expose, via anonymous HTTP GET, a JSON document -with the following format: +expected to expose, via anonymous HTTPS GET, a signed JWS +document [RFC7515], where the signing key MUST be made +available via the `/.well-known/jwks.json` of the +advertising server and the payload MUST adhere to the +following format: * REQUIRED: `server` - a human-readable name for the Servers providing the Resource Discovery Service @@ -2000,7 +2003,7 @@ with the following format: "server": "OCM Server 1", "resources": [ { - "publicUrl": "https://ocm-server-1.fqdn/s/1234567890abcdef", + "publicUrl": "https://cloud.example.org/s/1234567890abcdef", "displayName": "Public Dataset 1", "id": "1234567890abcdef", "rocrate": { @@ -2022,7 +2025,7 @@ with the following format: "name": "A RO-Crate embedded in OCM" }, { - "@id": "https://ocm-server-1.fqdn/s/1234567890abcdef", + "@id": "https://cloud.example.org/s/1234567890abcdef", "@type": "File", "name": "Public data file" } diff --git a/spec.yaml b/spec.yaml index 123e7d7..0dc6271 100644 --- a/spec.yaml +++ b/spec.yaml @@ -311,7 +311,7 @@ components: resourceadvertismenturi: type: string description: the uri of the ocm resources advertised at this endpoint - example: https://my-cloud-storage.org/ocm/resources + example: https://cloud.example.org/ocm/resources resourceTypes: type: array description: |