Propose better JSON-LD processing text

index.html

@@ -4240,47 +4240,67 @@ <h2>HTTP</h2>
         </section>
 
         <section class="informative">
-          <h2>JSON Processing</h2>
-
+          <h2>Processing JSON-LD</h2>
           <p>
 While the media types describing conforming documents defined in this
-specification always express JSON-LD, JSON-LD processing is not required to be
-performed, since JSON-LD is JSON. Some scenarios where processing a
-<a>verifiable credential</a> or a <a>verifiable presentation</a> as JSON is
-desirable include, but are not limited to:
+specification always express JSON-LD, RDF processing is not required to be
+performed, since JSON-LD is a concrete RDF syntax as described in [RDF11-CONCEPTS]. 
+Hence, a JSON-LD document is both an RDF document and a JSON document and correspondingly represents an instance of an RDF data model.
+          </p>
+           <p>
+RDF is a technology for modeling graphs of statements. Each statement is a single subject-property-value
+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 to 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 present, using the <code>@id</code> JSON key, which is aliased in this specification to <code>id</code>.
+See <a href="JSON-LD11##relationship-to-rdf">Relationship to RDF</a> for more details.
+          </p>
+           <p>
+As JSON can be used to express all different kinds of information, a consumer of a particular JSON
+document can only properly interpret the authors intent if they possess information that contextualizes
+and disambiguates it from other possible expressions. Information to assist with this interpretation can either 
+be wholly external to the JSON document or linked from within it. Compact JSON-LD documents include a <code>@context</code> property that internally expresses or links to contextual information and, per the JSON-LD specification, these documents follow object-oriented organizational principles to express <a>claims</a>. These features enable generalized processors to be written to convert JSON-LD documents from one context to another, but this is not needed when consumers receive JSON-LD documents that already use the context and shape that they expect. Authors of JSON-LD documents, such as <a>issuers</a> of <a>verifiable credentials</a>, are required to provide proper JSON-LD contexts and follow these rules in order to facilitate interoperability.
+          </p>
+           <p>
+The text below helps consumers understand how to ensure a JSON-LD document is expressed in a context
+and shape that their application already understands such that they do not need to transform it in
+order to consume its contents. Notably, this does not mean that consumers do not need to understand any context at all, rather, consuming applications only need to understand a chosen set of contexts and document shapes to work with and not others. Issuers can publish contexts and information about their <a>verifiable credentials</a> to aid consumers who do not use generalized processors, just like would be done with any other JSON-formatted data.
+          </p>
+          <p>
+Processing <a>verifiable credentials</a> or <a>verifiable presentations</a>
+by transforming JSON-LD to RDF might be desirable under the following conditions:
           </p>
-
           <ul>
             <li>
-Before securing or after verifying content
-that requires <a href="https://csrc.nist.gov/glossary/term/data_integrity">data
-integrity</a>, such as a
-<a>verifiable credential</a> or <a>verifiable presentation</a>.
+Before securing or after verifying <a>verifiable credentials</a> or <a>verifiable presentations</a>,
+in cases where the issuer made use of the underlying RDF Dataset model to provide details regarding 
+their intended expression of the <a href="#verifiable-credential-graphs">Verifiable Credential Graphs</a>.
             </li>
             <li>
-When performing JSON Schema validation, as described in Section
+After performing JSON Schema validation, as described in Section
 <a href="#data-schemas"></a>.
             </li>
             <li>
 When serializing or deserializing <a>verifiable credentials</a> or
-<a>verifiable presentations</a> into systems that store or index their contents.
+<a>verifiable presentations</a> into systems that store or index data in 
+Turtle [[?TURTLE]], N-Quads [[?N-QUADS]], or JSON-LD [[?JSON-LD11]].
             </li>
             <li>
-When operating on <a>verifiable credentials</a> or <a>verifiable
-presentations</a> in a software application, after verification or validation
-is performed for securing mechanisms that require an understanding of
-and/or processing of JSON-LD.
+When consuming <a>verifiable credentials</a> or <a>verifiable
+presentations</a> in a software application, after verification 
+is performed for securing mechanisms that do not require JSON-LD transformations.
             </li>
             <li>
-When an application chooses to process the media type using the `+json`
+When an application chooses to process the media type using the `+ld+json`
 structured media type suffix.
             </li>
           </ul>
 
           <p>
-That is, JSON processing is allowed as long as the document being consumed or
-produced is a <a>conforming document</a>. If JSON processing is desired, an
-implementer is advised to follow the following rule:
+Instead of performing general JSON-LD processing, application-specific processing is allowed as long as the document being consumed or
+produced is a <a>conforming document</a>.
+          </p>
+
+         <h3>Application-specific Processing</h3>
           </p>
 
           <ul>
@@ -4297,19 +4317,68 @@ <h2>JSON Processing</h2>
 implementing the rule above. This can ensure proper term identification,
 typing, and order, when a JSON document is processed as JSON-LD.
           </p>
+          <p>
+However, the intention of the issuer is not preserved, unless the rules expressed
+in the <code>@context</code> are followed, and the resulting <a href="#verifiable-credential-graphs">Verifiable Credential Graphs</a>, and their exact RDF types, and node and edge structure is understood by the verifier. By following the rules laid out in this section, applications can be hard-coded against
+specific contexts, just as they are commonly hard-coded to consume other
+application-specific JSON formats.
+          </p>
 
           <p>
-The rule above guarantees semantic interoperability between JSON and JSON-LD for
-literal JSON keys mapped to URIs by the `@context` mechanism. While JSON-LD
-processors will use the specific mechanism provided and can verify that all
-terms are correctly specified, JSON-based processors implicitly accept the same
-semantics without performing any JSON-LD transformations, but instead by
+          </p>
+While some RDF processors will use the language features of JSON-LD and can verify that all
+terms are correctly specified, JSON-LD processors explicitly accept the same
+semantics without performing any RDF transformations, but instead by
 applying the above rules. In other words, the context in which the data exchange
-happens is explicitly stated for both JSON and JSON-LD by using the same
-mechanism. With respect to JSON-based processors, this is achieved in a
-lightweight manner, without having to use JSON-LD processing libraries.
+happens is explicitly stated for both RDF and JSON-LD by using the same
+mechanism. With respect to JSON-LD-based processors, this is achieved in a
+lightweight manner, without having to use RDF processing libraries.
+          </p>
+        </section>
+        <section>
+          <h2>Processing RDF</h2>
+          <p>
+Issuers are advised that while conforming documents are expressed as compact JSON-LD,
+not all Holders or Verifiers will understand expressions of intention that are only visible 
+after RDF processing has occured.
+          </p>
+          <p>
+Some of the best features of JSON-LD are only possible by applying its language features to the 
+terms defined in the <code>@context</code>.
+          </p>
+          <p>
+Implementers are advised that <code>id</code> and <code>type</code> have been
+aliased to <code>@id</code> and <code>@type</code>, and are marked <code>@protected</code>.
+Depending on the software libraries used, attempts to redefine these terms might raise processing errors.
+Implementers interested in understanding what <code>@id</code> means 
+are advised to review <a href="https://www.w3.org/TR/json-ld11/#node-identifiers">Node Identifiers</a>, and
+<a href="https://www.w3.org/TR/json-ld11/#specifying-the-type">Specifying the Type</a>.
+          </p>
+          <p>
+Implementers are advised that object member, and array element order are not preserved by default in JSON-LD,
+therefore, <a>issuers</a> intending to communicate the orders of object
+members and/or array elements might need to leverage language and/or other
+advanced features of JSON-LD.
+See <a href="https://www.w3.org/TR/json-ld11/#sets-and-lists">Value Ordering</a>.
+          </p>
+          <p>
+Implementers are advised that while minimal processing of a document might
+make it appear that claims are related,
+the <code>https://www.w3.org/ns/credentials/v2</code> `@context` leverages
+<code>@container</code> and <code>@graph</code> to separate information
+graphs; in particular, these are used to separate the graphs related to
+<a>verifiable credentials</a>, <a>verifiable presentations</a>, and
+<a href="#dfn-embedded-proof">embedded proofs</a>.
+          </p>
+          <p>
+<a>Issuers</a> and <a>holders</a> might apply these same techniques to
+unambiguously communicate their intention regarding structured claims in
+<a>verifiable credentials</a> and <a>verifiable presentations</a>.
+<a>Verifiers</a> that do not understand or process JSON-LD will not
+be aware of these differences, and confusion between the intentions of the
+<a>issuer</a> and the <a>holder</a> could lead to unexpected processing
+behavior by <a>verifiers</a>.
           </p>
-
         </section>
       </section>