Explain JSON-LD further.

index.html

@@ -3950,42 +3950,197 @@ <h2>Syntaxes</h2>
       <section>
         <h3>JSON-LD</h3>
 
-        <p>
+        <section class="informative">
+          <h4>Data Model Foundations</h4>
+          <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, the 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 of centralized terminology registration or JSON format churn.
+          </p>
+
+          <p>
+  Issuers can add claim terminology unique to their communities via [[!JSON-LD]]'s
+  context files rather than being dependent on a single, centralized registry
+  system. This webby, decentralized approach provides infinite scalability. Future
+  standardization efforts may then focus on vocabulary definitions and
+  object-oriented modeling provided by communities of practice rather than idiosyncratic
+  JSON format creation for individual use cases or scenarios.
+          </p>
+
+          <p>
+  Furthermore, Verifiers can furthermore lean on similarly provided proof mechanisms
+  without writing new document parsers for each new security mechanism.
+          </p>
+
+          <p>
+  Lastly, Wallets can move these consistently-shaped credentials between
+  Issuers and Verifiers without needing to create new storage systems for each
+  format, with the confidence that each relying party can depend on consistent
+  grammatical structures and in-built object-oriented data modeling.
+          </p>
+
+          <p>
+  The consistent object-oriented modeling constraints of the Verifiable
+  Credential Data Model (VCDM) are familiar to developers and enable better
+  reuse and composition of data. That modeling is built from clean expressions
+  of <em>subjects, properties, and values</em> (also referred to as <em>entities,
+  attributes, and values</em>, <em>E-A-V</em>, as well as <em>subjects, predicates, and
+  objects</em>, <em>S-P-O</em>) 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 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, and 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>
+
+        <section class="informative">
+          <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>
+The 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 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 in which 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 economies of scale which reduces development time, decreases
+retooling cost, decreases 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>