Skip to content

Aries RFC 0047: JSON-LD Compatibility

Summary

Explains the goals of DID Communication with respect to JSON-LD, and how Aries proposes to accomplish them.

Motivation

JSON-LD is a familiar body of conventions that enriches the expressive power of plain JSON. It is natural for people who arrive in the DID Communication (DIDComm) ecosystem to wonder whether we are using JSON-LD--and if so, how. We need a coherent answer that clarifies our intentions and that keeps us true to those intentions as the ecosystem evolves.

Tutorial

The JSON-LD spec is a recommendation work product of the W3C RDF Working Group Since it was formally recommended as version 1.0 in 2014, the JSON for Linking Data Community Group has taken up not-yet-standards-track work on a 1.1 update.

JSON-LD has significant gravitas in identity circles. It gives to JSON some capabilities that are sorely needed to model the semantic web, including linking, namespacing, datatyping, signing, and a strong story for schema (partly through the use of JSON-LD on schema.org).

However, JSON-LD also comes with some conceptual and technical baggage. It can be hard for developers to master its subtleties; it requires very flexible parsing behavior after built-in JSON support is used to deserialize; it references a family of related specs that have their own learning curve; the formality of its test suite and libraries may get in the way of a developer who just wants to read and write JSON and "get stuff done."

In addition, the problem domain of DIDComm is somewhat different from the places where JSON-LD has the most traction. The sweet spot for DIDComm is small, relatively simple JSON documents where code behavior is strongly bound to the needs of a specific interaction. DIDComm needs to work with extremely simple agents on embedded platforms. Such agents may experience full JSON-LD support as an undue burden when they don't even have a familiar desktop OS. They don't need arbitrary semantic complexity.

If we wanted to use email technology to send a verifiable credential, we would model the credential as an attachment, not enrich the schema of raw email message bodies. DIDComm invites a similar approach.

Goal

The DIDComm messaging effort that began in the Indy community wants to benefit from the accessibility of ordinary JSON, but leave an easy path for more sophisticated JSON-LD-driven patterns when the need arises. We therefore set for ourselves this goal:

Be compatible with JSON-LD, such that advanced use cases can take advantage of it where it makes sense, but impose no dependencies on the mental model or the tooling of JSON-LD for the casual developer.

What the Casual Developer Needs to Know

  • The @ character in DIDComm messages is reserved for JSON-LD-isms. Any usage of JSON keys that begin with this character is required to be JSON-LD-compatible, and any time you see it, you are seeing JSON-LD at work.

  • @type and @id are required at the root of every message. The meaning of these fields in DIDComm matches JSON-LD's expectations, but you don't need to learn JSON-LD to use them.

  • JSON-LD's more advanced mechanisms are an option--not invoked ad hoc on a message-by-message basis, but specified in the formal description of a message family. You will know how much JSON-LD is relevant to a protocol when you implement it. In general, the community will want to discuss usage of new JSON-LD constructs before embracing them in protocols with broad interoperability intentions, because of the goal articulated above.

  • The decorator concept in DIDComm is orthogonal to JSON-LD, and is far more likely to be relevant to your early learning. See the Decorator RFC.

That's it.

Details

Compatibility with JSON-LD was evaluated against version 1.1 of the JSON-LD spec, current in early 2019. If material changes in the spec are forthcoming, a new analysis may be worthwhile. Our current understanding follows.

@type

The type of a DIDComm message, and its associated route or handler in dispatching code, is given by the JSON-LD @type property at the root of a message. JSON-LD requires this value to be an IRI. DIDComm DID references are fully compliant. Instances of @type on any node other than a message root have JSON-LD meaning, but no predefined relevance in DIDComm.

@id

The identifier for a DIDComm message is given by the JSON-LD @id property at the root of a message. JSON-LD requires this value to be an IRI. DIDComm message IDs are relative IRIs, and can be converted to absolute form as described in RFC 0217: Linkable Message Paths. Instances of @id on any node other than a message root have JSON-LD meaning, but no predefined relevance in DIDComm.

@context

This is JSON-LD’s namespacing mechanism. It is active in DIDComm messages, but can be ignored for simple processing, in the same way namespaces in XML are often ignored for simple tasks.

Every DIDComm message has an associated @context, but we have chosen to follow the procedure described in section 6 of the JSON-LD spec, which focuses on how ordinary JSON can be intepreted as JSON-LD by communicating @context out of band.

DIDComm messages communicate the context out of band by specifying it in the protocol definition (e.g., RFC) for the associated message type; thus, the value of @type indirectly gives the relevant @context. In advanced use cases, @context may appear in a DIDComm message, supplementing this behavior.

Ordering

JSON-LD specifies that the order of items in arrays is NOT significant, and notes (correctly) that this is the opposite of the standard assumption for plain JSON. This makes sense when viewed through the lens of JSON-LD’s role as a transformation of RDF.

Since we want to violate as few assumptions as possible for a developer with general knowledge of JSON, DIDComm messages reverse this default, making arrays an ordered construct, as if all DIDComm message @contexts contained something like:

"each field": { "@container": "@list"}
To contravene the default, use a JSON-LD construction like this in @context:

"myfield": { "@container": "@set"}

Decorators

Decorators are JSON fragments that can be included in any DIDComm message. They enter the formally defined JSON-LD namespace via a JSON-LD fragment that is automatically imputed to every DIDComm message:

"@context": {
  "@vocab": "https://github.com/hyperledger/aries-rfcs/"
}

All decorators use the reserved prefix char ~ (tilde). For more on decorators, see the Decorator RFC.

Signing

JSON-LD is associated but not strictly bound to a signing mechanism, LD-Signatures. It’s a good mechanism, but it comes with some baggage: you must canonicalize, which means you must resolve every “term” (key name) to its fully qualified form by expanding contexts before signing. This raises the bar for JSON-LD sophistication and library dependencies.

The DIDComm community is not opposed to using LD Signatures for problems that need them, but has decided not to adopt the mechanism across the board. There is another signing mechanism that is far simpler, and adequate for many scenarios. We’ll use whichever scheme is best suited to circumstances.

Type Coercion

DIDComm messages generally do not need this feature of JSON-LD, because there are well understood conventions around date-time datatypes, and individual RFCs that define each message type can further clarify such subtleties. However, it is available on a message-type-definition basis (not ad hoc).

Node References

JSON-LD lets one field reference another. See example 93 (note that the ref could have just been “#me” instead of the fully qualified IRI). We may need this construct at some point in DIDComm, but it is not in active use yet.

Internationalization and Localization

JSON-LD describes a mechanism for this. It has approximately the same ../../features as the one described in Aries RFC 0043, with a few exceptions:

  • The JSON-LD mechanism only applies to strings; it is explicitly disallowed for describing dates, numbers, or any strings that coerce to dates or numbers.
  • The JSON-LD mechanism is language-centric rather than locale-centric. For example, it doesn't specify sort order, time-of-day, or currency semantics.
  • There is no notion of a code that maps to strings--just a notion of strings that all have the same meaning. This means it doesn’t help us solve the problem of locale-independent error codes.
  • The notion of mappings of values for different locales is separable into an external catalog, but only if a value is referenced or included implicitly in a doc. In other words, a processor has to see the full message catalog when evaluating the doc.
  • It’s a bit awkward to retrofit onto an existing schema, because it requires a redefinition of the field that contains localized values, from being a single string to being a dictionary with language mappings. In other words, the schema before and after a developer adds localization support is not just different by new, optional fields; it is a breaking change. This contrasts with the indy PR approach, where the language mapping can be added after the fact, and gets associated by convention.
  • It doesn’t support localization of keys--only values. There are corner cases where key localization is desirable.

Because of these misalignments, the DIDComm ecosystem plans to use its own solution to this problem.

Additional JSON-LD Constructs

The following JSON-LD keywords may be useful in DIDComm at some point in the future: @base, @index, @container (cf @list and @set), @nest, @value, @graph, @prefix, @reverse, @version.

Drawbacks

By attempting compatibility but only lightweight usage of JSON-LD, we are neither all-in on JSON-LD, nor all-out. This could cause confusion. We are making the bet that most developers won't need to know or care about the details; they'll simply learn that @type and @id are special, required fields on messages. Designers of protocols will need to know a bit more.

Rationale and alternatives

  • We could go all-in on JSON-LD. This would require adoption of sophisticated parsing that is impractical on embedded platforms, but it would add a lot of semantic sophistication.
  • We could avoid JSON-LD entirely. This would force us to reinvent the wheel in some cases, and it would be frustrating to our friends in other SSI communities that are more JSON-LD-centric.

Unresolved questions

  • Is the reversal of JSON-LD's default of unordered arrays valid?
  • Is there a good way to discover that new DIDComm proposals should consider JSON-LD solutions, and make sure such questions get evaluated thoughtfully?

Implementations

The following lists the implementations (if any) of this RFC. Please do a pull request to add your implementation. If the implementation is open source, include a link to the repo or to the implementation within the repo. Please be consistent in the "Name" field so that a mechanical processing of the RFCs can generate a list of all RFCs supported by an Aries implementation.

Name / Link Implementation Notes