Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add warnings related to @vocab usage #1524

Merged
merged 6 commits into from
Jul 15, 2024
Merged

Add warnings related to @vocab usage #1524

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
935a094
Warn interop harm of using `@vocab`.
msporny Jul 6, 2024
9aebb5e
Update Getting Started section to not use issuer-dependent terms.
msporny Jul 6, 2024
9f46e6d
Provide guidance on understanding JSON-LD contexts and `@vocab`.
msporny Jul 6, 2024
33512b0
Fix grammar in `@vocab` usage section.
msporny Jul 6, 2024
3069379
Note that compaction can be used to remove unknown contexts.
msporny Jul 8, 2024
c4d3da3
Fine tune guidance on `@vocab` usage.
msporny Jul 15, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
74 changes: 50 additions & 24 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1172,9 +1172,9 @@ <h3>Getting Started</h3>

<p>
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 credential=]. Developers can copy the template below and paste it
into common [=verifiable credential=] tooling to start issuing, holding, and
verifying prototype credentials.
</p>

<p>
Expand All @@ -1183,14 +1183,18 @@ <h3>Getting Started</h3>
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.
</p>

<pre class="example nohighlight" title="A template for creating prototype verifiable credentials">
<pre class="example nohighlight"
title="A template for creating prototype verifiable credentials">
{
"@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"
Expand All @@ -1201,12 +1205,14 @@ <h3>Getting Started</h3>
<p>
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
<a href="#extensibility"></a>. 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
would then be replaced with the URL of a use-case-specific context. This
process is covered in Section <a href="#extensibility"></a>. 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.
</p>

</section>
Expand Down Expand Up @@ -4400,11 +4406,11 @@ <h3>JSON-LD</h3>
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
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 to be expressed in the
`@context` value.
processing=] and not expecting the `@base` and/or `@vocab` value to be
expressed in the `@context` value.
</p>

<p>
Expand All @@ -4415,22 +4421,42 @@ <h3>JSON-LD</h3>

<ul>
<li>
Use of JSON-LD keywords in the `@context` value that globally modify document
value processing, such as global settings of `@base`
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`
</li>
<li>
In-line declaration of JSON-LD contexts in the `@context` property.
Use of JSON-LD contexts that override declarations in previous contexts, such as
resetting `@vocab`
</li>
<li>
In-line declaration of JSON-LD contexts in the `@context` property
</li>
<li>
Use of full URLs for JSON-LD terms and types (e.g.,
`https://www.w3.org/2018/credentials#VerifiableCredential` or
`https://vocab.example/myvocab#SomeNewType`) instead of the short forms of
any such values (e.g., `VerifiableCredential` or `SomeNewType`) that are
either explicitly defined as JSON-LD `@context` mappings (e.g.,
`https://www.w3.org/ns/credentials/v2`) or are implicitly defined via the
`@vocab` feature that applies to all undefined terms.
explicitly defined as JSON-LD `@context` mappings (e.g.,
`https://www.w3.org/ns/credentials/v2`)
</li>
</ul>
</ul>

<p>
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
msporny marked this conversation as resolved.
Show resolved Hide resolved
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, at least to the extent that it affects
the semantics of the terms that are used by their application. Applications MAY
use JSON-LD <a data-cite="JSON-LD11-API#compaction-algorithms">compaction
algorithms</a> 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.
Comment on lines +4456 to +4459
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some additional detail might be needed, with the addition of that sentence. I think this, because I don't know (and I haven't been able to figure it out, after more than a few minutes reading the linked page and others. I had thought I had a good grasp of JSON-LD mechanics, but this makes me wonder!) how the suggested transformation would work. Maybe add some more-descriptive, psuedo-algorithmic language here, with fewer low-level details than the linked page?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm thinking that this statement is going to require it's own section. Both in the Data Integrity spec, and possibly in the VCDM spec. People seem to be requesting it over here (see item 3): w3c/vc-data-integrity#272 (comment)

If we get consensus to do item 3 (above), then I expect we'll dedicate a section to that sentence. So, we can take it out for now, or leave it in and expand upon it later. I'm fine either way.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Either will work for me, for now, if a tracking issue is opened before/upon merge of this PR.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is now being tracked in #1529

</p>

<section>
<h3>Syntactic Sugar</h3>
Expand Down