By name: "w3c-vcdm-getting-started" description: "Use when getting started with the W3C VCDM core model. Covers: getting started, verifiable credentials, and contexts." sections: - "4.1 Getting StartedThis section is non-normative." - "4.2 Verifiable Credentials" - "4.3 Contexts"
4.1 Getting StartedThis section is non-normative.
This specification is designed to ease the prototyping of new types of verifiable credentials. Developers can copy the template below and paste it into common verifiable credential tooling to start issuing, holding, and verifying prototype credentials.
A developer will change MyPrototypeCredential below to the type of credential
they would like to create. Since verifiable credentials talk about subjects,
each property-value pair in the credentialSubject object expresses a
particular property of the credential subject. Once a developer has added a
number of these property-value combinations, the modified object can be sent to
a conforming issuer implementation, and a verifiable credential will be
created for the developer. From a prototyping standpoint, that is all a
developer needs to do.
[Example 1](https://www.w3.org/TR/vc-data-model-2.0/#example-a-template-for-creating-prototype-verifiable-credentials): A template for creating prototype verifiable credentials
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"type": ["VerifiableCredential", "MyPrototypeCredential"],
"credentialSubject": {
"mySubjectProperty": "mySubjectValue"
}
}
After stabilizing all credential properties, developers are advised to generate
and publish vocabulary and context files at stable URLs to facilitate
interoperability with other developers. The
https://www.w3.org/ns/credentials/examples/v2 URL above
would then be replaced with the URL of a use-case-specific context. This
process is covered in Section 5.2 Extensibility. Alternatively,
developers can reuse existing vocabulary and context files that happen to fit
their use case. They can explore the Verifiable Credential Extensions
for reusable resources.
4.2 Verifiable Credentials
Verifiable credentials are used to express properties of one or more subjects as well as properties of the credential itself. The following properties are defined in this specification for a verifiable credential:
@context
Defined in Section 4.3 Contexts.
id
Defined in Section 4.4 Identifiers.
type
Defined in Section 4.5 Types.
name
Defined in Section 4.6 Names and Descriptions.
description
Defined in Section 4.6 Names and Descriptions.
issuer
Defined in Section 4.7 Issuer.
credentialSubject
Defined in Section 4.8 Credential Subject.
validFrom
Defined in Section 4.9 Validity Period.
validUntil
Defined in Section 4.9 Validity Period.
status
Defined in Section 4.10 Status.
credentialSchema
Defined in Section 4.11 Data Schemas.
refreshService
Defined in Section 5.4 Refreshing.
termsOfUse
Defined in Section 5.5 Terms of Use.
evidence
Defined in Section 5.6 Evidence.
A verifiable credential can be extended to have additional properties through the extension mechanism defined in Section 5.2 Extensibility.
4.3 Contexts
When two software systems need to exchange data, they need to use terminology that both systems understand. Consider how two people communicate effectively by using the same language, where the words they use, such as "name" and "website," mean the same thing to each individual. This is sometimes referred to as the context of a conversation. This specification uses a similar concept to achieve similar results for software systems by establishing a context in which to communicate.
Software systems that process verifiable credentials and verifiable presentations identify terminology by using URLs for each term. However,
those URLs can be long and not very human-friendly, while short-form,
human-friendly aliases can be more helpful. This specification uses the
@context property to map short-form aliases to the URLs.
Verifiable credentials and verifiable presentations MUST include a
@context property. Application developers MUST understand every JSON-LD
context used by their application, at least to the extent that it affects the
meaning of the terms used by their application. One mechanism for
doing so is described in the Section on
Validating Contexts in
the Verifiable Credential Data Integrity 1.0 specification. Other specifications that build
upon this specification MAY require that JSON-LD contexts be integrity protected
by using the relatedResource feature described in Section
5.3 Integrity of Related Resources or any effectively equivalent mechanism.
@context
The value of the @context property MUST be an ordered set
where the first item is a URL with the value
https://www.w3.org/ns/credentials/v2.
Subsequent items in the ordered set MUST be composed of any combination of
URLs and objects, where each is processable as a
JSON-LD Context.
[Example 2](https://www.w3.org/TR/vc-data-model-2.0/#example-use-of-the-context-property): Use of the @context property
{
"@context": [
"https://www.w3.org/ns/credentials/v2",
"https://www.w3.org/ns/credentials/examples/v2"
],
"id": "http://university.example/credentials/58473",
"type": ["VerifiableCredential", "ExampleAlumniCredential"],
"issuer": "did:example:2g55q912ec3476eba2l9812ecbfe",
"validFrom": "2010-01-01T00:00:00Z",
"credentialSubject": {
"id": "did:example:ebfeb1f712ebc6f1c276e12ec21",
"alumniOf": {
"id": "did:example:c276e12ec21ebfeb1f712ebc6f1",
"name": "Example University"
}
}
}
The example above uses the base context URL
(https://www.w3.org/ns/credentials/v2) to establish that the data exchange is
about a verifiable credential. This concept is further detailed in
Section 5.2 Extensibility. The data available at
https://www.w3.org/ns/credentials/v2 is a permanently cacheable static
document with instructions for processing it provided in Appendix
B.1 Base Context. The associated human-readable vocabulary document for the
Verifiable Credentials Data Model is available at
https://www.w3.org/2018/credentials/.
The second URL (https://www.w3.org/ns/credentials/examples/v2) is used to
demonstrate examples. Implementations are expected to not use
this URL for any other purpose, such as in pilot or production systems.
Note: See JSON-LD for more information about @context.
The @context property is further elaborated upon in
Section 3.1: The Context
of the JSON-LD 1.1 specification.