Skip to content

Commit

Permalink
Add section on Restriction to JSON-LD. Editorial clean up.
Browse files Browse the repository at this point in the history
  • Loading branch information
@msporny
msporny committed Jul 27, 2024
1 parent fea8cbc commit 53fed22
Showing 1 changed file with 92 additions and 90 deletions.
182 changes: 92 additions & 90 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1238,7 +1238,12 @@ <h3>Contexts</h3>
</p>
<p>
[=Verifiable credentials=] and [=verifiable presentations=] MUST include a
`@context` [=property=].
`@context` [=property=]. 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. One mechanism for
doing so is described in the Section on
<a data-cite="VC-DATA-INTEGRITY#validating-contexts">Validating Contexts</a> in
the [[[VC-DATA-INTEGRITY]]] specification.
</p>

<dl>
Expand Down Expand Up @@ -4294,108 +4299,36 @@ <h2>Syntaxes</h2>
<h3>JSON-LD</h3>

<p>
[[!JSON-LD11]] is a JSON-based format used to serialize
<a href="https://www.w3.org/TR/ld-glossary/#linked-data">Linked Data</a>.
Linked Data is modeled using Resource Description Framework (RDF).
RDF [[?RDF11-CONCEPTS]] is a technology for modeling graphs of statements. Each statement is a
JSON-LD is a JSON-based format [[!JSON-LD11]] used to serialize
<a href="https://www.w3.org/TR/ld-glossary/#linked-data">Linked Data</a>. Linked
Data is modeled using Resource Description Framework (RDF) [[?RDF11-CONCEPTS]].
RDF is a technology for modeling graphs of statements. Each statement is a
single <i>subject→property→value</i> (also known as
<i>entity→attribute→value</i>) relationship, which is referred to
as a <a>claim</a> in this specification. JSON-LD [[?JSON-LD11]] is a technology that enables
the expression of RDF using idiomatic JSON, enabling developers familiar with
JSON to write applications that consume RDF as JSON. In general, subjects are
<i>entity→attribute→value</i>) relationship, which is referred to as a
<a>claim</a> in this specification. JSON-LD is a technology that enables the
expression of RDF using idiomatic JSON, enabling developers familiar with JSON
to write applications that consume RDF as JSON. In general, subjects are
expressed as JSON objects with each property and value of the subject as a JSON
key and value, respectively. A special affordance is made to express an
identifier of a subject, if necessary, using the <code>id</code> key in this
specification. See
key and value, respectively. See
<a data-cite="?JSON-LD11#relationship-to-rdf">Relationship of JSON-LD to RDF</a>
for more details.
</p>
<p>
[[!JSON-LD11]] is useful when extending the data model described in this
specification. Instances of the data model are encoded in JSON-LD compacted
form [[!JSON-LD11]] and include the `@context` [=property=]. The
JSON-LD is useful when extending the data model described in this
specification. The concept of the
<a href="https://www.w3.org/TR/json-ld/#the-context">JSON-LD context</a>
is described in detail in the [[!JSON-LD11]] specification and its use is
is described in detail in the JSON-LD specification and its use is
elaborated on in Section <a href="#contexts"></a> and
Section <a href="#extensibility"></a>.
</p>

<p>
Multiple contexts MAY be used or combined to express any arbitrary information
about [=verifiable credentials=] in idiomatic JSON. The
<a href="https://www.w3.org/TR/json-ld/#the-context">JSON-LD context</a>,
available at `https://www.w3.org/ns/credentials/v2`, is a static
document that is never updated and can therefore be downloaded and cached client
side. The associated vocabulary document for the Verifiable Credentials Data
Model is available at `https://www.w3.org/2018/credentials`.
</p>

<p>
This specification restricts the usage of JSON-LD representations of
the data model. JSON-LD <a
href="https://www.w3.org/TR/json-ld/#compacted-document-form">compacted document
form</a> MUST be utilized for all representations of the data model in the
base media type, `application/vc`.
</p>

<p>
As elaborated upon in Section
<a href="#type-specific-credential-processing"></a>, some software applications
might not perform generalized JSON-LD processing. Authors of [=conforming
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 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` and/or `@vocab` value to be
expressed in the `@context` value.
</p>

<p>
In order to increase interoperability, [=conforming document=] authors are
urged to not use JSON-LD features that are not easily detected when performing
[=type-specific credential processing=]. These features include:
</p>

<ul>
<li>
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>
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
explicitly defined as JSON-LD `@context` mappings (e.g.,
`https://www.w3.org/ns/credentials/v2`)
</li>
</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, 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
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. One mechanism
for doing so is described in the Section on
<a data-cite="VC-DATA-INTEGRITY#validating-contexts">Validating Contexts</a> in
the [[[VC-DATA-INTEGRITY]]] specification.
about [=verifiable credentials=] in idiomatic JSON. The base
<a href="https://www.w3.org/TR/json-ld/#the-context">JSON-LD context</a> for
this specification is `https://www.w3.org/ns/credentials/v2`. The associated
vocabulary document for the Verifiable Credentials Data Model is available at
`https://www.w3.org/2018/credentials`.
</p>

<section>
Expand Down Expand Up @@ -4444,6 +4377,75 @@ <h3>Syntactic Sugar</h3>
</li>
</ul>
</section>

<section>
<h3>Restrictions on JSON-LD</h3>

<p>
This specification restricts the usage of JSON-LD representations of
the data model. JSON-LD <a
href="https://www.w3.org/TR/json-ld/#compacted-document-form">compacted document
form</a> MUST be utilized for all representations of the data model using the
`application/vc` base media type.
</p>

<p>
As elaborated upon in Section
<a href="#type-specific-credential-processing"></a>, some software applications
might not perform generalized JSON-LD processing. Authors of [=conforming
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 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` and/or `@vocab` value to be
expressed in the `@context` value.
</p>

<p>
In order to increase interoperability, [=conforming document=] authors are
urged to not use JSON-LD features that are not easily detected when performing
[=type-specific credential processing=]. These features include:
</p>

<ul>
<li>
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>
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
explicitly defined as JSON-LD `@context` mappings (e.g.,
`https://www.w3.org/ns/credentials/v2`)
</li>
</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, 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
application being developed.
</p>

</section>

<section>
<h3>Lists and Arrays</h3>
<p>
Expand Down

0 comments on commit 53fed22

Please sign in to comment.