From b64affe90a66dabcdf17d0fbc52e500abe710654 Mon Sep 17 00:00:00 2001 From: Benjamin Young Date: Thu, 7 Sep 2023 20:57:26 -0400 Subject: [PATCH] Explain JSON-LD further. Addresses #1227. --- index.html | 164 ++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 157 insertions(+), 7 deletions(-) diff --git a/index.html b/index.html index db34f17b9..b830090c5 100644 --- a/index.html +++ b/index.html @@ -3951,6 +3951,155 @@

Syntaxes

JSON-LD

+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. +

+ +

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

+ +

+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. +

+ +

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

+ +

+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. +

+ +

+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. +

+ +

+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. +

+ +
+

Extending JSON

+ +

+[[!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. +

+ +

+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. +

+ +

+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. +

+ +

+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. +

+ +

+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. +

+ +

+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. +

+ +

+[[!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. +

+
+ +
+

JSON-LD Syntax

+ +

[[!JSON-LD]] is a JSON-based format used to serialize Linked Data. The syntax is designed to easily integrate into deployed systems already using JSON, @@ -3958,18 +4107,18 @@

JSON-LD

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. -

+

-

+

[[!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 @context property. The JSON-LD context is described in detail in the [[!JSON-LD]] specification and its use is elaborated on in Section . -

+

-

+

Multiple contexts MAY be used or combined to express any arbitrary information about verifiable credentials in idiomatic JSON. The JSON-LD context, @@ -3977,15 +4126,16 @@

JSON-LD

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. -

+

-

+

This specification restricts the usage of JSON-LD representations of the data model. JSON-LD compact document form MUST be utilized for all representations of the data model in the base media type, `application/vc+ld+json`. -

+

+

Syntactic Sugar