Re: Understanding @contexts and credentialSchemas

a context describes semantics, a schema describes data shape... There is a
right tool for each job, but sometimes you need both.

`@context` can only help you define JSON-LD semantics.

`credentialSchema` is much more flexible and can help you define JSON
Schema, SHACL, CustomProprietarySchema, or any other schema technology you
want to use.

I would not recommend using `@context` for schemas related to data shape or
`credentialSchema` for semantics... but JSON-LD is a lot of rope and it
does let you define some data-shape like behaviors.... My experience with
it is that there is always a better solution than using JSON-LD "data
shape" features like @container...

A concrete example, "@type": "@json" <- this is JSON-LD for the JSON
Schema  "type": "oneOf <number, null, object, string, array, etc...>

This can be very useful when your JSON data has no well defined semantics,
or where its semantics are rapidly changing, or externally owned...

For example:

"@context": [ "", { "@vocab": "", "fhirBundle": { "@id": "", "@type": "@json" } } ]

In this case, all we know about "fhirBundle" is that it's JSON... this
documentation is incomplete... because what version of FHIR is it?

fhirVersion needs to be defined, and used to answer that, but together they
can allow you to "define only the semantics you need"... in this case, FHIR.

It's worth noting that there are lots of valid FHIR I could put in
"fhirBundle" that could cause explosions... that's where a schema language
like JSON Schema would be valuable.

Working together, they could help both producers and consumers agree to be
as specific as is helpful for the VC type, and not "overly pedantic /
specific" in ways that are beyond the point of diminishing returns.

One version of being as specific as is necessary is to say: "this payload
is json"... I personally think that is harmful laziness, but you could also
see it as a reflection of a lack of certainty regarding what is actually
getting signed... and a need to allow anything... regardless of what it
is... to be signed.

When answering the question of "what am I signing or verifying" JSON-LD and
JSON Schema (for example) give you different additional confidence...
Omitting both is the equivalent of saying you are either highly unconfident
in the content you are or will be signing in the future, or you feel that
the security benefits of typing and input validation are not relevant to
your credential... I would call credentials that lack semantic
disambiguation and schema / data shape fundamentally LESS SECURE.


Of the top 10, the following are mitigated with stricter semantics and data
shape constraints:

- Injection
- Sensitive Data Exposure
- Insecure Deserialization

A credential that lacks semantics and datashape is like a food product with
no labeling or a mobile phone built with parts that might have been
developed with poor labor practices... the point is that you don't really
know, because the issuer chose not to meet those bars, when they decided to


On Thu, Jun 10, 2021 at 2:28 PM Kerri Lemoie <>

> This is helpful, Orie.
> While VC has this credentialSchema property, I assume it would still be
> acceptable for a context to reference schema(s) directly?
> Thanks!
> K
> On Jun 10, 2021, at 10:09 AM, Orie Steele <>
> wrote:
> This won't be a complete answer, but at the time of publication I
> believe that field was used in 2 ways.
> 1. with json schema, see this for example -
> 2. with hyperledger indy zkp-cl signature vc's
> In both cases, "credentialSchemas" was more about the VC data shape and
> type, whereas contexts and JSON-LD are best used only for semantics.
> There are other tools like SHACL that can help do linked data shape
> constraints, perhaps someone might use them with credentialSchemas in the
> future.
> but AFAIK, "credentialSchemas" is focused on the credential data shape.
> and "@context" is focused on the semantics and term definitions used in the
> credential.
> OS
> On Wed, Jun 9, 2021 at 5:15 PM Kerri Lemoie <>
> wrote:
>> Hello all,
>> I’m reviewing this:
>> Could folks please explain to me the uses of credentialSchemas in
>> comparison to @context files in JSON-LD? Is it that @context files name the
>> attributes and credentialSchemas provide the information about how to
>> validate the data/semantics?
>> Can you provide some real-world examples? Bonus points for human centered
>> examples such as identity,  education, &  workforce. :)
>> Thanks!
>> Kerri
>> --------
>> Kerri Lemoie, PhD
>> Director, Digital Credentials Research & Innovation
>> <> |
>> she/her/hers
> --
> Chief Technical Officer
> <>

Chief Technical Officer


Received on Friday, 11 June 2021 13:45:16 UTC