From dcaa7d5bd25e81bc9dc55d58bc9d8f55ac4a7c1e Mon Sep 17 00:00:00 2001 From: Simeon Warner Date: Wed, 25 Oct 2023 09:50:15 -0400 Subject: [PATCH 1/2] AS context requires, EMM context recommended --- docs/0.1/context.json | 1 - docs/0.1/index.md | 67 ++++++++++++++++++++----------------- docs/_includes/api/links.md | 7 ++-- 3 files changed, 40 insertions(+), 35 deletions(-) diff --git a/docs/0.1/context.json b/docs/0.1/context.json index 442c426..9e63ac4 100644 --- a/docs/0.1/context.json +++ b/docs/0.1/context.json @@ -1,7 +1,6 @@ { "@context": { "@version": 1.1, - "@vocab": "https://www.w3.org/ns/activitystreams#", "emm": "https://ld4.github.io/entity_metadata_management/0.1/#", "id": "@id", "type": "@type", diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 22f55af..3abb82e 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -157,9 +157,32 @@ This specification provides an API via which Entity Metadata Providers can publi This specification is based on the [Activity Streams 2.0 specification][org-w3c-activitystreams]. The following sections describe the use of Activity Streams to meet Entity Metadata Management use cases. They describe only the Activity Streams classes and properties used, and any restrictions or additional semantics in the context of this specification. Implementations _MAY_{:.strong-term} use other properties from Activity Streams or elsewhere for extension, consumers _SHOULD_{:.strong-term} ignore any properties not defined in this specification that they don't understand. ### 2.2. JSON-LD Representation +{: #jsonld-representation} -The use of JSON-LD with a specific `@context` that extends the [Activity Streams 2.0 specification][org-w3c-activitystreams] allows Entity Metadata Consumers to parse the resulting documents using standard JSON tools, and also allows the data to be interpreted according to the RDF Data Model (see [Relationship to RDF](https://www.w3.org/TR/json-ld/#relationship-to-rdf)). +The use of [JSON-LD][org-w3c-json-ld] with a specific `@context` allows Entity Metadata Consumers to parse the resulting documents using standard JSON tools, and also allows the data to be interpreted according to the RDF Data Model (see [Relationship to RDF](https://www.w3.org/TR/json-ld/#relationship-to-rdf)). +In the simplest form, a JSON-LD `@context` maps terms to IRIs. All _Entity Metadata Management_{:.term} API responses _MUST_{:.strong-term} include the [Activity Streams 2.0 context][org-w3c-activitystreams-context-definition] definition at the top-level of each API response: + +```json-doc +{ + "@context": "https://www.w3.org/ns/activitystreams", + // rest of API response +} +``` + +It is _RECOMMENDED_ that implementations also include the [Entity Metadata Management context][emm-context-api-01], in which case the value of `@context` will be a list. The _Entity Metadata Management_{:.term} context includes definition of the term `Deprecate` and _MUST_ thus be included if the [`Deprecate` activity](#deprecate-entity) is used. Including the _Entity Metadata Management_{:.term} context also serves to signal to consumers that this specification is being followed. + +```json-doc +{ + "@context": [ + "https://www.w3.org/ns/activitystreams", + "https://ld4.github.io/entity_metadata_management/0.1/context.json" + ], + // rest of API response +} +``` + +Implementations _MAY_{:.strong-term} include additional extension contexts. Extension contexts _MUST NOT_{:.strong-term} override terms defined in the underlying _Activity Stream_{:.term} context and _Entity Metadata Management_{:.term} contexts. Implementations _MAY_{:.strong-term} also use additional properties and values not defined in a JSON-LD `@context` with the understanding that any such properties will likely be unsupported and ignored by consuming implementations that use the standard JSON-LD algorithms. ## 3. API Responses {: #api-responses} @@ -178,7 +201,10 @@ The _Entry Point_{:.term} _MUST_{:.strong-term} be implemented as an _OrderedCol ```json-doc { - "@context": "https://ld4.github.io/entity_metadata_management/0.1/context.json", + "@context": [ + "https://www.w3.org/ns/activitystreams", + "https://ld4.github.io/entity_metadata_management/0.1/context.json" + ], "summary": "My Authority - Change Documents", "type": "OrderedCollection", "id": "https://data.my.authority/change_documents/2021/activity-stream", @@ -198,23 +224,10 @@ The _Entry Point_{:.term} _MUST_{:.strong-term} be implemented as an _OrderedCol __@context__ -Reference: [JSON-LD scoped context][org-w3c-json-ld-scoped-contexts] +Reference: [JSON-LD context][org-w3c-json-ld-context] {:.reference} -The `@context` is used to refer a JSON-LD context which, in its simplest form, maps terms to IRIs. - -_Entity Metadata Management_{:.term} activity streams _MUST_{:.strong-term} include the following [context][emm-context-api-01] definition at the top-level of each API response: - -```json-doc -{ - "@context": "https://ld4.github.io/entity_metadata_management/0.1/context.json", - // rest of API response -} -``` - -The _Entity Metadata Management_{:.term} context includes information for all parts of this specification and thus the same context definition is used in all API responses. The _Entity Metadata Management_{:.term} context imports the _Activity Stream_{:.term} [context][org-w3c-activitystreams-context-definition] and thus it is not necessarily to specify that explicitly in API responses. - -Implementations _MAY_{:.strong-term} include additional extension contexts, in which case the value of `@context` will be a list with the _Entity Metadata Management_{:.term} context first. Extension contexts _MUST NOT_{:.strong-term} override terms defined in the _Entity Metadata Management_{:.term} context or the underlying _Activity Stream_{:.term} context. Implementations _MAY_{:.strong-term} also use additional properties and values not defined in a JSON-LD `@context` with the understanding that any such properties will likely be unsupported and ignored by consuming implementations that use the standard JSON-LD algorithms. +The `@context` _MUST_{:.strong-term} as describe in [JSON-LD Representation](#jsonld-representation). __summary__ @@ -343,7 +356,10 @@ _Change Sets_{:.term} _MUST_{:.strong-term} be implemented as an _OrderedCollect ```json-doc { - "@context": "https://ld4.github.io/entity_metadata_management/0.1/context.json", + "@context": [ + "https://www.w3.org/ns/activitystreams", + "https://ld4.github.io/entity_metadata_management/0.1/context.json" + ], "type": "OrderedCollectionPage", "id": "https://data.my.authority/change_documents/2021/activity-stream/page/2", "partOf": { @@ -397,18 +413,7 @@ __@context__ Reference: [JSON-LD context][org-w3c-json-ld-context] {:.reference} -The `@context` is used to refer a JSON-LD context which, in its simplest form, maps terms to IRIs. - -_Entity Metadata Management_{:.term} activity streams _MUST_{:.strong-term} include the following [context][emm-context-api-01] definition at the top-level of each API response: - -```json-doc -{ - "@context": "https://ld4.github.io/entity_metadata_management/0.1/context.json", - // rest of API Change Set response -} -``` - -See additional discussion in [Entry Point `@context`](#entry-point-context). +The `@context` _MUST_{:.strong-term} as describe in [JSON-LD Representation](#jsonld-representation). __type__ @@ -719,6 +724,8 @@ An entity that has been deprecated _SHOULD_{:.strong-term} have an [Entity Chang * A `Deprecate` activity for the deprecated entity, and one or more `Create` activities for the replacement entity or entities. In all cases, it is expected that the consumer will dereference the deprecated entity URI to obtain the updated entity description, including whether it was replaced. +Note that the _Entity Metadata Management_{:.term} context includes definition of the term `Deprecate` and thus _MUST_{:strong-term} be included in the `@context` definition if `Deprecate` activities are used. See [JSON-LD Representation](#jsondld-representation) for more details. + #### Example Entity Change Activity exceprt for Deprecate in the Scenario where a Replacement Entity Already Exists ```json-doc diff --git a/docs/_includes/api/links.md b/docs/_includes/api/links.md index 2fd4a18..f713dd0 100644 --- a/docs/_includes/api/links.md +++ b/docs/_includes/api/links.md @@ -14,7 +14,6 @@ [emm-use-cases]: {{ site.url }}{{ site.baseurl }}/0.1/#use-cases "Use Cases for Entity Metadata Change Management" [org-cc-licenses]: https://creativecommons.org/licenses/ "Create Commons Licenses" [org-iana-uri-schemes]: http://www.iana.org/assignments/uri-schemes/uri-schemes.xhtml "IANA URI Schemes" -[org-json-ld]: http://www.json-ld.org/ "JSON for Linking Data" [org-linked-data]: http://linkeddata.org/ "Linked Data" [org-rfc-2119]: https://tools.ietf.org/html/rfc2119 "RFC Keywords" [org-rfc-8259]: https://tools.ietf.org/html/rfc8259 "JSON RFC" @@ -46,6 +45,6 @@ [org-w3c-activitystreams-property-type]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-type [org-w3c-activitystreams-property-updated]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-updated [org-w3c-activitystreams-property-url]: https://www.w3.org/TR/activitystreams-vocabulary/#dfn-url -[org-w3c-json-as-json-ld]: http://www.w3.org/TR/json-ld/#interpreting-json-as-json-ld "Interpreting JSON as JSON-LD" -[org-w3c-json-ld-scoped-contexts]: https://json-ld.org/spec/latest/json-ld/#scoped-contexts "JSON-LD Scoped Contexts" -[org-w3c-json-ld]: http://www.w3.org/TR/json-ld/ "JSON-LD 1.0" +[org-w3c-json-ld]: http://www.w3.org/TR/json-ld11/ "JSON-LD 1.1" +[org-w3c-json-as-json-ld]: http://www.w3.org/TR/json-ld11/#interpreting-json-as-json-ld "Interpreting JSON as JSON-LD" +[org-w3c-json-ld-context]: https://www.w3.org/TR/json-ld11/#the-context "JSON-LD Context" From 08b006dc21a04fc12cacbacfc4a184fe95241e07 Mon Sep 17 00:00:00 2001 From: Simeon Warner Date: Wed, 25 Oct 2023 09:55:37 -0400 Subject: [PATCH 2/2] Improve @context description --- docs/0.1/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/0.1/index.md b/docs/0.1/index.md index 13a044e..d9c4867 100644 --- a/docs/0.1/index.md +++ b/docs/0.1/index.md @@ -227,7 +227,7 @@ __@context__ Reference: [JSON-LD context][org-w3c-json-ld-context] {:.reference} -The `@context` _MUST_{:.strong-term} as describe in [JSON-LD Representation](#jsonld-representation). +The _Entry Point_{:.term} _MUST_{:.strong-term} have a `@context` property as described in [JSON-LD Representation](#jsonld-representation). __summary__ @@ -413,7 +413,7 @@ __@context__ Reference: [JSON-LD context][org-w3c-json-ld-context] {:.reference} -The `@context` _MUST_{:.strong-term} as describe in [JSON-LD Representation](#jsonld-representation). +The _Change Set_{:.term} _MUST_{:.strong-term} have a `@context` property as described in [JSON-LD Representation](#jsonld-representation). __type__