diff --git a/docs/1.2-DRAFT/appendix/jsonld.md b/docs/1.2-DRAFT/appendix/jsonld.md index 71dcf0c0..5edd03e2 100644 --- a/docs/1.2-DRAFT/appendix/jsonld.md +++ b/docs/1.2-DRAFT/appendix/jsonld.md @@ -325,4 +325,57 @@ Following the conventions used by Schema.org, ad-hoc terms SHOULD also include d More information about the relationship of this term to other terms MAY be provided using [domainIncludes], [rangeIncludes], [rdfs:subClassOf] following the conventions used in the [Schema.org schema]. +## Grouping extensions as an RO-Crate profile + +If several RO-Crates are using the same `@context` extension terms, or define the same additional ad-hoc terms, then it may make sense to specify these within an [RO-Crate profile](../profiles.md) that the crates can then explicitly declare conformance to. + +The `@id` of the extension terms should after the move be made absolute URIs that resolve to the profile crate -- if these were made using then a request to set up such redirects can be made. + +For terms it is RECOMMENDED to change the `@id` of the terms after moving to be based on the profile's permalink, e.g. the profile with `@id` defines the term . + +See sections on [profile extension terms](../profiles.md#extension-terms) and [Profile JSON-LD context](../profiles.md#json-ld-context). [Custom file formats](../data-entities.md#adding-detailed-descriptions-of-encodings) and common [contextual entities](../contextual-entities.md) may also be moved to the profile, ensuring their `@id` are absolute URI and resolve to the profile JSON-LD. + +This can reduce repetition in their JSON-LD, but means additional measures must be taken to ensure the resulting RO-Crates remain functional over time, e.g. not to remove terms as the profile evolves over time. + +Example: + +```json +{ "@context": [ + "https://w3id.org/ro/crate/1.1/context", + "https://w3id.org/cpm/ro-crate/0.1" + ], + "@graph": [ + + { + "@type": "CreativeWork", + "@id": "ro-crate-metadata.json", + "conformsTo": {"@id": "https://w3id.org/ro/crate/1.1"}, + "about": {"@id": "./"} + }, + { + "@id": "./", + "@type": "Dataset", + "conformsTo": {"@id": "https://w3id.org/cpm/crate/0.1"}, + "hasPart": [ + { "@id": "CPM_COMPLIANT_PROVENANCE" } + ], + "…" : "" + }, + { + "@id": "CPM_COMPLIANT_PROVENANCE", + "@type": ["File", "CPMProvenanceFile"], + "encodingFormat": [ + "text/provenance-notation", + { "@id": "http://www.w3.org/TR/2013/REC-prov-n-20130430/"} + ], + "name": "Provenance file" + } +] +} +``` + +In the example above, the type `CPMProvenanceFile` is resolved to by the matching key in the second `@context` when content-negotiating for `application/ld+json` (browsers may see the human-readable documentations). + +The contextual entity `http://www.w3.org/TR/2013/REC-prov-n-20130430/` for `encodingFormat` is defined within the profile rather in this specific crate, however in this example that `@id` resolves to the textual specification at W3C rather than back to the Profile Crate. + {% include references.liquid %} diff --git a/docs/1.2-DRAFT/profiles.md b/docs/1.2-DRAFT/profiles.md index aa443f4b..958a7c25 100644 --- a/docs/1.2-DRAFT/profiles.md +++ b/docs/1.2-DRAFT/profiles.md @@ -226,10 +226,39 @@ which vocabulary/ontology it uses as a [DefinedTermSet]: 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 term MAY define its own `DefinedTermSet` and relate the terms using `hasDefinedTerm`: + +```json + { + "@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#" } + ] + }, + { + "@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](appendix/jsonld.md#extending-ro-crate) MAY indicate particular terms -directly as [DefinedTerm] instances: +directly as [DefinedTerm], [Class] and/or [Property] instances: ```json { @@ -242,7 +271,8 @@ directly as [DefinedTerm] instances: } ``` -The `termCode` SHOULD be valid as a key in JSON-LD `@context` of conforming RO-Crates. +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 @@ -256,10 +286,8 @@ 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", - {"@id": "http://www.w3.org/ns/json-ld#Context"} - ], + "encodingFormat": "application/ld+json", + "conformsTo": {"@id": "http://www.w3.org/ns/json-ld#Context"}, "version": "1.1.1", }, { @@ -270,21 +298,28 @@ context in the Profile Crate: } ``` -The JSON-LD Context: +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 + - MAY embed major.minor version in the PID, e.g. * SHOULD use `https` rather than `http` with a certificate commonly accepted by browsers * SHOULD have a `@id` URI that is _versioned_ with [`MAJOR.MINOR`][semver], e.g. `https://example.com/image-profile-2.4` * SHOULD have a descriptive [name] * SHOULD have a `encodingFormat` to the contextual entity `http://www.w3.org/ns/json-ld#Context` * MAY declare [version] according to [Semantic Versioning][semver] +- 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. Note that the referenced context URI does _not_ have to match the `@context` of the Profile Crate itself. {: .tip } The `@context` MAY be the Profile Crate's Metadata JSON-LD file if it is [resolvable](appendix/jsonld.md#ro-crate-json-ld-media-type) -as media type `application/ld+json` over HTTP. +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`. {% include references.liquid %}