json-schema-generics

Approaches

allOf

https://json-schema.org/understanding-json-schema/reference/combining#allOf

Pros:

• widely supported
• add new specific event per entity
• changes to the event schema apply to all events

Cons:

• validation will fail on any schemas where entities referenced in allOf have additionalProperties: false

Codegen support

• Quicktype - ❌
• json2ts - ✅

oneOf

https://json-schema.org/understanding-json-schema/reference/combining#oneOf

Pros:

• widely supported
• only 1 file as entry point (dereferencing potentially simpler?)
• changes to the event schema apply to all events

Cons:

• can have an event with entity_name=draft and payload=Property
• when adding new entities we have to modify the central event file
• when generating types we pull all entities even if interested in only few

Codegen support

• Quicktype - ❌
• json2ts - ✅

dynamicRef + dynamicAnchor

https://json-schema.org/blog/posts/dynamicref-and-generics

https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00#rfc.section.8.2.3.2

https://json-schema.org/draft/2020-12/draft-bhutton-json-schema-00#recursive-example

Pros:

• closely resembles generics
• add new specific event per entity
• changes to the event schema apply to all events

Cons:

• latest draft, support might be sketchy (support needs investigation)
• hard to read/understand
• codegen has to run against each specific event unless they are all collected in some kind of root schema

Codegen support

• Quicktype - ❌
• json2ts - ❌

copy-paste

Create a template-event, this event then can be copy-pasted and certain attributes changed to get entity-specific event.

Pros:

• add new specific event per entity

Cons:

• changes to the base event require changes to all entity-specific events
• codegen has to run against each specific event unless they are all collected in some kind of root schema

Codegen support

• Quicktype - ✅
• json2ts - ✅

---

Tools for json schemas

TypeScript types generation

Quicktype

Pros:

• can convert to/from many languages, so using go in the futurte could potentially be covered

cons:

• merges subschemas when using oneOf, rather than using unions: GH Issue

json-schema-to-typescript

Pros:

• Correctly handles union types

Cons:

• Issue with dereferencing, limiting how we structure schemas: GH Issue

Dereferencing

• @apidevtools/json-schema-ref-parser

Validation

• jsonschema - validate JSON against the schema