From e8014cde71f546b9139d8f87ffc73da438c487da Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Mon, 29 Jan 2024 16:44:10 +0100 Subject: [PATCH 1/8] Clarify section on Semantic Interoperability. --- index.html | 68 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 52 insertions(+), 16 deletions(-) diff --git a/index.html b/index.html index 24254f829..74ba5b30a 100644 --- a/index.html +++ b/index.html @@ -3078,25 +3078,61 @@

Extensibility

Semantic Interoperability

+

+ When defining new terms in an application-dependent vocabulary, developers MUST use unique [=URLs=] to identify the terms. + It is RECOMMENDED to re-use, whenever possible, terms—and their corresponding URLs—defined by well-known, public vocabularies, + such as [[[?DCTERMS]]] [[?DCTERMS]] or [[[?schema-org]]] [[?schema-org]]. + If that is not possible, developers MUST define a new URL for each term. + When doing so, general [[LINKED-DATA]] principles must be followed, in particular: +

+ +
  • + A human-readable documentation MUST be published, describing the semantics and + the constraints on the use of each term.
    • +
  • + It is RECOMMENDED to also publish the collection of all new terms as a machine-readable vocabulary + using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]] (and, if necessary, OWL2 [[?OWL2-OVERVIEW]]). +
    • +
  • + It MUST be possible to dereference the URL of a term, resulting in its description and/or formal definition. +
    • + + +

    + Developers SHOULD follow the detailed checklist in + [[[?LD-BP]]] [[?LD-BP]] when defining a new vocabulary. +

    +

    + Furthermore, a machine-readable description (that is, a + JSON-LD Context document) MUST be published at the URL specified + in the `@context` [=property=] for the vocabulary. + This context MUST map each term to its corresponding URL, possibly accompanied by further + constraints like the type of the property value. A human-readable document describing the expected order of values for + the `@context` [=property=] is also expected to be published by any implementer seeking interoperability. +

    + +

    + When processing the active context defined by the base JSON-LD Context + document defined in this specification, compliant JSON-LD-based processors produce an error when a JSON-LD context + redefines any term. + The only way to change the definition of existing terms is to introduce a new term that clears the active context within + the scope of that new term. + Authors that are interested in this feature should read about the `@protected` + keyword in the JSON-LD 1.1 specification. +

    -A human-readable document describing the expected order of values for the -`@context` [=property=] is expected to be published by any -implementer seeking interoperability. A machine-readable description -(that is, a normal JSON-LD Context document) is expected to be published -at the URL specified in the `@context` [=property=] by -JSON-LD implementers seeking interoperability. + The base JSON-LD Context file for this specification also includes an extra feature, using the + `@vocab` keyword, which ensures + that any undefined term in a [=verifiable credential=] or a [=verifiable presentation=] is automatically mapped to a + URL prefixed with `https://www.w3.org/ns/credentials/issuer-dependent#`. + The purpose is to allow early experimentation with terms during the development phase, without + the necessity to provide a formal definition in every cycle of that experimentation. + However, developers SHOULD NOT use this feature in production; this + could lead to name clashes, yielding semantic ambiguities with other applications. + Instead, they SHOULD define all the + terms, as described earlier in this section, to achieve proper interoperability.

    From 7b3da6d7f3fb018a861b1d166945901dcec8798c Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Wed, 31 Jan 2024 06:15:34 +0100 Subject: [PATCH 2/8] Fix grammar in Semantic Interoperability section. Co-authored-by: Ted Thibodeau Jr --- index.html | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/index.html b/index.html index 74ba5b30a..6780e66ab 100644 --- a/index.html +++ b/index.html @@ -3079,8 +3079,8 @@

    Extensibility

    Semantic Interoperability

    - When defining new terms in an application-dependent vocabulary, developers MUST use unique [=URLs=] to identify the terms. - It is RECOMMENDED to re-use, whenever possible, terms—and their corresponding URLs—defined by well-known, public vocabularies, + When defining new terms in an application-specific vocabulary, developers MUST use unique [=URLs=] to identify the terms. + Whenever possible, it is RECOMMENDED to re-use terms — and their corresponding URLs — defined by well-known, public vocabularies, such as [[[?DCTERMS]]] [[?DCTERMS]] or [[[?schema-org]]] [[?schema-org]]. If that is not possible, developers MUST define a new URL for each term. When doing so, general [[LINKED-DATA]] principles must be followed, in particular: @@ -3088,7 +3088,7 @@

    Semantic Interoperability

    • - A human-readable documentation MUST be published, describing the semantics and + Human-readable documentation MUST be published, describing the semantics of and the constraints on the use of each term.
    • It is RECOMMENDED to also publish the collection of all new terms as a machine-readable vocabulary @@ -3127,9 +3127,9 @@

      Semantic Interoperability

      `@vocab` keyword, which ensures that any undefined term in a [=verifiable credential=] or a [=verifiable presentation=] is automatically mapped to a URL prefixed with `https://www.w3.org/ns/credentials/issuer-dependent#`. - The purpose is to allow early experimentation with terms during the development phase, without - the necessity to provide a formal definition in every cycle of that experimentation. - However, developers SHOULD NOT use this feature in production; this + This is to allow early experimentation with terms during the development phase, without + requiring a formal definition in every cycle of that experimentation. + Note that developers SHOULD NOT use this feature in production; this could lead to name clashes, yielding semantic ambiguities with other applications. Instead, they SHOULD define all the terms, as described earlier in this section, to achieve proper interoperability. From 791c9ee3db48df8b1f45645595eb863955163bcb Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Wed, 31 Jan 2024 06:18:36 +0100 Subject: [PATCH 3/8] Minor tweaks on the changes --- index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/index.html b/index.html index 6780e66ab..5eee8d5ad 100644 --- a/index.html +++ b/index.html @@ -3079,8 +3079,8 @@

      Extensibility

      Semantic Interoperability

      - When defining new terms in an application-specific vocabulary, developers MUST use unique [=URLs=] to identify the terms. - Whenever possible, it is RECOMMENDED to re-use terms — and their corresponding URLs — defined by well-known, public vocabularies, + When defining new terms in an application-specific vocabulary, developers MUST use globally unambiguous [=URLs=] to identify the terms. + Whenever possible, it is RECOMMENDED to re-use terms — and their corresponding URLs — defined by well-known, public vocabularies, such as [[[?DCTERMS]]] [[?DCTERMS]] or [[[?schema-org]]] [[?schema-org]]. If that is not possible, developers MUST define a new URL for each term. When doing so, general [[LINKED-DATA]] principles must be followed, in particular: From def339e869ccfd2417609fc7ead153cc9a96b293 Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Thu, 1 Feb 2024 06:26:51 +0100 Subject: [PATCH 4/8] Fix markup in semantic interop section. Co-authored-by: David I. Lehn --- index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/index.html b/index.html index 5eee8d5ad..a0ddbd75c 100644 --- a/index.html +++ b/index.html @@ -3089,7 +3089,8 @@

      Semantic Interoperability

      • Human-readable documentation MUST be published, describing the semantics of and - the constraints on the use of each term.
        • + the constraints on the use of each term. +
      • It is RECOMMENDED to also publish the collection of all new terms as a machine-readable vocabulary using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]] (and, if necessary, OWL2 [[?OWL2-OVERVIEW]]). From bfc194508c6d49b1c0f7fa23a52db37854032753 Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Mon, 5 Feb 2024 13:58:44 +0100 Subject: [PATCH 5/8] Remove OWL2 reference and normative-sounding text. --- index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.html b/index.html index a0ddbd75c..004100b9b 100644 --- a/index.html +++ b/index.html @@ -3082,8 +3082,8 @@

        Semantic Interoperability

        When defining new terms in an application-specific vocabulary, developers MUST use globally unambiguous [=URLs=] to identify the terms. Whenever possible, it is RECOMMENDED to re-use terms — and their corresponding URLs — defined by well-known, public vocabularies, such as [[[?DCTERMS]]] [[?DCTERMS]] or [[[?schema-org]]] [[?schema-org]]. - If that is not possible, developers MUST define a new URL for each term. - When doing so, general [[LINKED-DATA]] principles must be followed, in particular: + If that is not possible, developers must define a new URL for each term. + When doing so, the general [[LINKED-DATA]] are expected to be followed, in particular:

          @@ -3093,7 +3093,7 @@

          Semantic Interoperability

        • It is RECOMMENDED to also publish the collection of all new terms as a machine-readable vocabulary - using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]] (and, if necessary, OWL2 [[?OWL2-OVERVIEW]]). + using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]].
        • It MUST be possible to dereference the URL of a term, resulting in its description and/or formal definition. From 38a56496cacde460677e3132ee65558cba38820d Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Mon, 5 Feb 2024 14:00:57 +0100 Subject: [PATCH 6/8] Add guidelines text to Semantic Interoperability section. Co-authored-by: Manu Sporny --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 004100b9b..391733c7d 100644 --- a/index.html +++ b/index.html @@ -3096,7 +3096,7 @@

          Semantic Interoperability

          using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]].
        • - It MUST be possible to dereference the URL of a term, resulting in its description and/or formal definition. + It SHOULD be possible to dereference the URL of a term, resulting in its description and/or formal definition.
        From dfe145604d2a27cea3d5047b298cc62d49c4fac1 Mon Sep 17 00:00:00 2001 From: Ivan Herman Date: Wed, 7 Feb 2024 17:18:58 +0100 Subject: [PATCH 7/8] Make last lowercase 'must' normative. Co-authored-by: Manu Sporny --- index.html | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/index.html b/index.html index 391733c7d..a8b12a9ed 100644 --- a/index.html +++ b/index.html @@ -3081,9 +3081,9 @@

        Semantic Interoperability

        When defining new terms in an application-specific vocabulary, developers MUST use globally unambiguous [=URLs=] to identify the terms. Whenever possible, it is RECOMMENDED to re-use terms — and their corresponding URLs — defined by well-known, public vocabularies, - such as [[[?DCTERMS]]] [[?DCTERMS]] or [[[?schema-org]]] [[?schema-org]]. - If that is not possible, developers must define a new URL for each term. - When doing so, the general [[LINKED-DATA]] are expected to be followed, in particular: + such as [[[?DCTERMS]]] [[?DCTERMS]] or [[[?schema-org]]] [[?schema-org]]. + If that is not possible, authors MUST define a new URL for each term. + When doing so, the general guidelines for [[LINKED-DATA]] are expected to be followed, in particular:

          @@ -3092,48 +3092,48 @@

          Semantic Interoperability

          the constraints on the use of each term.
        • - It is RECOMMENDED to also publish the collection of all new terms as a machine-readable vocabulary + It is RECOMMENDED to also publish the collection of all new terms as a machine-readable vocabulary using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]].
        • - It SHOULD be possible to dereference the URL of a term, resulting in its description and/or formal definition. -
          • -
        - + It SHOULD be possible to dereference the URL of a term, resulting in its description and/or formal definition. +
        • +
      +

      Developers SHOULD follow the detailed checklist in [[[?LD-BP]]] [[?LD-BP]] when defining a new vocabulary.

      - Furthermore, a machine-readable description (that is, a + Furthermore, a machine-readable description (that is, a JSON-LD Context document) MUST be published at the URL specified - in the `@context` [=property=] for the vocabulary. + in the `@context` [=property=] for the vocabulary. This context MUST map each term to its corresponding URL, possibly accompanied by further constraints like the type of the property value. A human-readable document describing the expected order of values for - the `@context` [=property=] is also expected to be published by any implementer seeking interoperability. + the `@context` [=property=] is also expected to be published by any implementer seeking interoperability.

      When processing the active context defined by the base JSON-LD Context - document defined in this specification, compliant JSON-LD-based processors produce an error when a JSON-LD context + document defined in this specification, compliant JSON-LD-based processors produce an error when a JSON-LD context redefines any term. The only way to change the definition of existing terms is to introduce a new term that clears the active context within - the scope of that new term. - Authors that are interested in this feature should read about the `@protected` + the scope of that new term. + Authors that are interested in this feature should read about the `@protected` keyword in the JSON-LD 1.1 specification.

      - The base JSON-LD Context file for this specification also includes an extra feature, using the + The base JSON-LD Context file for this specification also includes an extra feature, using the `@vocab` keyword, which ensures that any undefined term in a [=verifiable credential=] or a [=verifiable presentation=] is automatically mapped to a - URL prefixed with `https://www.w3.org/ns/credentials/issuer-dependent#`. + URL prefixed with `https://www.w3.org/ns/credentials/issuer-dependent#`. This is to allow early experimentation with terms during the development phase, without - requiring a formal definition in every cycle of that experimentation. + requiring a formal definition in every cycle of that experimentation. Note that developers SHOULD NOT use this feature in production; this - could lead to name clashes, yielding semantic ambiguities with other applications. + could lead to name clashes, yielding semantic ambiguities with other applications. Instead, they SHOULD define all the - terms, as described earlier in this section, to achieve proper interoperability. + terms, as described earlier in this section, to achieve proper interoperability.

      From 83dfad7ba2b4ae217be0a65781853f01745c1162 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 10 Feb 2024 15:48:06 -0500 Subject: [PATCH 8/8] Remove bad characters and reflow text in semantic interop section. --- index.html | 78 ++++++++++++++++++++++++++++++------------------------ 1 file changed, 43 insertions(+), 35 deletions(-) diff --git a/index.html b/index.html index a8b12a9ed..f4f7e11a3 100644 --- a/index.html +++ b/index.html @@ -3079,61 +3079,69 @@

      Extensibility

      Semantic Interoperability

      - When defining new terms in an application-specific vocabulary, developers MUST use globally unambiguous [=URLs=] to identify the terms. - Whenever possible, it is RECOMMENDED to re-use terms — and their corresponding URLs — defined by well-known, public vocabularies, - such as [[[?DCTERMS]]] [[?DCTERMS]] or [[[?schema-org]]] [[?schema-org]]. - If that is not possible, authors MUST define a new URL for each term. - When doing so, the general guidelines for [[LINKED-DATA]] are expected to be followed, in particular: +When defining new terms in an application-specific vocabulary, developers MUST +use globally unambiguous [=URLs=] to identify the terms. Whenever possible, it +is RECOMMENDED to re-use terms — and their corresponding URLs — defined by +well-known, public vocabularies, such as [[[?DCTERMS]]] [[?DCTERMS]] or +[[[?schema-org]]] [[?schema-org]]. If that is not possible, authors MUST +define a new URL for each term. When doing so, the general guidelines +for [[LINKED-DATA]] are expected to be followed, in particular:

      • - Human-readable documentation MUST be published, describing the semantics of and - the constraints on the use of each term. +Human-readable documentation MUST be published, describing the semantics of and +the constraints on the use of each term.
      • - It is RECOMMENDED to also publish the collection of all new terms as a machine-readable vocabulary - using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]]. +It is RECOMMENDED to also publish the collection of all new terms as a +machine-readable vocabulary using [[[?RDF-SCHEMA]]] [[?RDF-SCHEMA]].
      • - It SHOULD be possible to dereference the URL of a term, resulting in its description and/or formal definition. +It SHOULD be possible to dereference the URL of a term, resulting in its +description and/or formal definition.

      - Developers SHOULD follow the detailed checklist in - [[[?LD-BP]]] [[?LD-BP]] when defining a new vocabulary. +Developers SHOULD follow the detailed +checklist in [[[?LD-BP]]] [[?LD-BP]] when defining a new vocabulary.

      - Furthermore, a machine-readable description (that is, a - JSON-LD Context document) MUST be published at the URL specified - in the `@context` [=property=] for the vocabulary. - This context MUST map each term to its corresponding URL, possibly accompanied by further - constraints like the type of the property value. A human-readable document describing the expected order of values for - the `@context` [=property=] is also expected to be published by any implementer seeking interoperability. +Furthermore, a machine-readable description (that is, a +JSON-LD Context document) MUST be +published at the URL specified in the `@context` [=property=] for the +vocabulary. This context MUST map each term to its corresponding URL, possibly +accompanied by further constraints like the type of the property value. A +human-readable document describing the expected order of values for the +`@context` [=property=] is also expected to be published by any implementer +seeking interoperability.

      - When processing the active context defined by the base JSON-LD Context - document defined in this specification, compliant JSON-LD-based processors produce an error when a JSON-LD context - redefines any term. - The only way to change the definition of existing terms is to introduce a new term that clears the active context within - the scope of that new term. - Authors that are interested in this feature should read about the `@protected` - keyword in the JSON-LD 1.1 specification. +When processing the active +context defined by the base JSON-LD Context document defined in this specification, compliant JSON-LD-based +processors produce an error when a JSON-LD context +redefines any term. The only way to change the definition of existing +terms is to introduce a new term that clears the active context within the scope +of that new term. Authors that are interested in this feature should read about +the `@protected` +keyword in the JSON-LD 1.1 specification.

      - The base JSON-LD Context file for this specification also includes an extra feature, using the - `@vocab` keyword, which ensures - that any undefined term in a [=verifiable credential=] or a [=verifiable presentation=] is automatically mapped to a - URL prefixed with `https://www.w3.org/ns/credentials/issuer-dependent#`. - This is to allow early experimentation with terms during the development phase, without - requiring a formal definition in every cycle of that experimentation. - Note that developers SHOULD NOT use this feature in production; this - could lead to name clashes, yielding semantic ambiguities with other applications. - Instead, they SHOULD define all the - terms, as described earlier in this section, to achieve proper interoperability. +The base JSON-LD Context file for this specification also includes an extra +feature, using the `@vocab` +keyword, which ensures that any undefined term in a [=verifiable credential=] or +a [=verifiable presentation=] is automatically mapped to a URL prefixed with +`https://www.w3.org/ns/credentials/issuer-dependent#`. This is to allow early +experimentation with terms during the development phase, without requiring a +formal definition in every cycle of that experimentation. Note that developers +SHOULD NOT use this feature in production; this could lead to name clashes, +yielding semantic ambiguities with other applications. Instead, they SHOULD +define all the terms, as described earlier in this section, to achieve proper +interoperability.