diff --git a/IETF-RFC.md b/IETF-RFC.md index aba1aa3..c8d977f 100644 --- a/IETF-RFC.md +++ b/IETF-RFC.md @@ -511,6 +511,8 @@ contain the following information about its OCM API: this endpoint. Example: `"https://my-cloud-storage.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 @@ -1171,15 +1173,15 @@ format: Servers exposed by the Directory Service * REQUIRED: `servers` - a JSON array of objects to describe the list of OCM Servers with the following string fields: - - REQUIRED: `url` - an absolute URL identifying the + * REQUIRED: `url` - an absolute URL identifying the OCM Server. It MUST: - - include scheme: either `https://` or + * include scheme: either `https://` or (for testing purposes) `http://` - - include host (either a FQDN or an IP address) - - MAY include a non-default port - - MUST NOT include a base path (e.g., `/ocm`) - - MUST NOT include userinfo, query, or fragment - - REQUIRED: `displayName` - a human-readable name + * include host (either a FQDN or an IP address) + * MAY include a non-default port + * MUST NOT include a base path (e.g., `/ocm`) + * MUST NOT include userinfo, query, or fragment + * REQUIRED: `displayName` - a human-readable name for the OCM Server Example: @@ -1203,6 +1205,94 @@ format: } ``` +# 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` - an public URL that can be used for + direct download via anonymous HTTP GET + * OPTIONAL: `rocrate` - an embedded JSON object following the + [ROCRATE](https://www.researchobject.org/ro-crate/specification/1.1/data-entities.html) + data-entities specification. + * REQUIRED: `providerId` - 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 Our deepest thanks and appreciation go to the people who started the diff --git a/spec.yaml b/spec.yaml index 833517f..c701d56 100644 --- a/spec.yaml +++ b/spec.yaml @@ -336,6 +336,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: |