clarify, add context, or otherwise improve examples (#457)

* work on simple example in sec 6

* Simple Structured SD-JWT work

* work on Complex Structured SD-JWT

* SD-JWT-based Verifiable Credentials work

* Work on W3C Verifiable Credentials Data Model v2.0

* Try to better link the digests to the Disclosures in the respective text around examples

* Document History is part of the document too

* typo fix

* actually...

Author: bc-pi

draft-ietf-oauth-selective-disclosure-jwt.md

@@ -716,32 +716,32 @@ lines in RFCs and for readability. JSON does not allow line breaks within string
 
 ## Issuance
 
-The Issuer is using the following input JWT Claims Set:
+The following data about the user comprises the input JWT Claims Set used by the Issuer:
 
 <{{examples/simple/user_claims.json}}
 
-The Issuer in this case made the following decisions:
+In this example, the following decisions were made by the Issuer in constructing the SD-JWT:
 
 * The `nationalities` array is always visible, but its contents are selectively disclosable.
-* The `sub` element and essential verification data (`iss`, `iat`, `cnf`, etc.) are always visible.
+* The `sub` element as well as essential verification data (`iss`, `exp`, `cnf`, etc.) are always visible.
 * All other End-User claims are selectively disclosable.
-* For `address`, the Issuer is using a flat structure, i.e., all of the claims
+* For `address`, the Issuer is using a flat structure, i.e., all the claims
   in the `address` claim can only be disclosed in full. Other options are
   discussed in (#nested_data).
 
 The following payload is used for the SD-JWT:
 
 <{{examples/simple/sd_jwt_payload.json}}
 
-The following Disclosures are created by the Issuer:
+The respective Disclosures are created by the Issuer:
 
 {{examples/simple/disclosures.md}}
 
-The payload is then signed by the Issuer to create the following JWT:
+The payload is then signed by the Issuer to create the following Issuer-signed JWT:
 
 <{{examples/simple/sd_jwt_jws_part.txt}}
 
-The following is the issued SD-JWT:
+Adding the Disclosures produces the SD-JWT:
 
 <{{examples/simple/sd_jwt_issuance.txt}}
 
@@ -763,6 +763,10 @@ If the Verifier did not require Key Binding, then the Holder could have
 presented the SD-JWT with selected Disclosures directly, instead of encapsulating it in
 an SD-JWT+KB.
 
+After validation, the Verifier will have the following processed SD-JWT payload available for further handling:
+
+<{{examples/simple/verified_contents.json}}
+
 # Considerations on Nested Data in SD-JWTs {#nested_data}
 
 Being JSON, an object in an SD-JWT payload MAY contain name/value pairs where the value is another object or objects MAY be elements in arrays. In SD-JWT, the Issuer decides for each claim individually, on each level of the JSON, whether the claim should be selectively disclosable or not. This choice can be made on each level independent from whether keys higher in the hierarchy are selectively disclosable.
@@ -788,7 +792,7 @@ The Issuer can decide to treat the `address` claim as a block that can either be
 
 <{{examples/address_only_flat/sd_jwt_payload.json}}
 
-The Issuer would create the following Disclosure:
+The Issuer would create the following Disclosure referenced by the one hash in the SD-JWT:
 
 {{examples/address_only_flat/disclosures.md}}
 
@@ -1681,7 +1685,7 @@ Line breaks have been added for readability.
 
 In this example, in contrast to (#main-example), the Issuer decided to create a structured object for the `address` claim, allowing to separately disclose individual members of the claim.
 
-The Issuer is using the following input JWT Claims Set:
+The following data about the user comprises the input JWT Claims Set used by the Issuer:
 
 <{{examples/simple_structured/user_claims.json}}
 
@@ -1691,7 +1695,7 @@ The following payload is used for the SD-JWT:
 
 <{{examples/simple_structured/sd_jwt_payload.json}}
 
-The following Disclosures are created:
+The digests in the SD-JWT payload reference the following Disclosures:
 
 {{examples/simple_structured/disclosures.md}}
 
@@ -1704,28 +1708,32 @@ and `country` of the `address` property:
 
 <{{examples/simple_structured/sd_jwt_presentation.txt}}
 
+After validation, the Verifier will have the following processed SD-JWT payload available for further handling:
+
+<{{examples/simple_structured/verified_contents.json}}
+
 ## Complex Structured SD-JWT {#example-complex-structured-sd-jwt}
 
 In this example, an SD-JWT with a complex object is represented. The data
 structures defined in OpenID Connect for Identity Assurance [@OIDC.IDA] are used.
 
-The Issuer is using the following input JWT Claims Set:
+The Issuer is using the following user data as the input JWT Claims Set:
 
 <{{examples/complex_ekyc/user_claims.json}}
 
 The following payload is used for the SD-JWT:
 
 <{{examples/complex_ekyc/sd_jwt_payload.json}}
 
-The following Disclosures are created by the Issuer:
+The digests in the SD-JWT payload reference the following Disclosures:
 
 {{examples/complex_ekyc/disclosures.md}}
 
 The following is a presentation of the SD-JWT:
 
 <{{examples/complex_ekyc/sd_jwt_presentation.txt}}
 
-After the validation, the Verifier will have the following data for further processing:
+The Verifier will have this processed SD-JWT payload available after validation:
 
 <{{examples/complex_ekyc/verified_contents.json}}
 
@@ -1740,7 +1748,7 @@ a German citizen.
 Key Binding is applied
 using the Holder's public key passed in a `cnf` claim in the SD-JWT.
 
-The Issuer is using the following input JWT Claims Set:
+The following citizen data is the input JWT Claims Set:
 
 <{{examples/arf-pid/user_claims.json}}
 
@@ -1752,19 +1760,19 @@ The following payload is used for the SD-JWT:
 
 <{{examples/arf-pid/sd_jwt_payload.json}}
 
-The following Disclosures are created by the Issuer:
+The digests in the SD-JWT payload reference the following Disclosures:
 
 {{examples/arf-pid/disclosures.md}}
 
 The following is an example of an SD-JWT+KB that discloses only nationality and the fact that the person is over 18 years old:
 
 <{{examples/arf-pid/sd_jwt_presentation.txt}}
 
-The following is the payload of a corresponding Key Binding JWT:
+This is the payload of the corresponding Key Binding JWT:
 
 <{{examples/arf-pid/kb_jwt_payload.json}}
 
-After the validation, the Verifier will have the following data for further processing:
+After validation, the Verifier will have the following processed SD-JWT payload available for further handling:
 
 <{{examples/arf-pid/verified_contents.json}}
 
@@ -1776,7 +1784,7 @@ could be used to express a W3C Verifiable Credentials Data Model v2.0 [@VC_DATA_
 Key Binding is applied
 using the Holder's public key passed in a `cnf` claim in the SD-JWT.
 
-The Issuer is using the following input JWT Claims Set:
+The following is the input JWT Claims Set:
 
 <{{examples/jsonld/user_claims.json}}
 
@@ -1788,15 +1796,15 @@ The following payload is used for the SD-JWT:
 
 <{{examples/jsonld/sd_jwt_payload.json}}
 
-The following Disclosures are created by the Issuer:
+The digests in the SD-JWT payload reference the following Disclosures:
 
 {{examples/jsonld/disclosures.md}}
 
-The following is an example of an SD-JWT+KB that discloses only `type`, `medicinalProductName`, `atcCode` of the vaccine, `type` of the `recipient`, `type`, `order` and `dateOfVaccination`:
+This is an example of an SD-JWT+KB that discloses only `type`, `medicinalProductName`, `atcCode` of the vaccine, `type` of the `recipient`, `type`, `order` and `dateOfVaccination`:
 
 <{{examples/jsonld/sd_jwt_presentation.txt}}
 
-After the validation, the Verifier will have the following data for further processing:
+After the validation, the Verifier will have the following processed SD-JWT payload available for further handling:
 
 <{{examples/jsonld/verified_contents.json}}
 
@@ -1925,6 +1933,7 @@ data. The original JSON data is then used by the application. See
 
    -12
 
+   * Clarify, add context, or otherwise improve the examples
    * Editorial and reference fixes
    * Moved considerations around unlinkability to the top of the Privacy Considerations section