edit: decide on a schema

[oliver-sanders]

We are currently considering JSON Schema, however, we should have a quick look around to make sure this is the best choice.

Points in favour of JSON Schema:

• It is used by Jedi.
• There is good tooling around it.
• It may be easier to integrate with text editors via existing JSON Schema plugins.
• JSON Schema Form extends JSON Schema into form layout/control.

[aenglyst]

Assessment of JSON Schema

The current version is 2020-12

Specification links can be found here:

Specification Links | JSON Schema (json-schema.org)

[aenglyst]

Pros

• Standardised format - JSON Schema is an IETF standard providing a format for what JSON data is required for a given application and how to interact with it. Applying such standards for a JSON document lets you enforce consistency and data validity across similar JSON data.

• Future Proofed - The JSON Schema format is a web standard meaning changes in Front End frameworks are decoupled from the data layer far downstream (Close to the clientside delivery)

• Validation of both the front and backend can be done using the same schema. It is a powerful tool for validating the structure of JSON data

• Yaml compatible

• Reusable - Already used at MO. It is used by Jedi. Creating synergy between architectures used in different areas reduces maintenance and improves scalability. This will help to future-proof the technology stack.

• API compatibility - The JSON Schema media types (application/schema+json and application/schema-instance+json) will be published as an IETF RFC, which has already been adopted by the HTTP APIs working group.

• Web validation tools - https://json-schema.org/implementations.html#validator-web%20(online)

• Text editor integration - It may be easier to integrate with text editors via existing JSON Schema plugins.
  Further investigation is required. In particular for the use of LSPs for text editor integration. This is being looked at in tickets macro: add line numbers into Python API output #2660, rose edit capabilities document #2651.

• UI form integration - JSON Schema Form extends JSON Schema into form layout/control.
  There are a number of JSON Schema form extensions available.
  A proof of concept application demonstrates the use of one of these: JSON Schema Form.

  This provides a neat solution for end-to-end data editing and validation. Some more detailed investigation is required for addressing custom widgets and hierarchical data delivery.
  Further investigation is provide in edit: choose a form generator #2644.

• Good tooling is available - Generally there is a lot of resources available for implementation. See:

  Implementations | JSON Schema (json-schema.org)

  Tools to consider include:

  cloudflare/json-schema-tools: Packages for working with JSON Schema and JSON Hyper-Schema (github.com)

  JSON Schema Web Validators and Generators

  Online JSON Schema Validator and Generator (extendsclass.com)

  JSON Schema Validator - Newtonsoft

  Create vuelidate validation rules based on json schema:

  mokkabonna/vue-vuelidate-jsonschema: Create vuelidate validation rules based on json schema (github.com)

  Customizable and hackable json-validator and json-schema utilities for traversal, data generation and validation:

  sagold/json-schema-library: Customizable and hackable json-validator and json-schema utilities for traversal, data generation and validation (github.com)

  There are many others to consider.

Cons

• Documentation - There are a few gaps in the documentation, e.g. Unevaluated Items, contentSchema

• Flexibility - It may not be flexible enough for all metadata descriptions. Data types are limited to numbers, strings and lists.

• Extendability - It is not clear how it can be extended for all metadata definitions

[aenglyst]

Alternatives

Other JSON data validators exist, and these can be used alongside tools such as jsonlint, for validating JSON for the correct format rather than allowing for custom validation of JSON instances.

Other alternative architectures for API consideration include:

OpenAPI, AsyncAPI.

Some of the alternatives to JSON Schema are TypeSchema or JTD, that instead of focusing on validation, focus on the definition of data models. Although the addition of such an extra layer may just add unnecessary complexity.

TypeSchema

TypeSchema is a code generator friendly alternative to JsonSchema explained as:

For code generators it is difficult to work with JSON Schema since it is designed to validate JSON data. In JSON Schema you don't need to provide any keywords i.e. {} is a valid JSON Schema which basically allows every value and the defined keywords are applied based on the actual data. This means you can interpret a schema only if you have also the actual data. A code generator on the other hand needs to determine a concrete type of a schema without the actual data.

Because of this TypeSchema is designed in such a way that it is possible to determine a concrete type based on the used keywords. You can think: TypeSchema is to JsonSchema what TypeScript is to Javascript, a more type safe version which has also keywords for better inheritance, union/intersection and generic handling.

JTD - jtd (jsontypedef.github.io)

Validating JSON data in shell scripts with jtd-validate (jsontypedef.com)

JSON Type Definition, aka RFC 8927, is an easy-to-learn, standardized way to define a schema for JSON data. You can use JSON Typedef to portably validate data across programming languages, create dummy data, generate code, and more.

This jtd package is a JavaScript / TypeScript implementation of JSON Type Definition. It lets you validate input data against JSON Type Definition schemas. jtd works in Node.js and web browsers.

If you're looking to generate code from schemas, check out "Generating TypeScript from JSON Typedef schemas" in the JSON Typedef docs.

Other options:
Standards for describing JSON structures:

• JSON Content Rules
• JSON LD
• RAML
  Consider in the context of API related technologies that specify own structures for JSON structures such as:
• GraphQL
• Falcor
• OData

[aenglyst]

Conclusion

In summary, although there are some limitations, json-schema seems to be a good fit for allowing validation of translated metadata and there are many implementations and pre-existing tooling to facilitate an end-to-end metadata configuration editor in a modern web driven context. This is a good technology solution, although some further work is needed to verify extensibility options and for enabling custom widget capabilities.