RO-Crate profiles

While RO-Crates can be considered general-purpose containers of arbitrary data and open-ended metadata, in practical use within a particular domain, application or framework, it will be beneficial to further constrain RO-Crate to a specific profile: a set of conventions, types and properties that one minimally can require and expect to be present in that subset of RO-Crates.

Defining and conforming to such a profile enables reliable programmatic consumption of an RO-Crate’s content, as well as consistent creation, e.g. a form in a user interface containing the required types and properties, and likewise a rendering of an RO-Crate can easier make rich UI components if it can reliably assume for instance that the Person always has an affiliation to a Organization which has a url - a restriction that may not be appropriate for all types of RO-Crates.

As such RO-Crate Profiles can be considered a duck typing mechanism for RO-Crates, but also as a classifier to indicate the crate’s purpose, expectations and focus.

Publishing an RO-Crate profile

An RO-Crate profile is identified with a Profile URI.

Recommendations:

• The profile URI MUST resolve to a human-readable profile description (e.g. a HTML web page)
  • The profile URI MAY have a corresponding machine-readable Profile Crate
• The profile URI SHOULD be a permalink (persistent identifier)
  • e.g. starting with https://w3id.org/ http://purl.org/ or https://doi.org/
• The profile URI SHOULD be versioned with MAJOR.MINOR, e.g. http://example.com/image-profile-2.4
• The profile description SHOULD use key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL as described in RFC 2119.

Suggestions:

• The profile MAY require/suggest which @type of data entities and/or contextual entities are expected.
• The profile MAY require/suggest properties expected per type of entity (e.g. “Each CreativeWork must declare a license“)
• The profile MAY require/suggest a particular version of RO-Crate.
• The profile MAY recommend RO-Crate extensions with domain-specific terms and vocabularies.
• The profile MAY require/suggest a particular JSON-LD context.
• The profile MAY require/suggest a particular RO-Crate publishing method or packaging like .zip or BagIt.

Declaring conformance of an RO-Crate profile

RO-Crate can describe a profile by adding it as an contextual entity:

{
    "@id": "https://w3id.org/ro/wfrun/process/0.4",
    "@type": ["CreativeWork", "Profile"],
    "name": "Process Run crate profile",
    "version": "0.4.0"
}

The contextual entity for a profile:

• The @type SHOULD be an array. The @type MUST include Profile.
• The @type SHOULD include CreativeWork (indicating a Web Page) or Dataset (indicating a Profile Crate).
• SHOULD have an absolute URI as @id
• SHOULD have a descriptive name
• MAY declare version, preferably according to Semantic Versioning

RO-Crates that are conforming to (or intending to conform to) such a profile SHOULD declare this using conformsTo on the root data entity:

{
    "@id": "./",
    "@type": "Dataset",
    "conformsTo":
        {"@id": "https://w3id.org/ro/wfrun/process/0.4"}       
}

It is valid for a crate to conform to multiple profiles, in which case conformsTo is an unordered array.

Note that as profile conformance is declared on the RO-Crate Root (./ in this example), the profile applies to the whole RO-Crate, and may cover aspects beyond the crate’s metadata file (e.g. identifiers, packaging, purpose).

Profile Crate

While the Profile URI @id must resolve to a human-readable profile description, it MAY additionally be made to resolve to a Profile Crate.

A Profile Crate is a type of RO-Crate that gathers resources which further define the profile in addition to the profile description. This allows formalizing an alternative profile description for machine-readability, for instance for validation, but also additional resources like examples. The rest of this subsection declares the content of this Profile Crate.

The Profile Crate @id declared within its own RO-Crate Metadata Document SHOULD be an absolute URI, and the corresponding reference from its RO-Crate Metadata Descriptor updated accordingly.

Within the Profile Crate, its Root Data entity MUST declare Profile as an additional @type:

{
    "@id": "ro-crate-metadata.json",
    "@type": "CreativeWork",
    "conformsTo": {"@id": "https://w3id.org/ro/crate/1.2-DRAFT"},
    "about": {"@id": "https://w3id.org/ro/wfrun/process/0.4"}
},  
{
    "@id": "ro-crate-preview.html",
    "@type": "CreativeWork",    
    "about": { "@id": "https://w3id.org/ro/wfrun/process/0.4" }
},
{
    "@id": "https://w3id.org/ro/wfrun/process/0.4",
    "@type": ["Dataset", "Profile"],
    "name": "Process Run crate profile",
    "version": "0.4.0",
    "isProfileOf": [
        {"@id": "https://w3id.org/ro/crate/1.2-DRAFT"}
    ],
    "hasPart": [ 
        { "@id": "index.html" }
    ],
    "hasResource": [ 
        { "@id": "#hasSpecification" }
    ],
    "…": ""
},
{
    "@id": "index.html",
    "@type": "File",
    "name": "Process Run crate profile description",
    "encodingFormat": "text/html",
    "about": "https://w3id.org/ro/wfrun/process/0.4",
},
{ 
    "@id": "#hasSpecification",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://www.w3.org/ns/dx/prof/role/specification" },
    "hasArtifact": {"@id": "index.html"}
}

The rest of the earlier requirements for a Profile entity also apply here, adding:

• MUST reference the human readable profile description as a data entity
• SHOULD have an absolute URI as @id
• SHOULD have a descriptive name
• MAY declare version, preferably according to Semantic Versioning (e.g. 0.4.0)
• SHOULD reference the minimally expected RO-Crate specification as isProfileOf, which MAY be declared as contextual entity
• SHOULD list related data entities using hasPart (see below)
• MAY list profile descriptors using hasResource (see below)

The base RO-Crate specification referenced by isProfileOf is a Profile Crate itself, see ro-crate-metadata.json or ro-crate-preview.html.

How to retrieve a Profile Crate

To resolve a Profile URI to a machine-readable Profile Crate, follow the approaches of retrieving an RO-Crate.

If none of these approaches worked, then this profile probably does not have a corresponding Profile Crate. For human display of conformed profiles, display a hyperlink to its @id Web page, described by its name.

Shared contextual entities from a Profile Crate

If an RO-Crate declares conformance to a given profile crate with conformsTo on its root data entity, contextual entities declared in the corresponding Profile Crate do not need to be repeated in the conforming crate.

For instance, if a Profile Crate adds a DefinedTerm entity according to the ad-hoc definitions, the term MAY be referenced in the conforming crate without making a contextual entity there. For archival purposes it MAY however still be preferrable to copy such entities across to each conforming crate.

In the conforming crate, any terms defined in the profile using DefinedTerm, rdfs:Class and rdf:Property MUST either be used as full URIs matching the @id, or mapped to these URIs from the conforming crate’s JSON-LD @context. Note that JSON-LD only expands keys from @id and @type.

It is RECOMMENDED that @id of such shared entities are absolute URIs on both sides to avoid resolving relative paths, and that the profile’s recommended JSON-LD Context used by conforming crates SHOULD have a mapping to the URIs, see section Extending RO-Crate.

Archiving Profile Crates

For archival purposes, a crate declaring profile conformance MAY choose to include a snapshot copy of the Profile Crate, indicated using distribution, as detailed for dataset distributions:

{
    "@id": "https://w3id.org/ro/wfrun/process/0.4",
    "@type": ["CreativeWork", "Profile"],
    "name": "Process Run crate profile",
    "version": "0.4.0",
    "distribution": { "@id": "process-profile-0.1.zip" }
},
{ 
    "@id": "process-profile-0.1.zip",
    "@type": "DataDownload",
    "encodingFormat": ["application/zip", {"@id": "https://www.nationalarchives.gov.uk/PRONOM/x-fmt/263"}],
    "conformsTo": { "@id": "https://w3id.org/ro/crate" }
}

This is mainly beneficial if the crate relies heavily on the profile, e.g. for definitions of terms.

What is included in the Profile Crate?

This section defines the type of resources that should or may be included in the Profile Crate for different purposes (roles).

Declaring the role within the crate

In order for programmatic use of the Profile Crate to consume particular subresources, e.g. for validation, the role of each entity SHOULD be declared by including them using hasResource to a ResourceDescriptor contextual entity that references the subresource using hasResource, as defined by the Profiles Vocabulary:

{
    "@id": "ro-crate-metadata.json",
    "@type": "CreativeWork",
    "conformsTo": {"@id": "https://w3id.org/ro/crate/1.2-DRAFT"},
    "about": {"@id": "http://example.com/my-crate-profile/0.1/"},
},
{
    "@id": "http://example.com/my-crate-profile/0.1/",
    "@type": ["Dataset", "Profile"],
    "name": "My Crate Profile",
    "version": "0.1.0",
    "hasPart": [
        {"@id": "http://example.com/my-crate-profile/0.1/shape.shex"}
    ],
    "hasResource": [
        {"@id": "#hasShape"}
    ]
},
{ 
    "@id": "#hasShape",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://www.w3.org/ns/dx/prof/role/constraints" },
    "hasArtifact": {"@id": "http://example.com/my-crate-profile/0.1/shape.shex"}
}

The ResourceDescriptor entity MAY also declare dct:format or dct:conformsTo, however the data entity referenced with hasArtifact SHOULD always declare encodingFormat (with OPTIONAL conformsTo) to specify its encoding format, e.g.:

{
    "@id": "http://example.com/my-crate-profile/0.1/shape.shex",
    "@type": "File",
    "encodingFormat": [
        "text/shex", 
        {"@id": "http://shex.io/shex-semantics/" }
    ]
}

The referenced role do not need to be declared as a DefinedTerm contextual entity unless it differs from these recommended predefined roles:

{
    "@id": "http://www.w3.org/ns/dx/prof/role/constraints",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Constraints", 
    "description": "Descriptions of obligations, limitations or extensions that the profile defines"
},
{
    "@id": "http://www.w3.org/ns/dx/prof/role/example",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Example", 
    "description": "Sample instance data conforming to the profile"
},
{
    "@id": "http://www.w3.org/ns/dx/prof/role/guidance",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Guidance", 
    "description": "Documents, in human-readable form, how to use the profile"
},
{
    "@id": "http://www.w3.org/ns/dx/prof/role/mapping",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Mapping", 
    "description": "Describes conversions between two specifications"
},
{
    "@id": "http://www.w3.org/ns/dx/prof/role/schema",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Schema", 
    "description": "Machine-readable structural descriptions of data defined by the profile"
},
{
    "@id": "http://www.w3.org/ns/dx/prof/role/specification",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Specification", 
    "description": "Defining the profile in human-readable form"
},
{
    "@id": "http://www.w3.org/ns/dx/prof/role/validation",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Validation", 
    "description": "Supplies instructions about how to verify conformance of data to the profile"
},
{
    "@id": "http://www.w3.org/ns/dx/prof/role/vocabulary",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Vocabulary", 
    "description": "Defines terms used in the profile specification"
},
{
    "@id": "http://purl.org/dc/terms/conformsTo",
    "@type": ["DefinedTerm", "ResourceRole"],
    "name": "Conforms to", 
    "description": "Suggestion of additional profile to conform to"
}

The examples in the rest of this document will list the data entities with a corresponding ResourceDescriptor entity, but for brevity not repeating the required hasPart and hasResource references from the root dataset.

Below follows the suggested data entities to include in a Profile Crate using hasPart and, if applicable, a corresponding hasResource to a ResourceDescriptor:

Profile description entity

A Profile Crate MUST declare a human-readable profile description, which is about this Profile Crate and SHOULD have encodingFormat as text/html. The corresponding ResourceDescriptor SHOULD have identifier http://www.w3.org/ns/dx/prof/role/specification or http://www.w3.org/ns/dx/prof/role/guidance – for example:

{
    "@id": "index.html",
    "@type": "File",
    "name": "Process Run Crate profile description",
    "encodingFormat": "text/html",
    "about": "https://w3id.org/ro/wfrun/process/0.4",
},
{ 
    "@id": "#hasSpecification",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://www.w3.org/ns/dx/prof/role/specification" },
    "hasArtifact": {"@id": "index.html"}
}

The profile description MAY (instead of say a dedicated index.html as above) be equivalent to the RO-Crate Website entity ro-crate-preview.html (promoting it to a data entity by listing it under hasPart):

{ 
    "@id": "#hasSpecification",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://www.w3.org/ns/dx/prof/role/specification" },
    "hasArtifact": {"@id": "ro-crate-preview.html"}
},
{
    "@id": "ro-crate-preview.html",
    "@type": "CreativeWork",
    "name": "RO-Crate preview of the Process Run Crate profile",
    "encodingFormat": "text/html",
    "about": "https://w3id.org/ro/wfrun/process/0.4"
}

Profile Schema entity

An optional machine-readable schema of the profile, for instance a Describo JSON profile:

{
    "@id": "https://raw.githubusercontent.com/UTS-eResearch/describo/v0.13.0/src/components/profiles/paradisec.describo.profile.json",
    "@type": "File",
    "name": "PARADISEC profile for Describo",
    "encodingFormat": "application/json",
    "conformsTo": {"@id": "https://github.com/UTS-eResearch/describo/wiki/dsp-index#profile-structure"}
},
{ 
    "@id": "#hasSchema",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://www.w3.org/ns/dx/prof/role/schema" },
    "hasArtifact": {"@id": "https://raw.githubusercontent.com/UTS-eResearch/describo/v0.13.0/src/components/profiles/paradisec.describo.profile.json"}
},
{
    "@id": "https://github.com/UTS-eResearch/describo/wiki/dsp-index#profile-structure",
    "@type": "Profile",
    "name": "Describo JSON profile"
}

A schema may formalize restrictions on the RO-Crate Metadata Document on a graph-level (e.g. what types/properties) as well as serialization level (e.g. use of JSON arrays).

This interpretation of schema assumes the resource somewhat describes the data structure, e.g. expected types and attributes the RO-Crate’s JSON-LD. Use alternatively the role http://www.w3.org/ns/dx/prof/role/validation if the schema is primarily a set of constraint for validation purposes, or http://www.w3.org/ns/dx/prof/role/vocabulary for ontologies and term listings.

Below are known schema types in their recommended media type, with suggested identifiers for the contextual entities of encodingFormat with type Standard and conformsTo with type Profile:

Some of the above schema languages are based on general data structure syntaxes like application/json and text/turtle, and therefore have a generic encodingFormat with a specialized conformsTo URI, which itself is declared as a Profile.

Software that works with the profile

Software that may consume/validate/generate RO-Crates following this profile (potentially using the schema):

{
      "@id": "https://arkisto-platform.github.io/describo/",
      "@type": "SoftwareApplication",
      "name": "Describo",
      "version": "0.13.0",
      "url": "https://arkisto-platform.github.io/describo/"
}

Repositories that expect the profile

A repository or collection within a repository that may accept/contain RO-Crates following this profile:

{
   "@id": "https://mod.paradisec.org.au/",
   "@type": "RepositoryCollection",
   "title":  "Modern PARADISEC demonstrator",   
   "description": "PARADISEC curates digital material about small or endangered languages",
   "publisher": {"@id": "https://paradisec.org.au/"}
}

BagIt packaging

If conforming RO-Crates should be packaged according to a BagIt profile (e.g. must be serialized as an application/zip):

{
   "@id": "https://w3id.org/ro/bagit/profile/0.3",
   "@type": "Profile",
   "name":  "BagIt profile for RO-Crate in ZIP",
   "encodingFormat": [
        "application/json", 
        {"@id": "https://bagit-profiles.github.io/bagit-profiles-specification/"}
   ]   
}

Extension vocabularies

A profile that extends RO-Crate SHOULD indicate which vocabulary/ontology it uses as a DefinedTermSet:

{
    "@id": "https://w3id.org/ro/terms/test#",
    "@type": "DefinedTermSet",
    "name": "Namespace for workflow testing metadata",
    "url": "https://github.com/ResearchObject/ro-terms/tree/master/test",
},
{ 
    "@id": "#hasTestVocabulary",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://www.w3.org/ns/dx/prof/role/vocabulary" },
    "hasArtifact": {"@id": "https://w3id.org/ro/terms/test#"}
}

The @id of the vocabulary SHOULD be the namespace, while url SHOULD go to a human-readable description of the vocabulary.

A profile that defines many extensions terms MAY define its own DefinedTermSet and relate the terms using hasDefinedTerm:

 {
    "@id": "https://w3id.org/cpm/ro-crate",
    "@type": "Dataset",
    "identifier": "https://w3id.org/cpm/ro-crate",
    "name": "Common Provenance Model RO-Crate profiles and vocabulary",
    "hasPart": [
      { "@id": "https://w3id.org/cpm/ro-crate#" }
    ],
    "hasResource": [
        { "@id": "#hasCPMVocabulary" }
    ]
  },
  { 
    "@id": "#hasCPMVocabulary",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://www.w3.org/ns/dx/prof/role/vocabulary" },
    "hasArtifact": {"@id": "https://w3id.org/cpm/ro-crate#"}
  },  
  {
    "@id": "https://w3id.org/cpm/ro-crate#",
    "@type": "DefinedTermSet",
    "name": "Namespace for Common Provenance Model RO-Crate model",
    "hasDefinedTerm": [
      { "@id": "https://w3id.org/cpm/ro-crate#CPMProvenanceFile" },
      { "@id": "https://w3id.org/cpm/ro-crate#CPMMetaProvenanceFile" }
    ]
  },
  { 
    "@id": "https://w3id.org/cpm/ro-crate#CPMProvenanceFile",
    "@type": "DefinedTerm",
    "…" : ""
  }

Extension terms

A profile that extends RO-Crate MAY indicate particular terms directly as DefinedTerm, rdfs:Class and/or rdf:Property instances:

{
    "@id": "https://w3id.org/ro/terms/test#runsOn",
    "@type": "DefinedTerm",
    "termCode": "runsOn",
    "name": "Runs on",
    "description": "Service where the test instance is executed",
    "url": "https://lifemonitor.eu/workflow_testing_ro_crate#test-instance"
}

The termCode SHOULD be valid as a key in JSON-LD @context of conforming RO-Crates. The term SHOULD be mapped to the terms’ @id in the @context of this Profile Crate.

JSON-LD Context

A profile that have a corresponding JSON-LD @context (e.g. to map its extensions terms, or to suggest a version of RO-Crate’s official context) SHOULD indicate the context in the Profile Crate:

{
    "@id": "https://w3id.org/ro/crate/1.2-DRAFT/context",
    "@type": "CreativeWork",
    "name": "RO-Crate JSON-LD Context",
    "encodingFormat": "application/ld+json",
    "conformsTo": {"@id": "http://www.w3.org/ns/json-ld#Context"},
    "version": "1.1.1"
},
{
    "@id": "http://www.w3.org/ns/json-ld#Context",
    "@type": "DefinedTerm",
    "name": "JSON-LD Context",
    "url": "https://www.w3.org/TR/json-ld/"
}

The JSON-LD Context entity:

• MUST have an encodingFormat of application/ld+json
• MUST have an absolute URI as @id, which MUST be retrievable as JSON-LD directly or with content-negotiation and/or HTTP redirects.
• SHOULD have a permalink (persistent identifier) as @id
  • e.g. starting with https://w3id.org/ http://purl.org/
• SHOULD use https rather than http with a certificate commonly accepted by browsers
• SHOULD have a @id URI that is versioned with MAJOR.MINOR, e.g. https://example.com/image-profile-2.4
• SHOULD have a descriptive name
• SHOULD have a conformsTo to the contextual entity http://www.w3.org/ns/json-ld#Context
• MAY declare version according to Semantic Versioning
• Updates MAY add new terms or patch fixes (with corresponding version change)
• Updates SHOULD NOT remove terms already published and potentially used by consumers of the profile
• Updates SHOULD NOT replace URIs terms map to – except for typos.
• Including the DefinedTerm for JSON-LD is optional.

Note that the referenced context URI does not have to match the @context of the Profile Crate itself.

The @context MAY be the Profile Crate’s Metadata JSON-LD file itself if it is resolvable as media type application/ld+json over HTTP. Make sure the crate includes the defined terms both within its @context and ideally as entities in its @graph.

Multiple profiles

RO-Crate profiles sometimes build on each other. Note that unlike traditional object-oriented programming with strict class hierarchies, profiles are a looser construct of conventions rather than absolute rules. RO-Crate therefore do not enforce any particular “inheritance” across profiles.

A crate conforming to multiple RO-Crate profiles SHOULD explicitly declare conformsTo for each profile. Each profile MUST have a corresponding contextual entity for each.

A Profile Crate can suggest interoperable profiles under hasPart, and recommend them by using the role http://purl.org/dc/terms/conformsTo in a resource descriptor. For example, the specializing Workflow Run Crate profile recommends two other profiles, the “parent” Process Run Crate and a “mix-in” Workflow RO-Crate:

{
    "@id": "https://w3id.org/ro/wfrun/workflow/0.4",
    "@type": ["Dataset", "Profile"],
    "name": "Workflow Run crate profile",
    "description": "Profile for recording a workflow run. It is recommended to also conform to profiles Process Run Crate and Workflow RO-Crate",
    "version": "0.4.0",
    "isProfileOf": [
        {"@id": "https://w3id.org/ro/crate/1.2-DRAFT"},
    ],
    "hasPart": [ 
        { "@id": "https://w3id.org/ro/wfrun/process/0.4" },
        { "@id": "https://w3id.org/workflowhub/workflow-ro-crate/1.0" },
        { "…": "" }
    ],
    "hasResource": [ 
        { "@id": "#shouldConformToWorkflowROCrate" },
        { "@id": "#shouldConformToProcess" }
        { "…": "" }
    ],
    "…": ""
},
{
    "@id": "https://w3id.org/ro/wfrun/process/0.4",
    "@type": ["CreativeWork", "Profile"],
    "name": "Process Run Crate profile",
    "version": "0.4.0"
},
{
    "@id": "https://w3id.org/workflowhub/workflow-ro-crate/1.0",
    "@type": ["CreativeWork", "Profile"],
    "name": "Workflow RO-Crate profile",
    "version": "1.0"
},
{ 
    "@id": "#shouldConformToWorkflowROCrate",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://purl.org/dc/terms/conformsTo" },
    "hasArtifact": {"@id": "https://w3id.org/workflowhub/workflow-ro-crate/1.0"}
},
{ 
    "@id": "#shouldConformToProcess",
    "@type": "ResourceDescriptor",
    "hasRole": { "@id": "http://purl.org/dc/terms/conformsTo" },
    "hasArtifact": {"@id": "https://w3id.org/ro/wfrun/process/0.4"}
}

Note that this does not enforce any particular hierarchy of profiles, thus listed profiles can be both more general or more specific than the given Profile Crate. A given profile MAY provide further recommendations or requirements for how the related profiles are to be used in its human-readable documentation, e.g. by elaborating on the ResourceDescriptor.

It is NOT RECOMMENDED to include further elements of the referenced profiles, e.g. their ResourceDescriptors, see How to retrieve a Profile Crate.