From 935a094b3b3bfdaf982b67e29904762081a79d3f Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 6 Jul 2024 14:29:36 -0400 Subject: [PATCH 1/6] Warn interop harm of using `@vocab`. --- index.html | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/index.html b/index.html index 09c432366..3d6373137 100644 --- a/index.html +++ b/index.html @@ -4400,11 +4400,11 @@

JSON-LD

documents=] are advised that interoperability might be reduced if JSON-LD keywords in the `@context` value are used to globally affect values in a [=verifiable credential=] or [=verifiable presentation=], such as by -globally setting the `@base` keyword. For example, globally setting these values +setting the `@base` or `@vocab` keyword. For example, setting these values might trigger a failure in a mis-implemented JSON Schema check on the `@context` value in an implementation that is performing [=type-specific credential -processing=] and not expecting the `@base` value to be expressed in the -`@context` value. +processing=] and not expecting the `@base` value or `@vocab` value to be +expressed in the `@context` value.

@@ -4415,20 +4415,23 @@

JSON-LD

From 9aebb5ec61a7fb612fb5b3a01709875d3c480376 Mon Sep 17 00:00:00 2001 From: Manu Sporny Date: Sat, 6 Jul 2024 15:27:42 -0400 Subject: [PATCH 2/6] Update Getting Started section to not use issuer-dependent terms. --- index.html | 32 +++++++++++++++++++------------- 1 file changed, 19 insertions(+), 13 deletions(-) diff --git a/index.html b/index.html index 3d6373137..70cf3c158 100644 --- a/index.html +++ b/index.html @@ -1172,9 +1172,9 @@

Getting Started

This specification is designed to ease the prototyping of new types of -[=verifiable credentials=]. Developers can copy the -template below and paste it into common [=verifiable credential=] -tooling to start issuing, holding, and verifying prototype credentials. +[=verifiable credentials=]. Developers can copy the template below and paste it +into common [=verifiable credential=] tooling to start issuing, holding, and +verifying prototype credentials.

@@ -1183,14 +1183,18 @@

Getting Started

each property-value pair in the `credentialSubject` object expresses a particular property of the credential subject. Once a developer has added a number of these property-value combinations, the modified object can be sent to -the [=verifiable credential=] issuer software and a [=verifiable credential=] will -be created for the developer. From a prototyping standpoint, that is all a +the [=verifiable credential=] issuer software and a [=verifiable credential=] +will be created for the developer. From a prototyping standpoint, that is all a developer needs to do.

- 
+        
 {
-  "@context": ["https://www.w3.org/ns/credentials/v2"],
+  "@context": [
+    "https://www.w3.org/ns/credentials/v2",
+    "https://www.w3.org/ns/credentials/examples/v2"
+  ],
   "type": ["VerifiableCredential", "MyPrototypeCredential"],
   "credentialSubject": {
     "mySubjectProperty": "mySubjectValue"
@@ -1201,12 +1205,14 @@ 
Getting Started

         

 Once a developer has prototyped their credential to a point where they believe
 all of the credential properties are stable, it is advised that they generate
-vocabulary and context files for their application and publish them at stable URLs
-so that other developers can use the same vocabulary and context to achieve
-interoperability. This process is covered in Section
-. Alternatively, developers can reuse existing vocabulary
-and context files that happen to fit their use case. They can explore the
-[[[VC-SPECS]]] [[VC-SPECS]] for reusable resources.
+vocabulary and context files for their application and publish them at stable
+URLs so that other developers can use the same vocabulary and context to achieve
+interoperability. The `https://www.w3.org/ns/credentials/examples/v2` URL above
+will then be replaced with the URL to an application-specific context. This
+process is covered in Section . Alternatively,
+developers can reuse existing vocabulary and context files that happen to fit
+their use case. They can explore the [[[VC-SPECS]]] [[VC-SPECS]] for reusable
+resources.
         

 
       

From 9f46e6d4b7939350cee42e8f26ae098d1ad269cb Mon Sep 17 00:00:00 2001
From: Manu Sporny 
Date: Sat, 6 Jul 2024 16:05:11 -0400
Subject: [PATCH 3/6] Provide guidance on understanding JSON-LD contexts and
 `@vocab`.

---
 index.html | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/index.html b/index.html
index 70cf3c158..d0706dc44 100644
--- a/index.html
+++ b/index.html
@@ -4439,7 +4439,21 @@ 
JSON-LD

 explicitly defined as JSON-LD `@context` mappings (e.g.,
 `https://www.w3.org/ns/credentials/v2`).
           
-       
+        
+
+        

+While this specification warns against the usage of `@vocab`, there are
+legitimate usages of the feature, such as to ease experimentation, development,
+and localized deployment. If an application developer desires to use `@vocab` in
+production, which is strongly advised against, they are urged to understand that
+any usage of `@vocab` will disable undefined term error reporting, and
+subsequent usage will override previous `@vocab` declarations. Subsequent usage
+of `@vocab` changes the semantics of the information contained in the document
+and so it is important to understand how these changes will affect the
+application being developed. Application developers MUST understand every
+JSON-LD context used by their application to the extent that it affects
+the semantics of the terms that are used by their application.
+        

 
         

           
Syntactic Sugar


From 33512b05f9c3e9f299817e6d6403b78264822350 Mon Sep 17 00:00:00 2001
From: Manu Sporny 
Date: Sat, 6 Jul 2024 18:25:22 -0400
Subject: [PATCH 4/6] Fix grammar in `@vocab` usage section.

Co-authored-by: Ted Thibodeau Jr 
---
 index.html | 40 ++++++++++++++++++++--------------------
 1 file changed, 20 insertions(+), 20 deletions(-)

diff --git a/index.html b/index.html
index d0706dc44..742af1569 100644
--- a/index.html
+++ b/index.html
@@ -1172,7 +1172,7 @@ 
Getting Started

 
         

 This specification is designed to ease the prototyping of new types of
-[=verifiable credentials=]. Developers can copy the template below and paste it
+[=verifiable credential=]. Developers can copy the template below and paste it
 into common [=verifiable credential=] tooling to start issuing, holding, and
 verifying prototype credentials.
         

@@ -1183,7 +1183,7 @@ 
Getting Started

 each property-value pair in the `credentialSubject` object expresses a
 particular property of the credential subject. Once a developer has added a
 number of these property-value combinations, the modified object can be sent to
-the [=verifiable credential=] issuer software and a [=verifiable credential=]
+the [=verifiable credential=] issuer software, and a [=verifiable credential=]
 will be created for the developer. From a prototyping standpoint, that is all a
 developer needs to do.
         

@@ -1206,9 +1206,9 @@ 
Getting Started

 Once a developer has prototyped their credential to a point where they believe
 all of the credential properties are stable, it is advised that they generate
 vocabulary and context files for their application and publish them at stable
-URLs so that other developers can use the same vocabulary and context to achieve
+URLs, so that other developers can use the same vocabulary and context to achieve
 interoperability. The `https://www.w3.org/ns/credentials/examples/v2` URL above
-will then be replaced with the URL to an application-specific context. This
+would then be replaced with the URL of an application-specific context. This
 process is covered in Section . Alternatively,
 developers can reuse existing vocabulary and context files that happen to fit
 their use case. They can explore the [[[VC-SPECS]]] [[VC-SPECS]] for reusable
@@ -4406,10 +4406,10 @@ 
JSON-LD

 documents=] are advised that interoperability might be reduced if JSON-LD
 keywords in the `@context` value are used to globally affect values in a
 [=verifiable credential=] or [=verifiable presentation=], such as by
-setting the `@base` or `@vocab` keyword. For example, setting these values
-might trigger a failure in a mis-implemented JSON Schema check on the `@context`
+setting either or both of the `@base` or `@vocab` keywords. For example, setting these values
+might trigger a failure in a mis-implemented JSON Schema test of the `@context`
 value in an implementation that is performing [=type-specific credential
-processing=] and not expecting the `@base` value or `@vocab` value to be
+processing=] and not expecting the `@base` and/or `@vocab` value to be
 expressed in the `@context` value.
         

 
@@ -4422,14 +4422,14 @@ 
JSON-LD

         
    
           
  • 
 In-line declaration of JSON-LD keywords in the `@context` value that globally
-modify document term and value processing, such as setting `@base` or `@vocab`,
+modify document term and value processing, such as setting `@base` or `@vocab`
           
    • 
           
  • 
 Use of JSON-LD contexts that override declarations in previous contexts, such as
-resetting `@vocab`,
+resetting `@vocab`
           
    • 
           
  • 
-In-line declaration of JSON-LD contexts in the `@context` property, and
+In-line declaration of JSON-LD contexts in the `@context` property
           
    • 
           
  • 
 Use of full URLs for JSON-LD terms and types (e.g.,
@@ -4437,21 +4437,21 @@ 
    JSON-LD
    
 `https://vocab.example/myvocab#SomeNewType`) instead of the short forms of
 any such values (e.g., `VerifiableCredential` or `SomeNewType`) that are
 explicitly defined as JSON-LD `@context` mappings (e.g.,
-`https://www.w3.org/ns/credentials/v2`).
+`https://www.w3.org/ns/credentials/v2`)
           
    • 
         

 
         

-While this specification warns against the usage of `@vocab`, there are
-legitimate usages of the feature, such as to ease experimentation, development,
-and localized deployment. If an application developer desires to use `@vocab` in
-production, which is strongly advised against, they are urged to understand that
-any usage of `@vocab` will disable undefined term error reporting, and
-subsequent usage will override previous `@vocab` declarations. Subsequent usage
-of `@vocab` changes the semantics of the information contained in the document
-and so it is important to understand how these changes will affect the
+While this specification cautions against the use of `@vocab`, there are
+legitimate uses of the feature, such as to ease experimentation, development,
+and localized deployment. If an application developer wants to use `@vocab` in
+production — even though strongly advised against — they are urged to understand that
+any use of `@vocab` will disable reporting of "undefined term" errors, and
+later use(s) will override any previous `@vocab` declaration(s). Different values
+of `@vocab` can change the semantics of the information contained in the document,
+so it is important to understand whether and how these changes will affect the
 application being developed. Application developers MUST understand every
-JSON-LD context used by their application to the extent that it affects
+JSON-LD context used by their application, at least to the extent that it affects
 the semantics of the terms that are used by their application.
         

 

From 3069379af855e971c5b969163a0eb4e438d98bba Mon Sep 17 00:00:00 2001
From: Manu Sporny 
Date: Mon, 8 Jul 2024 17:57:30 -0400
Subject: [PATCH 5/6] Note that compaction can be used to remove unknown
 contexts.

Co-authored-by: Ted Thibodeau Jr 
Co-authored-by: Dave Longley 
---
 index.html | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 742af1569..48002a704 100644
--- a/index.html
+++ b/index.html
@@ -1208,7 +1208,7 @@ 
Getting Started

 vocabulary and context files for their application and publish them at stable
 URLs, so that other developers can use the same vocabulary and context to achieve
 interoperability. The `https://www.w3.org/ns/credentials/examples/v2` URL above
-would then be replaced with the URL of an application-specific context. This
+would then be replaced with the URL of a use-case-specific context. This
 process is covered in Section . Alternatively,
 developers can reuse existing vocabulary and context files that happen to fit
 their use case. They can explore the [[[VC-SPECS]]] [[VC-SPECS]] for reusable
@@ -4452,7 +4452,10 @@ 
JSON-LD

 so it is important to understand whether and how these changes will affect the
 application being developed. Application developers MUST understand every
 JSON-LD context used by their application, at least to the extent that it affects
-the semantics of the terms that are used by their application.
+the semantics of the terms that are used by their application. Applications MAY
+use JSON-LD compaction
+algorithms to transform a document that uses an unknown JSON-LD context
+to one that does not, so the new document's terms will match expectations.
         

 
         


From c4d3da36cfbe2ca9c32df1d59f635eacbebfc922 Mon Sep 17 00:00:00 2001
From: Manu Sporny 
Date: Mon, 15 Jul 2024 10:28:59 -0400
Subject: [PATCH 6/6] Fine tune guidance on `@vocab` usage.

Co-authored-by: Gabe <7622243+decentralgabe@users.noreply.github.com>
---
 index.html | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

diff --git a/index.html b/index.html
index 48002a704..2c946edf3 100644
--- a/index.html
+++ b/index.html
@@ -4445,8 +4445,9 @@ 
JSON-LD

 While this specification cautions against the use of `@vocab`, there are
 legitimate uses of the feature, such as to ease experimentation, development,
 and localized deployment. If an application developer wants to use `@vocab` in
-production — even though strongly advised against — they are urged to understand that
-any use of `@vocab` will disable reporting of "undefined term" errors, and
+production, which is advised against to reduce term collisions and leverage the benefits
+of semantic interoperability, they are urged to understand that any use of `@vocab` will
+disable reporting of "undefined term" errors, and
 later use(s) will override any previous `@vocab` declaration(s). Different values
 of `@vocab` can change the semantics of the information contained in the document,
 so it is important to understand whether and how these changes will affect the