JSON-LD Working Group

JSON-LD Working Group Guiding Principles

This document sets down the current guiding principles in use by the JSON-LD 1.1 Working Group to assist in making decisions about specification features. These guidelines provide a framework in which to have productive discussions that quickly come to consensus, rather than ending up blocked in an unresolvable tug-of-war over opposing and equally valid points of view. The principles are not meant to be interpreted as strict or objective rules, but instead as informative of the overall direction of the group to promote consistency and usability of the resulting specifications.

This document is a Living Document and as such will change. Members of the group are encouraged to edit (e.g. to update, correct, etc.) the information. Comments about this document are welcome via issues and pull request on the group’s “admin” repository or via emails sent to the group’s public-json-ld-wg@w3.org e-mail list, using a subject prefix of [Principles] ….

Table of Content

Stay on target!

We follow our overall mission of making production and consumption of the JSON serialized data as easy as possible for the widest variety of developers, with or without any experience of any underlying graph models.


Require real use cases, with actual instance data.

Features are supported by real world use cases, with actual data that can be referenced. This helps reduce entirely theoretical features that might be implemented in libraries, but never used in practice by producers or consumers.


Require at least two supporters for each use case.

As the mission is interoperability, having at least two supporters for each use case is important. If only one supporter can be found, then any features that it would require are likely too specific for inclusion in the proposed form.


As simple as possible, but no simpler.

A simpler solution (to understand, implement and use) is better than a more complex solution that accomplishes the same result.

Consistency is simpler than exceptions.

Simplicity is considered in aggregate for the set of features defined by a specification, not independently. If the same set of features can be accomplished by a smaller number of more consistent patterns, then that method is (very likely) simpler. Memorizing exceptions is harder than memorizing and applying rules.

Usability is determined by end users, not library implementers.

Usability is determined by the target audience (data producers and consumers) based on their experience of understanding and applying the specification via existing implementations, not by the experience of implementers of the specification text directly. If there is a feature that makes it harder for implementations, but easier/better for end users, then that is a worthwhile trade off. We follow the HTML Design Pattern documents notion of the Priority of Constituencies, with an emphasis on trying to make things better for everyone.


Provide on-ramps.

A solution that can be implemented in incremental stages is better than a solution that is all or nothing, as not everyone needs every feature but many people need various parts. Complex patterns should build upon simple ones, sometimes making them patterns more complicated than if they were built in isolation.

Define success, not failure.

The specifications are defined in terms of what it means to be conformant, and not patterns that are not conformant. The fewer constraints we require, the easier to have non-breaking changes in the future and the easier it is to have experimentation. In a similar way to the distinction between Open World and Closed World, if something is not defined by the specification then it is permissible (just not standardized) rather than being disallowed.


Follow existing standards and best practices, where possible and where they do not conflict with other principles.

Between invention and reuse, pick reuse… unless that reuse would demonstrably harm adoption by being more complicated than necessary.

New features should be compatible with the RDF Data Model.

It is noted that the RDF data model is the W3C standard for graph models on the web, and has been for a long time. Consistency and following existing standards are noted above as important … as is usability and general adoption by developers that are unaware of RDF at all. JSON-LD should be able to serialize all of the RDF data model (enabling a RDF to JSON-LD to RDF round trip, without loss of data). New features that are not present in the RDF data model would not survive a round trip in the other direction (JSON-LD to RDF to JSON-LD), and thus must be carefully considered as to their value.