Ad-hoc terms can be moved to a Profile Crate

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 <https://w3id.org/ro/terms/> 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` <https://w3id.org/cpm/ro-crate> defines the term <https://w3id.org/cpm/ro-crate#CPMProvenanceFile>. 
+
+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 <https://w3id.org/cpm/ro-crate#CPMProvenanceFile> 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 %}

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 <https://w3id.org/> <http://purl.org/>
+  - MAY embed major.minor version in the PID, e.g. <https://w3id.org/ro/crate/1.2/context>
 * 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 %}