JSON, a Simple and Easy Start for Verifiable Credential Issuance
JSON is really really simple. It is just name value pairs. There is a tiny IANA registry for JWT claims that defines about 100 JSON terms. This is the one registry of JSON terms that folks who love JSON reference repeatedly and say solves any needed disambiguation problems. However, beyond these approximately 100 terms, there is nowhere really to look up and figure out what a particular name asserted in JSON actually means.
Having small known vocabularies works out fine for contained ecosystems where all the entities have a shared understanding of vocabulary they agree on. This small known vocabulary all actors agree on is known as “closed world” scenario because it assumes a boundary of knowing that is obvious to those involved who care and un-obvious to those outside the world but they don’t care anyway so who cares about them.
If one is a receiver of a JSON VC with only name-value pairs and it contains values outside of that tiny IANA registry – then…what does one do if one isn’t “inside” whatever “world” the issuer assumed. One either has to go and contact the issuer to ask them OR potentially hire a big tech firm to help one do the discernment because that big tech firm has done the work to accumulate knowledge from all these closed worlds and are selling that discernment capability as a service.
On the other hand JSON is very easily understood by developers. There is a lot of existing tooling that just works. Serialization isn’t required. It’s easy. It is human readable.
So let’s look at some JSON. What is it?
JSON (JavaScript Object Notation) is a widely used open standard object and document format used for data interchange and is human readable. It consists of attribute-value pairs. It is a generic data model.
Here is an example of JSON (from the JSON Wikipedia page)
There are several different data types and structures supported in JSON. From the example above:
- Number
- Age 27
- String: a sequence of zero or more Unicode characters.
- firstName – “John”
- Boolean: either of the values true or false
- Is alive = true
- null: an empty value, represented by the string null
- No spouse
- Array: an ordered list of zero or more values, each of which may be of any type.
- phoneNumbers – represents an array
- There is more than one phone number listed, so it is represented as an array
- children – represents an empty array
- Object: a collection of name-value pairs where the names (also called keys) are strings. Objects are intended to represent associative arrays, where each key is unique within an object. Objects are delimited with curly brackets and use commas to separate each name-value pair, while within each pair the colon ‘:’ character separates the key or name from its value.
- Address – an object consisting of four different name-value pairs.
JSON alone doesn’t have very much meaning and is not machine readable. This format is needed as a kind of “on ramp” to the VC ecosystem because of the above qualities. It’s a good starting point for developers, people – and organizations to begin to issue VCs. However if JSON is the only way to express claims within VCs – more complex cool interesting things that are possible with JSON-LD are closed off. The next part of this article will look at the key capabilities and features of JSON-LD.
JSON-LD for Semantic Clarity and Interoperability
JSON-LD is newer – it takes JSON and adds one more piece to it – a way to refer to contexts and vocabularies that have meaning.
JSON-LD can be read with JSON tooling – it just leaves out all the extra LD stuff.
One of the main goals of JSON-LD was to make it very easy for developers to interpret JSON objects according to immutable and open data registries rather than local schemata, which can be separated from the data they are essential to interpreting. It was created for web developers working with data that must interoperate semantically across the Web.
What distinguishes JSON-LD is that it supports an additional layer of context to map the name part of the name-value pair to an RDF ontology, a knowledge graph that structures metadata in shared vocabularies so that when machines read it they can understand more about what it means.
Here is JSON-LD being used to describe the movie Avatar.
At the top in the @context field it references the place where one can look up more about what the terms below mean so in the schema.org context there is a type called “Movie” and they can then look up what are all the different terms for this type.
JSON-LD allows credential issuers to define a type of credential they are issuing and then use the @context field for navigating a tree of schemata that explain the structure and content of a credential. The @context field is an address (URL) which also helps place the credential in its original context. This helps the verifier confirm the meaning of all the “attributes” of the “attributes-value pairs” that are listed on the credential.
JSON-LD supports disambiguation between properties found in different credentials issued by different issuers and so verifiers understand what they are looking at.
One of the features that is valuable for a multilingual world is the ability to map property values to another language via a language map. So, when a credential is published in one language, English, and is presented to a verifier who is familiar with another language, Thai, the program can go look up the values of the claims in the document and have them accurately translated so they can be read by the verifier.
This means that definitions can be expressed in different languages and translated. In addition to all the features JSON provides, JSON-LD introduces:
- a universal identifier mechanism for JSON objects via the use of IRIs,
- a way to disambiguate keys shared among different JSON documents by mapping them to IRIs via a context,
- a mechanism in which a value in a JSON object may refer to a resource on a different site on the Web giving the ability to annotate strings with their language,
- a way to associate data types with values such as dates and times,
- and a facility to express one or more directed graphs, such as a social network, in a single document.
One of the industries that is really dependent on JSON-LD for credentialing is higher education. The Credential Transparency Description Language (CTDL) work by Credential Engine that I am one of the advisors for is working to develop semantic mapping and meaning for over 1 million different credentials issued by 50,000 higher educational institutions in the United States. Different but similar work is happening in Europe to map and make sense of credentials issued by various institutions.
(Some parts of the post are excerpted and adapted from the Verifiable Credential Flavors Explained paper that I wrote a few years ago. My colleague Lucy and I are working on an update of this paper coming up in the fall.)