JSON Schema Guidelines

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. The JSON Schema specification can be found at json-schema.org. Maximize JSON Schema's features that allow extensibility, in particular set the additionalProperties property to true and don't use required enumerations for version numbers. CIECA's experience with XML schema has been very few complaints from trading partners about missing or inappropriate tags and values, and many more urgent production problems from schema validation errors. Trading Partners have very limited desire to upgrade versions and iterative agile development necessitates a new approach that doesn't require synchronizing on schema updates with our entire user community for deployments.

CIECA's XML schemas featured a cascade of include files for incorporating services, messages, code lists, and common/simple type definitions. JsonSchema can resolve references to code lists and type definitions in external files, but schemas are not included within parent schemas in the same way. CIECA's JsonSchema style will continue to gather code lists, and common/simple type definitions in external files to support schemas for individual services/messages.

Schema Building Procedures

Always make sure that you are referencing the property definition.