Verifiable Cred V1.1 Normative
Contents
Full Title or Meme
W3C Verifiable Credential Abstract.
Context
The Variable Cred Data Model Spec is hard to read. This is a collection of only the mandatory bits separated from the optional bits.
Problems
These are not necessarily defects in the VC data model as much as they are limitations in the model itself, which may be intentional.
- The VC data model is a definition of the structure (and use) of the credential and so term like Expiration Date applies not to the license or grant, but to the bucket of bits that is defined in the model.
- In general, the use of term license in the real world conflates the concept of a grant with the documentation of that grant. So, a Driver's License sometimes refers to the grant of a privilege to use the public road with the documentation of that grant with an ISO 18013 paper or digital document.
Mandatory Elements
The key words MAY, MUST, MUST NOT, RECOMMENDED, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
1.4 Conformance
A conforming document is any concrete expression of the data model that complies with the normative statements in this specification. Specifically, all relevant normative statements in Sections 4. Basic Concepts, 5. Advanced Concepts, and 6. Syntaxes of this document MUST be enforced. A serialization format for the conforming document MUST be deterministic, bi-directional, and lossless as described in Section 6. Syntaxes. The conforming document MAY be transmitted or stored in any such serialization format.
A conforming processor is any algorithm realized as software and/or hardware that generates or consumes a conforming document. Conforming processors MUST produce errors when non-conforming documents are consumed.
This specification makes no normative statements with regard to the conformance of roles in the ecosystem, such as issuers, holders, or verifiers, because the conformance of ecosystem roles are highly application, use case, and market vertical specific.
Digital proof mechanisms, a subset of which are digital signatures, are required to ensure the protection of a verifiable credential. Having and validating proofs, which may be dependent on the syntax of the proof (for example, using the JSON Web Signature of a JSON Web Token for proofing a key holder), are an essential part of processing a verifiable credential. At the time of publication, Working Group members had implemented verifiable credentials using at least three proof mechanisms:
- JSON Web Tokens [RFC7519] secured using JSON Web Signatures [RFC7515]
- Data Integrity Proofs [DATA-INTEGRITY]
- Camenisch-Lysyanskaya Zero-Knowledge Proofs [CL-SIGNATURES].
Implementers are advised to note that not all proof mechanisms are standardized as of the publication date of this specification. The group expects some of these mechanisms, as well as new ones, to mature independently and become standardized in time. Given there are multiple valid proof mechanisms, this specification does not standardize on any single digital signature mechanism. One of the goals of this specification is to provide a data model that can be protected by a variety of current and future digital proof mechanisms. Conformance to this specification does not depend on the details of a particular proof mechanism; it requires clearly identifying the mechanism a verifiable credential uses.
4.1 Contexts
When two software systems need to exchange data, they need to use terminology that both systems understand. As an analogy, consider how two people communicate. Both people must use the same language and the words they use must mean the same thing to each other. This might be referred to as the context of a conversation.
Verifiable credentials and verifiable presentations have many attributes and values that are identified by URIs [RFC3986]. However, those URIs can be long and not very human-friendly. In such cases, short-form human-friendly aliases can be more helpful. This specification uses the @context property to map such short-form aliases to the URIs required by specific verifiable credentials and verifiable presentations.
NOTE: In JSON-LD, the @context property can also be used to communicate other details, such as datatype information, language information, transformation rules, and so on, which are beyond the needs of this specification, but might be useful in the future or to related work. For more information, see Section 3.1: The Context of the [JSON-LD] specification.
Verifiable credentials and verifiable presentations MUST include a @context property.
@context
The value of the @context property MUST be an ordered set where the first item is a URI with the value https://www.w3.org/2018/credentials/v1. For reference, a copy of the base context is provided in Appendix B.1 Base Context. Subsequent items in the array MUST express context information and be composed of any combination of URIs or objects. It is RECOMMENDED that each URI in the @context be one which, if dereferenced, results in a document containing machine-readable information about the @context.
NOTE: Though this specification requires that a @context property be present, it is not required that the value of the @context property be processed using JSON-LD. This is to support processing using plain JSON libraries, such as those that might be used when the verifiable credential is encoded as a JWT. All libraries or processors MUST ensure that the order of the values in the @context property is what is expected for the specific application. Libraries or processors that support JSON-LD can process the @context property using full JSON-LD processing as expected.
The following paragraph appears to be in a normative section, but it is empirically false as it points to v1.1 and not v1.0 The data available at https://www.w3.org/2018/credentials/v1 is a static document that is never updated and SHOULD be downloaded and cached. The associated human-readable vocabulary document for the Verifiable Credentials Data Model is available at https://www.w3.org/2018/credentials/.
4.3 Types
Software systems that process the kinds of objects specified in this document use type information to determine whether or not a provided verifiable credential or verifiable presentation is appropriate. This specification defines a type property for the expression of type information. Verifiable credentials and verifiable presentations MUST have a type property. That is, any credential or presentation that does not have type property is not verifiable, so is neither a verifiable credential nor a verifiable presentation.
type The value of the type property MUST be, or map to (through interpretation of the @context property), one or more URIs. If more than one URI is provided, the URIs MUST be interpreted as an unordered set. Syntactic conveniences SHOULD be used to ease developer usage. Such conveniences might include JSON-LD terms. It is RECOMMENDED that each URI in the type be one which, if dereferenced, results in a document containing machine-readable information about the type.
All credentials, presentations, and encapsulated objects MUST specify, or be associated with, additional more narrow types (like UniversityDegreeCredential, for example) so software systems can process this additional information.
4.4 Credential Subject
A verifiable credential contains claims about one or more subjects. This specification defines a credentialSubject property for the expression of claims about one or more subjects. A verifiable credential MUST have a credentialSubject property.
credentialSubject The value of the credentialSubject property is defined as a set of objects that contain one or more properties that are each related to a subject of the verifiable credential. Each object MAY contain an id, as described in Section 4.2 Identifiers.
4.5 Issuer
This specification defines a property for expressing the issuer of a verifiable credential. A verifiable credential MUST have an issuer property.
issuer The value of the issuer property MUST be either a URI or an object containing an id property. It is RECOMMENDED that the URI in the issuer or its id be one which, if dereferenced, results in a document containing machine-readable information about the issuer that can be used to verify the information expressed in the credential.
4.6 Issuance Date
This specification defines the issuanceDate property for expressing the date and time when a credential becomes valid.
issuanceDate A credential MUST have an issuanceDate property. The value of the issuanceDate property MUST be a string value of an [XMLSCHEMA11-2] combined date-time string representing the date and time the credential becomes valid, which could be a date and time in the future.
4.7 Proofs (Signatures)
At least one proof mechanism, and the details necessary to evaluate that proof, MUST be expressed for a credential or presentation to be a verifiable credential or verifiable presentation; that is, to be verifiable. This specification identifies two classes of proof mechanisms:
- An external proof is one that wraps an expression of this data model, such as a JSON Web Token. Three signature methods are included in the base schema:
- EcdsaSecp256k1Signature2019
- EcdsaSecp256r1Signature2019 - this is the only one approved for use by Western governments.
- Ed25519Signature2018
- An embedded proof is a mechanism where the proof is included in the data, such as a Linked Data Signature, which is elaborated upon in Section 6.3.2 Data Integrity Proofs. When embedding a proof, the proof property MUST be used.
proof One or more cryptographic proofs that can be used to detect tampering and verify the authorship of a credential or presentation. The specific method used for an embedded proof MUST be included using the type property.
Optional Elements
4.2 Identifiers
Defines the normative use of ID, which is, itself, optional.
The value of the id property MUST be a single URI.
4.8 Expiration
This specification defines the expirationDate property for the expression of credential expiration information.
expirationDate If present, the value of the expirationDate property MUST be a string value of an [XMLSCHEMA11-2] date-time representing the date and time the credential ceases to be valid.
4.9 Status
This specification defines the following credentialStatus property for the discovery of information about the current status of a verifiable credential, such as whether it is suspended or revoked.
credentialStatus If present, the value of the credentialStatus property MUST include the following: id property, which MUST be a URI. type property, which expresses the credential status type (also referred to as the credential status method). It is expected that the value will provide enough information to determine the current status of the credential and that machine readable information needs to be retrievable from the URI. For example, the object could contain a link to an external document noting whether or not the credential is suspended or revoked.
4.10 Presentations
Presentations MAY be used to combine and present credentials. They can be packaged in such a way that the authorship of the data is verifiable. The data in a presentation is often all about the same subject, but there is no limit to the number of subjects or issuers in the data. The aggregation of information from multiple verifiable credentials is a typical use of verifiable presentations.
A verifiable presentation is typically composed of the following properties:
id The id property is optional and MAY be used to provide a unique identifier for the presentation. For details related to the use of this property, see Section 4.2 Identifiers. type The type property is required and expresses the type of presentation, such as VerifiablePresentation. For details related to the use of this property, see Section 4.3 Types. verifiableCredential If present, the value of the verifiableCredential property MUST be constructed from one or more verifiable credentials, or of data derived from verifiable credentials in a cryptographically verifiable format.
holder
If present, the value of the holder property is expected to be a URI for the entity that is generating the presentation.
proof
If present, the value of the proof property ensures that the presentation is verifiable. For details related to the use of this property, see Section 4.7 Proofs (Signatures).
5.4 Data Schemas
Data schemas are useful when enforcing a specific structure on a given collection of data. There are at least two types of data schemas that this specification considers:
Data verification schemas, which are used to verify that the structure and contents of a credential or verifiable credential conform to a published schema. Data encoding schemas, which are used to map the contents of a verifiable credential to an alternative representation format, such as a binary format used in a zero-knowledge proof. It is important to understand that data schemas serve a different purpose from the @context property, which neither enforces data structure or data syntax, nor enables the definition of arbitrary encodings to alternate representation formats.
This specification defines the following property for the expression of a data schema, which can be included by an issuer in the verifiable credentials that it issues:
credentialSchema The value of the credentialSchema property MUST be one or more data schemas that provide verifiers with enough information to determine if the provided data conforms to the provided schema. Each credentialSchema MUST specify its type (for example, JsonSchemaValidator2018), and an id property that MUST be a URI identifying the schema file. The precise contents of each data schema is determined by the specific type definition.
5.5 Refreshing
It is useful for systems to enable the manual or automatic refresh of an expired verifiable credential. For more information about expired verifiable credentials, see Section 4.8 Expiration. This specification defines a refreshService property, which enables an issuer to include a link to a refresh service.
The issuer can include the refresh service as an element inside the verifiable credential if it is intended for either the verifier or the holder (or both), or inside the verifiable presentation if it is intended for the holder only. In the latter case, this enables the holder to refresh the verifiable credential before creating a verifiable presentation to share with a verifier. In the former case, including the refresh service inside the verifiable credential enables either the holder or the verifier to perform future updates of the credential.
The refresh service is only expected to be used when either the credential has expired or the issuer does not publish credential status information. Issuers are advised not to put the refreshService property in a verifiable credential that does not contain public information or whose refresh service is not protected in some way.
NOTE Placing a refreshService property in a verifiable credential so that it is available to verifiers can remove control and consent from the holder and allow the verifiable credential to be issued directly to the verifier, thereby bypassing the holder.
refreshService The value of the refreshService property MUST be one or more refresh services that provides enough information to the recipient's software such that the recipient can refresh the verifiable credential. Each refreshService value MUST specify its type (for example, ManualRefreshService2018) and its id, which is the URI of the service. There is an expectation that machine readable information needs to be retrievable from the URI. The precise content of each refresh service is determined by the specific refreshService type definition.
