Description
openedon Jun 11, 2024
We've been following the SchemaStore best practices for the development of our JSON schemas. They recommend a schema version based on what is widely supported in editors and IDEs. Previously this was draft-04, so all of our schemas currently use that version. However the new recommendation is draft-07 which comes with some quality of life improvements that can improve the readability and maintainability of our JSON schemas. Namely:
- The
$comment
keyword to explain reasoning behind schema decisions inline. - The
propertyNames
keyword to improve merging of two or more object subschemas while limitingadditionalProperties
.
Additionally, SchemaStore has an unofficial "strict mode" draft-07 meta schema https://json.schemastore.org/metaschema-draft-07-unofficial-strict.json
that requires type
, title
, and description
properties which we should be using and provides links to understanding-json-schema for each hint/check to help new JSON Schema contributors.
- There are some breaking changes from draft-04 to draft-06. You can migrate schemas from draft-04 to draft-07 using ajv-cli.
- The pattern of
*PropertiesComplete
can be updated to usepropertyNames
instead of lists of empty objects. - The
enum
properties with single values can be updated toconst
where it would make sense to useconst
.
Metadata
Assignees
Labels
Type
Projects
Status
Done