Home

Welcome to the Concordia wiki!

What is it?

Concordia is a JSON schema language. It only defines form but not function. In other words, it describes the types and subtypes of a JSON payload (form) but not the contents of the payload (function).

This is an important distinction; including function would be an overzealous undertaking and completely unnecessary as it is entirely application dependent. Form will provide consumers with syntactic validation, which will allow them to safely query the JSON data once it has been validated. Function is the semantic layer and is unique to each use-case.

However, it is highly encouraged that users extend this definition to include their own semantics, if desired. For example, a "number" type is defined in this specification with no other fields, but it could be extended to allow for "min" and/or "max" fields that determine the minimum and/or maximum allowed values for this field. Then, the data validation could easily be extended to look for and guarantee that the data falls within this range.

A Concordia schema may have as many additional fields as desired. Therefore, while the data may have very specific components for one application, it can still be understood and used by other applications that understand Concordia. Likewise, the data may have as many additional fields as desired, and it will still be considered valid as long as the defined fields are valid.

Who would use it?

JSON is a widely used data format for communication between two nodes. When the format of the data is know apriori, then there are more efficient technologies, such as ProtocolBuffers. However, when the communication between the two nodes is not so tightly coupled, e.g. in research or startup environments when the format can rapidly evolve or when providing a public interface for a web service, it can be highly advantageous to publish a schema that defines that payload.

For example, a startup creates a new web service with two APIs that allow users to upload and download data, respectively. If a Concordia schema was published for the upload API, it would allow user applications that are generating data to validate that data before attempting to upload. This allows remote devices to save power and time by validating points themselves and handle invalid ones before wasting networking resources. That same schema can be used on the server-side to, again, validate the data before consumption. The read API would publish its own schema that defines all possible forms of the data. Consumers can pass that schema to a code generation tool to create language-specific representations of the data.

How do I get started?

First, check out the specification. There is a Schema Definition which defines the schema in a BNF form, a Diagrams page for the more graphically inclined, and an Examples page that gives a walkthrough of how to build Concordia schemas. There is also a FAQ if you get confused. Finally, check out the code and/or use the libraries, and let us know what you think!