Add schema type metadata

draft-ietf-oauth-sd-jwt-vc.md

@@ -130,6 +130,9 @@ document are to be interpreted as described in RFC 2119 [@!RFC2119].
 This specification uses the terms "Holder", "Issuer", "Verifier", "Key Binding", and "Key Binding JWT" defined by
 [@!I-D.ietf-oauth-selective-disclosure-jwt].
 
+Consumer:
+: Applications using this specification are called Consumer. This typically includes Issuers, Verifiers, and Wallets.
+
 Verifiable Credential (VC):
 :  An assertion with claims about a Subject that is cryptographically secured by an Issuer (usually by a digital signature).
 
@@ -478,30 +481,26 @@ MUST NOT be used.
 
 # Type Metadata {#type-metadata}
 
-A type is associated with metadata defining, for example, information about the type, a schema defining which claims MAY or MUST appear in the SD-JWT VC, and how they can be displayed.
+A SD-JWT VC type, i.e., the `vct` value, is associated with Type Metadata defining, for example, information about the type or a schema defining which claims MAY or MUST appear in the SD-JWT VC.
 
-This section defines Type Metadata that can be associated with a type of a SD-JWT VC as well as a method for retrieving the Type Metadata and processing rules. This Type Metadata is intended to be used, among other things, for the following purposes:
+This section defines Type Metadata that can be associated with a type of a SD-JWT VC, as well as a method for retrieving the Type Metadata and processing rules. This Type Metadata is intended to be used, among other things, for the following purposes:
 
- * Developers of Issuers and Verifiers can use the Typ Metadata to understand the
+ * Developers of Issuers and Verifiers can use the Type Metadata to understand the
    semantics of the type and the associated rules. While in some cases,
-   Issuers are the parties that define types (credential formats), this is
+   Issuers are the parties that define types, this is
    not always the case. For example, a type can be defined by a
    standardization body or a community.
- * Verifiers can use the metadata to determine whether a credential is valid
+ * Verifiers can use the Type Metadata to determine whether a credential is valid
    according to the rules of the type. For example, a Verifier can check
    whether a credential contains all required claims and whether the claims
    are selectively disclosable.
- * Wallets can use the metadata to display the credential in a way that is
-   consistent with the Issuer's intent.
 
-Applications using Type Metadata defined in this specification are called "Consumers" in the following. This typically includes Issuers, Verifiers, and Wallets.
+Type Metadata can be retrieved as described in (#retrieving-type-metadata).
 
 ## Type Metadata Example {#type-metadata-example}
 
 All examples in this section are non-normative.
 
-Type Metadata about the value of a `vct` claim value can be retrieved as described in (#retrieving-type-metadata).
-
 ```json
 {
   "vct": "https://betelgeuse.example.com/education_credential",
@@ -522,7 +521,9 @@ The following is an example for a Type Metadata document:
   "name":"Betelgeuse Education Credential - Preliminary Version",
   "description":"This is our development version of the education credential. Don't panic.",
   "extends":"https://galaxy.example.com/galactic-education-credential-0.9",
-  "extends#integrity":"sha256-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-WRL5"
+  "extends#integrity":"sha256-9cLlJNXN-TsMk-PmKjZ5t0WRL5ca_xGgX3c1VLmXfh-WRL5",
+  "schema_uri":"https://exampleuniversity.com/public/credential-schema-0.9",
+  "schema_uri#integrity":"sha256-o984vn819a48ui1llkwPmKjZ5t0WRL5ca_xGgX3c1VLmXfh"
 }
 ```
 
@@ -540,17 +541,14 @@ defined:
 * `extends`
   * OPTIONAL. A URI of another type that this type extends, as described in
   (#extending-type-metadata).
-
-## Extending Type Metadata {#extending-type-metadata}
-
-A type can extend another type. The extended type is identified by the URI in
-the `extends` property. Consumers MUST retrieve and process
-Type Metadata for the extended type before processing the Type Metadata for the extending
-type.
-
-The extended type MAY itself extend another type. This can be used to create a
-chain or hierarchy of types. The security considerations described in
-(#circular-extends) apply in order to avoid problems with circular dependencies.
+* `schema`
+  * OPTIONAL. An embedded JSON Schema document describing the structure of
+  the Verifiable Credential as described in (#schema-type-metadata). `schema` MUST NOT be used
+  if `schema_uri` is present.
+* `schema_uri`
+  * OPTIONAL. A URL pointing to a JSON Schema document describing the structure
+  of the Verifiable Credential as described in (#schema-type-metadata). `schema_uri` MUST NOT
+  be used if `schema` is present.
 
 ## Retrieving Type Metadata {#retrieving-type-metadata}
 
@@ -569,7 +567,7 @@ If the claim `vct#integrity` is present in the SD-JWT VC, its value
 
 ### From a Registry {#retrieval-from-registry}
 
-A Consumer MAY use a registry to retrieve Type Metadata for a type,
+A Consumer MAY use a registry to retrieve Type Metadata for a SD-JWT VC type,
 e.g., if the type is not a HTTPS URL or if the Consumer does not have
 access to the URL. The registry MUST be a trusted registry, i.e., the Consumer MUST trust the registry to provide correct Type Metadata for the type.
 
@@ -584,15 +582,15 @@ retrieve Type Metadata based on a URN in the `vct` claim.
 
 ### From a Local Cache {#retrieval-from-local-cache}
 
-A Consumer MAY cache Type metadata for a type. If a hash for integrity
+A Consumer MAY cache Type Metadata for a SD-JWT VC type. If a hash for integrity
 protection is present in the Type Metadata as defined in (#document-integrity), the Consumer MAY assume that the Type Metadata is static and can be cached
 indefinitely. Otherwise, the Consumer MUST use the `Cache-Control`
 header of the HTTP response to determine how long the metadata can be cached.
 
 ### From Type Metadata Glue Documents {#glue-documents}
 
 Credentials MAY encode Type Metadata directly, providing it as "glue
-information" to the consumer.
+information" to the Consumer.
 
 For JSON-serialized JWS-based credentials, such Type Metadata documents MAY be
 included in the unprotected header of the JWS. In this case, the key `vctm` MUST
@@ -612,13 +610,36 @@ array instead of retrieving the respective Type Metadata elsewhere as follows:
    Type Metadata document matches that of the `vct` in the Type Metadata document, and it MUST verify the integrity of the Type Metadata document as defined in
    (#document-integrity). The Consumer MUST NOT use the Type Metadata if no hash for integrity protection was provided.
 
+## Extending Type Metadata {#extending-type-metadata}
+
+A SD-JWT VC type can extend another type. The extended type is identified by the URI in
+the `extends` property. Consumers MUST retrieve and process
+Type Metadata for the extended type before processing the Type Metadata for the extending
+type.
+
+The extended type MAY itself extend another type. This can be used to create a
+chain or hierarchy of types. The security considerations described in
+(#circular-extends) apply in order to avoid problems with circular dependencies.
+
+The `schema` or `schema_uri` property of the extending type MUST be evaluated for validation purposes if it exists.
+Afterwards, or if there is no such property, the `schema` or `schema_uri` property of the extended type MUST evaluated.
+This means that all schemas in the chain of extended types MUST be evaluated for a particular Verifiable Credential.
+
+## Schema Type Metadata {#schema-type-metadata}
+
+If a `schema` or `schema_uri` property is present, a Consumer that intends to validate the Verifiable Credential
+(in particular, Verifiers) MUST validate the Verifiable Credential against the provided JSON Schema document.
+
+TBD: provide details about the base JSON document the JSON Schema document MUST be validated against.
+
+TBD: Full JSON Schema example
 # Document Integrity {#document-integrity}
 
-Both the `vct` claim in the SD-JWT VC and various URIs in the metadata
-document MAY be accompanied by a respective claim suffixed with `#integrity`, in particular:
+Both the `vct` claim in the SD-JWT VC and various URIs in the Type Metadata MAY be accompanied by a respective claim suffixed with `#integrity`, in particular:
 
  * `vct` as defined in (#claims),
  * `extends` as defined in (#extending-type-metadata)
+ * `schema_uri` as defined in (#schema-type-metadata)
 
 The value MUST be an "integrity metadata" string as defined in Section 3 of
 [@!W3C.SRI]. A Consumer of the respective documents MUST verify the
@@ -1007,6 +1028,7 @@ for their contributions (some of which substantial) to this draft and to the ini
 * Include Type Metadata
 * Editorial changes
 * Updated terminology to clarify digital signatures are one way to secure VCs and presentations
+* Include schema Type Metadata
 
 -03