Instead, credential data model authors are expected to use machine-readable
vocabularies through the use of [LINKED-DATA]. This implementation guide
provides examples for how to express data models using a data format that
is popular with software developers and web page authors called [JSON-LD]. This
data format provides features that enable authors to express their data models
in idiomatic JSON while also ensuring that their vocabulary terms are
unambigiously understood, even by software that does not implement
JSON-LD processing.
The Verifiable Credentials data model also uses a graph-based data model,
which allows authors to model both simple relationships that describe
one or more attributes for a single entity and complex multi-entity
relationships.
The rest of this section describes how to author extensions that build on
the Verifiable Credentials Data Model.
7.1 Creating New Credential Types
We expect the most common extensions to the Verifiable Credentials Data Model
to be new credential types. Whenever someone has something to say about one or
more entities and they want their authorship to be verifiable, they should use
a Verifiable Credential. Sometimes there may be an existing credential type,
that someone else has created, that can be reused to make the statements they
want to make. However, there are often cases where new credential types are
needed.
New credential types can be created by following a few steps. This guide will
also walk you through creating an example new credential type. At a high level,
the steps to follow are:
-
Design the data model.
-
Create a new JSON-LD context.
-
Select a publishing location.
-
Use the new JSON-LD context when issuing new credentials.
So, let's walk through creating a new credential type which we will
call ExampleAddressCredential. The purpose of this credential
will be to express a person's postal address.
Design the data model
First, we must design a data model for our new credential type. We know that
we will need to be able to express the basics of a postal address, things
like a person's city, state, and zipcode. Of course, those items are quite
US centric, so we should consider internationalizing those terms. But before
we go further, since we're using [LINKED-DATA] vocabularies, there is a good
chance that commonly known concepts may already have a vocabulary that someone
else has created that we can leverage.
If we are going to use someone else's vocabulary, we will want to make sure it
is stable and unlikely to change in any significant way. There may even be
technologies that we can make use of that store immutable vocabularies that
we can reference, but those are not the focus of this example. Here we will
rely on the inertia that comes from a very popularly used vocabulary on the
Web, schema.org. It turns out that this vocabulary has just what we need; it
has already modeled a postal address and even has examples for how to express
it using JSON-LD.
Using the schema.org vocabulary and JSON-LD we can express a person's address
like so:
{
"@context": [
"http://schema.org"
],
"type": "Person",
"address": {
"type": "PostalAddress",
"streetAddress": "123 Main St."
"addressLocality": "Blacksburg",
"addressRegion": "VA",
"postalCode": "24060",
"addressCountry": "US"
}
}
Note the above @context key in the JSON. This @context
refers to a machine-readable file (also expressed in JSON) that provides
term definitions [JSON-LD]. A term definition maps a key or type used in the
JSON, such as address or PostalAddress, to a globally
unique identifier: a URL.
This ensures that when software sees the @context
http://schema.org, that it will interpret the the keys and types in the
JSON in a globally consistent way, without requiring developers to use full URLs
in the JSON or in the code that may traverse it. As long as the software is
aware of the specific @context used (or if it uses JSON-LD
processing to transform it to some other known @context), then it
will understand the context in which the JSON was written and meant to
be understood. The use of @context also allows [JSON-LD] keywords
such as @type to be aliased to the simpler type as
is done in the above example.
Note that we could also express the JSON using full URLs, if we want to avoid
using @context. Here is what the example would look like if we did
that:
Example 5: Example schema.org address with full URLs
{
"@type": "http://schema.org/Person",
"http://schema.org/address": {
"@type": "http://schema.org/PostalAddress",
"http://schema.org/streetAddress": "123 Main St."
"http://schema.org/addressLocality": "Blacksburg",
"http://schema.org/addressRegion": "VA",
"http://schema.org/postalCode": "24060",
"http://schema.org/addressCountry": "US"
}
}
While this form is an acceptable way to express the information such that it is
unambiguous, many software developers would prefer to use more idiomatic JSON.
The use of @context enables idiomatic JSON without losing global
consistency and without the need for a centralized registry or authority for
creating extensions. Note that @context can also have more than
one value. In this case, a JSON array is used to express multiple values, where
each value references another context that defines terms. Using this mechanism
we can first bring in the terms defined in the Verifiable Credentials Data Model
specification and then bring in the terms defined by schema.org:
Example 6: Example address credential with schema.org context
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"http://schema.org"
],
...
"credentialSubject": {
"type": "Person",
"address": {
"type": "PostalAddress",
"streetAddress": "123 Main St."
"addressLocality": "Blacksburg",
"addressRegion": "VA",
"postalCode": "24060",
"addressCountry": "US"
}
},
...
}
Note, however, that each context might have a different definition for
the same term, e.g., the JSON key address might map to a different
URL in each context. By default, [JSON-LD] allows terms in a
@context to be redefined using a last term wins
order. While these changes can be safely dealt with by using JSON-LD
processing, we want to lower the burden on consumers of Verifiable Credentials.
We want consumer software to be able to make assumptions about the meaning of
terms by only having to read and understand the string value associated with
the @context key. We don't want them to have to worry about terms
being redefined in unexpected ways. That way their software can inspect only
the @context values and then be hard coded to understand the
meaning of the terms.
In order to prevent term redefinition, the [JSON-LD] @protected
feature must be applied to term definitions in the @context. All
terms in the core Verifiable Credentials @context are
already protected in this way. The only time that an existing term is allowed
to be redefined is if the new definition is scoped underneath another new term
that is defined in a context. This matches developer expectations and
ensures that consumer software has strong guarantees about the semantics of the
data it is processing; it can be written such that it is never confused about
the definition of a term. Note that consumers must determine their own risk
profile for how to handle any credentials their software processes that include
terms that it does not understand.
Create a new JSON-LD context
Given the above, there is at least one reason why we don't want to use
the schema.org context: it is designed to be very flexible and thus
does not use the @protected feature. There are a few additional
reasons we want to create our own [JSON-LD] context though. First, the
schema.org context does not define our new credential type:
ExampleAddressCredential. Second, it is not served via a secure
protocol (e.g., https); rather, it uses http. Note that this
is less of a concern than it may seem, as it is recommended that all Verifiable
Credential consumer software hard code the @context values it
understands and not reach out to the Web to fetch them. Lastly, it is a very
large context, containing many more term definitions than are necessary for our
purposes.
So, we will create our own [JSON-LD] context that expresses just those term
definitions that we need for our new credential type. Note that this does not
mean that we must mint new URLs; we can still reuse the schema.org vocabulary
terms. All we are doing is creating a more concise and targeted context. Here's
what we'll need in our context:
Example 7: Example address credential context
{
"@version": 1.1,
"@protected": true,
"ExampleAddressCredential":
"https://example.org/ExampleAddressCredential",
"Person": {
"@id": "http://schema.org/Person",
"@context": {
"@version": 1.1,
"@protected": true,
"address": "http://schema.org/address"
}
},
"PostalAddress": {
"@id": "http://schema.org/PostalAddress",
"@context": {
"@version": 1.1,
"@protected": true,
"streetAddress": "http://schema.org/streetAddress",
"addressLocality": "http://schema.org/addressLocality",
"addressRegion": "http://schema.org/addressRegion",
"postalCode": "http://schema.org/postalCode",
"addressCountry": "http://schema.org/addressCountry"
}
}
}
The above context defines a term for our new credential type
ExampleAddressCredential, mapping it to the URL
https://example.org/ExampleAddressCredential. We could have also
chosen a URI like urn:private-example:ExampleAddressCredential, but
this approach would not allow us to serve up a Web page to describe it, if we
so desire. The context also defines the terms for types Person and
PostalAddress, mapping them to their schema.org vocabulary URLs.
Furthermore, when those types are used, it also defines protected terms for
each of them via a scoped context, mapping terms like address
and streetAddress to their schema.org vocabulary URLs. For more
information on how to write a JSON-LD context or scoped contexts, see
the [JSON-LD] specification.
Select a publishing location
Now that we have a [JSON-LD] context, we must give it a URL. Technically
speaking, we could just use a URI, for example, a private URN such as
urn:private-example:my-extension. However, if we want people to be
able to read and discover it on the Web, we should give it a URL like
https://example.org/example-address-credential-context/v1.
When this URL is dereferenced, it should return
application/ld+json by default, to allow JSON-LD processors to process
the context. However, if a user agent requests HTML, it should return
human readable text that explains, to humans, what the term definitions are and
what they map to. Since we're reusing an existing vocabulary, schema.org, we
can also simply link to the definitions of the meaning of our types and terms
via their website. If we had created our own new vocabulary terms, we would
describe them on our own site, ideally including machine readable Information
as well.
Use the new JSON-LD context when issuing new credentials
Now we're ready for our context to be used by anyone who
wishes to issue an ExampleAddressCredential!
Example 8: Example address credential with schema.org context
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://example.org/example-address-credential-context/v1"
],
"id": "https://example.org/credentials/1234",
"type": "ExampleAddressCredential",
"issuer": "https://example.org/people#me",
"issuanceDate": "2017-12-05T14:27:42Z",
"credentialSubject": {
"id": "did:example:1234",
"type": "Person",
"address": {
"type": "PostalAddress",
"streetAddress": "123 Main St."
"addressLocality": "Blacksburg",
"addressRegion": "VA",
"postalCode": "24060",
"addressCountry": "US"
}
},
"proof": { ... }
}
Note that writing this new credential type requires permission from no one,
you must only adhere to the above referenced standards.