Skip to content

Commit

Permalink
Explain JSON-LD further.
Browse files Browse the repository at this point in the history 
Addresses #1227.
  • Loading branch information
@BigBlueHat
BigBlueHat committed Sep 8, 2023
1 parent 929edc8 commit 3932fb4
Showing 1 changed file with 157 additions and 7 deletions.
164 changes: 157 additions & 7 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3951,41 +3951,191 @@ <h2>Syntaxes</h2>
<h3>JSON-LD</h3>

<p>
The world of credentials is vast and varied. A physical wallet places
relatively few constraints on the shape and size of those credentials–and it
places no restriction on their contents. Likewise, Verifiable Credential Data
Model’s use of [[!JSON-LD]] provides the consistent shape for all compliant
Verifiable Credentials, so that digital wallets can store credentials with
widely varying content, providing value to a plethora of communities, and
enabling many diverse use cases–from coupons to authentication.
</p>

<p>
Consequently, Wallet providers can have the confidence that any Verifiable
Credential will “fit” while Issuers and Verifiers benefit from a common
exchange representation that provides built in extensibility without the
high costs from centralized terminology registration or JSON format churn.
</p>

<p>
Issuers can add claims terminology unique to their communities via [[!JSON-LD]]’s
context files rather than be dependent on a single, centralized registry
system. This webby decentralized approach provides infinite scalability. Future
standardization efforts, then focus on vocabulary definitions and
object-oriented modeling provided by communities of practice vs. idiosyncratic
JSON format creation for individual use cases or scenarios.
</p>

<p>
Verifiers can furthermore lean on the similarly provided proof mechanisms
without writing new document parsers for each new security mechanism.
</p>

<p>
Lastly, Wallets can then move these consistently shaped credentials between
Issuers and Verifiers without the need to create new storage systems for each
format with the confidence that each relying party can depend on consistent
grammatical structures and inbuilt object-oriented data modeling.
</p>

<p>
The Verifiable Credential Data Model’s consistent object-oriented modeling
constraints are familiar to developers and enable better reuse and composition
of data. That modeling is built from clean expressions of subject, property,
values which comprise the shape of each atomic claim within a VCDM credential.
This approach empowers Wallets to store any credential shaped in this way (as
with physical wallets) and to index the contained claims made across all the
holder’s credentials such that credentials may be quickly and easily found and
presented when needed.
</p>

<p>
This foundational data modeling and grammatical structure is provided through
the addition of a single `@context` key which identifies context files that map
otherwise idiosyncratic and often ephemeral terms into universally shareable,
collision resistant vocabularies. This context mechanism provides the
underlying subject, property, value graph-based data model which enables
aggregation, collation, and even separation of the individual statements held
within the [[!JSON-LD]] graph and brings the object-oriented structure to previously
freeform JSON documents.
</p>

<section>
<h3>Extending JSON</h3>

<p>
[[!JSON-LD]] brings context, meaning, and object-oriented modeling to previously
idiosyncratic JSON formats. It provides that contextualization by mapping
colloquial terms used within a JSON object to term and type definitions with
universal identifiers in the form of URLs. This prevents term collisions and
need for yet-more-JSON-formats by providing a common extensible JSON structure
with minimal requirements for extensibility. The additional grammatical
constraints at this foundational layer prevent the need for endless invention
and support of use case specific JSON models with idiosyncratic terms and
unique to the implementation approaches to data modeling, value usage, and
parsing approaches.
</p>

<p>
A JSON document becomes a [[!JSON-LD]] document when it includes an `@context`
property with a URL associated with a context file. The context file provides
the mapping between the idiosyncratic in-document terminology and universally
shareable identifiers and value definitions. This provides not only
contextualization and meaning, but also reusability through universally
shareable terms and object-oriented structuring. This enables aggregation and
collation of data without the need for additional upfront integration
development time for each newly discovered JSON format. Future community
credential definitions will focus on the use of their terminology rather than
force implementers to parse another unique JSON format specific to that
community or use case.
</p>

<p>
Consequently, without any additional processing a JSON document gains the value
of an in-message association with its terminology definitions. Details on
processing VCDM documents consistently with the context file, but without
[[!JSON-LD]] tooling can be found in the “JSON Processing” section below.
</p>

<p>
The referenced context file provides the foundation for a consistent
grammatical layer based on object-oriented modeling and community driven
terminology selection which enables coexistence of various JSON tree shapes and
colloquial terms while preventing likely terminology collisions or creating a
need to write new tree traversal code for every new media type or JSON shape or
parsing approach.
</p>

<p>
Verifiable Credentials Data Model uses this consistent foundation to provide a
common layer across all credentials, presentations, and transaction formats
within a single, consistently parseable media type definition. This allows for
ecosystem extensibility without requiring a centralized registry to be updated
for every new application or community. The core data model terms are
registered and specified while communities are free to build on that foundation
through their own specification process. The terminology mappings are
referenced from the VCDM document removing the need for an ever changing
landscape of “private claims” or narrowly defined “public claims” housed in a
centralized registry. The common grammar and object-oriented data modeling
remain the same and properly contextualized terms can commingle. Applications
and communities can easily extend what is claimed and signed through the use of
vocabularies.
</p>

<p>
The underpinning graph data model enables signing of the document’s statements
rather than just the envelope it’s contained in. When using this feature, the
data–while signed–is accessible in the same way it had been prior to signing
allowing for easier indexing, storage, and in-Wallet selection.The existence of
the proof within the object-oriented graph model provides confidence that not
only the wrapping structure was signed, but its actual informational contents.
This enables selective disclosure of statements within the same JSON format
avoiding the ever increasing cost of retooling for new disclosure formats or
new envelope types. The proof is consistently placed alongside the claims.
</p>

<p>
[[!JSON-LD]] provides Verifiable Credentials with a consistent grammatical
foundation, object-oriented modeling, and collision-free terminology sharing
which allows for ecosystem growth, document format iteration (rather than
reinvention), and an extensible framework for new cryptographic proof
mechanisms without altering or damaging the underlying data structure. This
creates an economies of scale which reduces development time, decreased
retooling cost, increases time to market, and provides long term stability for
Issuers, Verifiers, and Wallets.
</p>
</section>

<section>
<h3>JSON-LD Syntax</h3>

<p>
[[!JSON-LD]] is a JSON-based format used to serialize
<a href="https://www.w3.org/TR/ld-glossary/#linked-data">Linked Data</a>. The
syntax is designed to easily integrate into deployed systems already using JSON,
and provides a smooth upgrade path from JSON to [[!JSON-LD]]. It is primarily
intended to be a way to use Linked Data in Web-based programming environments,
to build interoperable Web services, and to store Linked Data in JSON-based
storage engines.
</p>
</p>

<p>
<p>
[[!JSON-LD]] is useful when extending the data model described in this
specification. Instances of the data model are encoded in JSON-LD compact
form [[!JSON-LD]] and include the <code>@context</code> <a>property</a>. The
<a href="https://www.w3.org/TR/json-ld/#the-context">JSON-LD context</a>
is described in detail in the [[!JSON-LD]] specification and its use is
elaborated on in Section <a href="#extensibility"></a>.
</p>
</p>

<p>
<p>
Multiple contexts MAY be used or combined to express any arbitrary information
about <a>verifiable credentials</a> in idiomatic JSON. The
<a href="https://www.w3.org/TR/json-ld/#the-context">JSON-LD context</a>,
available at <code>https://www.w3.org/ns/credentials/v2</code>, 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 <code>https://www.w3.org/2018/credentials</code>.
</p>
</p>

<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">compact document
form</a> MUST be utilized for all representations of the data model in the
base media type, `application/vc+ld+json`.
</p>
</p>
</section>

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

0 comments on commit 3932fb4

Please sign in to comment.