Make DRS compatible with RO-crates

[sveinugu]

This is a small writeup of the idea that was presented in the Cloud work stream meeting May 12:

• The context where this came up was the "FAIRification of Genomic Annotations WG (FGA-WG)" in Research Data Alliance (RDA)

  • One of the goals of the WG is to define a minimal metadata model that can be used to harmonise metadata pertaining to genomic annotations/tracks from various sources. This includes entities that describes experiments, samples, etc. As one of the entities, we would like to describe data files that in most cases are located remotely in relation to the harmonised metadata.
  • Related GitHub issue in the FGA-WG repo: Align Annotation schema with GA4GH DRS standards or other standard for data access

• One idea is to adopt and reuse the DRS data model, but not the API. Advantages:

  • The DRS schema includes a number of fields that makes sense for us to include.
  • Importantly, the DRS schema includes the possibility of defining multiple access points for the same file, using different protocols
  • Makes more sense to lean on the work that has been done to define the schema instead of creating our own
  • Allows a DRS server to be easily implemented, as the required metadata is already there
  • Also allows for a DRS URI to be added, if available
  • Draft of the harmonised metadata model (under development), adopting DRS entities (from File entity, row 40)

• Another idea was to align with Research Object Crate (RO-Crate), which is gaining use, esp. in Europe.

  • RO-Crate is based on JSON-LD v1.0 and Schema.org vocabulary
  • Part of the larger infrastructure of tools and services for linked data, knowledge networks, etc.
  • Important in ELIXIR, EOSC, etc.
  • Being supported by scientific journals, databases etc.

• We discussed both possibilities in a WG meeting May 6. Here, Nathan Sheffield introduced the DRS, and its data mode, and Eli Chadwick introduced Research Object Crate (RO-Crate) community standard.

  • Out of this came a recognition that the two standards operate on different levels. RO-create is a higher-level specification, within which one can define RO-Crate profiles.

• So the current idea is whether the DRS data model could be made RO-Crate compatible?

[sveinugu]

First question is to figure out what is needed to do this. I am relatively new to linked data, so this might be inaccurate, but I believe this would include the following:

• Describe the DRS data model in a way that are compatible with linked data, and schema.org in particular. Mainly, this would include mapping each field name to terms in schema.org.
• For fields that have no natural mapping, one would need to define an IRI to describe the contents.
• Figure out how to maintain interoperability with DRS field names in parallel to schema.org counterparts.
• Figure out what is needed to define a RO-Crate profile.

[egchristensen]

@briandoconnor and @MichaelLukowski ☝

[vsmalladi]

What Would "DRS ↔ RO-Crate Compatible" Likely Require?

1. DRS Metadata Extended with JSON-LD / schema.org Context

DRS currently serves metadata specific to data retrieval endpoints. To conform to RO-Crate, it would need to:

• Provide JSON-LD responses embedding schema.org context.
• Possibly include terms such as @context, @graph, @id, and relevant types like Dataset, File, and relevant hasPart links—as defined in RO-Crate's spec researchobject.org.

2. Expose RO-Crate Metadata Document Over DRS

DRS servers might serve a ro-crate-metadata.json (or similar) endpoint that clients can fetch, effectively delivering an RO-Crate’s manifest for one or more objects.

3. Support for Packaging/Unpackaging

Allow clients to request objects bundled as RO-Crate, e.g., via an endpoint like /objects/{id}/bundle?format=ro-crate, or allow uploading RO-Crate packages which DRS would unpack and register.

4. Mapping Access Methods to RO-Crate Structures

DRS's access_methods (e.g., https, gs, etc.) could be encoded into the encodingFormat, contentUrl or similar schema.org properties in the RO-Crate metadata.

5. Ensure Identifiers and Self-Description

RO-Crate mandates identifiers such as @id (often the filename ro-crate-metadata.json) and root entity descriptions [researchobject.org](https://www.researchobject.org/ro-crate/specification/1.2/appendix/changelog.html. DRS could include metadata aligning to that structure to ensure self-description and discoverability.

6. Optional Profiles or Extensions

RO-Crate supports Profiles—targeted metadata subsets for domains like workflows or datasets researchobject.org. If DRS has usage in a workflow context, integrating into corresponding RO-Crate profiles could be beneficial.

# Insert this under top-level `paths:` in the OpenAPI YAML (add to other server docs as desired).
paths:
  /objects/{object_id}/ro-crate:
    get:
      summary: "Retrieve an RO-Crate metadata document describing this object (optional extension)"
      operationId: getObjectRoCrate
      tags:
        - ro-crate
      description: |
        Optional endpoint that returns an RO-Crate metadata document (JSON-LD @graph)
        describing the requested DRS object and any contained parts. This endpoint is
        optional for DRS servers. Servers advertising RO-Crate support MUST document
        that support in service-info (see `x-ro-crate-support` example).
      parameters:
        - name: object_id
          in: path
          required: true
          schema:
            type: string
          description: "DRS object identifier"
        - name: accept
          in: header
          required: false
          schema:
            type: string
          description: |
            Clients MAY request `application/ld+json; profile="https://w3id.org/ro/crate/1.2/context"`
            to explicitly request RO-Crate JSON-LD. Servers may also honour default JSON requests.
      responses:
        '200':
          description: "RO-Crate Metadata Document (JSON-LD) describing the crate and its data entities"
          content:
            application/ld+json; profile="https://w3id.org/ro/crate/1.2/context":
              schema:
                $ref: '#/components/schemas/ROCrateMetadata'
              examples:
                simpleCrate:
                  summary: "Single-file crate example"
                  value:
                    "@context": "https://w3id.org/ro/crate/1.2/context"
                    "@graph":
                      - "@id": "./"
                        "@type": "Dataset"
                        "name": "DRS object crate for example-file.bam"
                        "description": "RO-Crate manifest for DRS object example-file.bam"
                        "hasPart":
                          - "@id": "drs://example.org/objects/abcdef12345"
                      - "@id": "drs://example.org/objects/abcdef12345"
                        "@type": "File"
                        "name": "example-file.bam"
                        "encodingFormat": "application/octet-stream"
                        "contentSize": 123456789
                        "contentUrl":
                          - "@id": "https://drs.example.org/objects/abcdef12345/data?protocol=https"
                            "name": "HTTPS access URL"
                        "checksum":
                          - "@type": "Checksum"
                            "algorithm": "sha256"
                            "value": "0123456789abcdef..."
        '401':
          description: "Not authenticated / credentials required"
        '403':
          description: "Authenticated but not authorized to view or export the crate"
        '404':
          description: "Object not found"

  /objects/{object_id}/bundle:
    get:
      summary: "Download an Attached RO-Crate (zip) for the object (optional)"
      operationId: getObjectRoCrateBundle
      tags:
        - ro-crate
      description: |
        Optional endpoint that returns an attached RO-Crate archive (zip) containing
        `ro-crate-metadata.json` at the archive root and, optionally, included files.
        Servers may choose to include file payloads or reference remote URLs in the metadata.
      parameters:
        - name: object_id
          in: path
          required: true
          schema:
            type: string
        - name: format
          in: query
          required: false
          schema:
            type: string
            enum: ['ro-crate', 'zip']
            default: 'ro-crate'
          description: "Requested bundle format. 'ro-crate' requests an RO-Crate zip archive."
      responses:
        '200':
          description: "Attached RO-Crate zip archive containing ro-crate-metadata.json"
          content:
            application/zip; profile="ro-crate/1.2":
              schema:
                type: string
                format: binary
        '401':
          description: "Not authenticated"
        '403':
          description: "Authenticated but not authorized"
        '404':
          description: "Object not found"

# Optional: advertise support through extended service-info or server metadata.
# This is not required, but recommended for discovery.
# Add an `x-ro-crate-support` in top-level `info` or in `/service-info` responses if present.

components:
  schemas:
    # Minimal documentation-only schema for RO-Crate Metadata (free-form JSON-LD)
    ROCrateMetadata:
      title: "ROCrateMetadata"
      description: "A JSON-LD document conforming to RO-Crate 1.2 (represented as an object)."
      type: object
      additionalProperties: true
      example:
        "@context": "https://w3id.org/ro/crate/1.2/context"
        "@graph": [
          {
            "@id": "./",
            "@type": "Dataset",
            "name": "DRS object crate for example-file.bam",
            "hasPart": [
              { "@id": "drs://example.org/objects/abcdef12345" }
            ],
            "publisher": { "@type": "Organization", "name": "Example DRS Service" }
          },
          {
            "@id": "drs://example.org/objects/abcdef12345",
            "@type": "File",
            "name": "example-file.bam",
            "encodingFormat": "application/octet-stream",
            "contentSize": 123456789,
            "contentUrl": [
              { "@id": "https://drs.example.org/objects/abcdef12345/data?protocol=https" }
            ],
            "checksum": [
              { "@type": "Checksum", "algorithm": "sha256", "value": "0123456789abcdef..." }
            ]
          }
        ]

# Example vendor extension for service discovery (optional)
# Add 'x-ro-crate-support' under the server's service-info or top-level info to advertise capability:
# info:
#   title: "Example DRS service"
#   x-ro-crate-support:
#     version: "1.2"
#     bundle_endpoint: "/objects/{object_id}/bundle"
#     metadata_endpoint: "/objects/{object_id}/ro-crate"
#     notes: "Servers should attach only non-sensitive metadata; do not embed secrets."
# --- End RO-CRATE Extension Snippet ---

[briandoconnor]

Some initial questions/thought:

• would be a good example of how we handle "optional" extensions to our APIs? Would this start as an optional representation in our schema?
• is this a bundle replacement?