Our great sponsors
-
typescript-json-validator
Automatically generate a validator using JSON Schema and AJV for any TypeScript type.
-
SurveyJS
Open-Source JSON Form Builder to Create Dynamic Forms Right in Your App. With SurveyJS form UI libraries, you can build and style forms in a fully-integrated drag & drop form builder, render them in your JS app, and store form submission data in any backend, inc. PHP, ASP.NET Core, and Node.js.
-
openapi-cop
A proxy that validates responses and requests against an OpenAPI document. https://www.npmjs.com/package/openapi-cop https://hub.docker.com/r/lxlu/openapi-cop
-
Snowplow
The enterprise-grade behavioral data engine (web, mobile, server-side, webhooks), running cloud-natively on AWS and GCP
-
WorkOS
The modern identity platform for B2B SaaS. The APIs are flexible and easy-to-use, supporting authentication, user identity, and complex enterprise features like SSO and SCIM provisioning.
Most people do not write JSON Schema by hand. Typescript is one of the popular tools: https://github.com/vega/ts-json-schema-generator
I used https://github.com/ForbesLindesay/typescript-json-validator for a service I built recently. It parses TS types and turns them into a validator function - seems to work very well so far.
There’s a conversion of the typ to JSON schema under the hood.
> As a side note, what do people think about JSON schema? I find it quite verbose and cumbersome
Agreed. But if you want to have validation and autocompletion in most editors, it is still the way to go. We use it to validate JSON content files for a CMS [1]. It is a little repetitive in our case (e.g. the `:name`/`:description` keys are repeated), but not that bad. Newer versions of JSON Schema [2] have improved in that respect, but most editors (or plugins) and tooling in general is still based on older versions. So we have to stick with those for a while.
[1] https://github.com/frontaid/schema/blob/master/frontaid-sche...
[2] https://json-schema.org/specification.html
If you have to deal with JSON a lot, you might want to checkout https://www.schemastore.org/json/ which has schemas for a large number of file types.
I wouldn't write jsonschema definitions directly. Check out typebox. It lets you define a schema in memory and immediately have access to the types https://github.com/sinclairzx81/typebox
Combined with ajv you can even have more advanced custom validation with custom error messages.
Json schema validation is cpu expensive in nodejs, so you do not want it in production for every request. We made a proxy [1] that only allows requests that are conform to the swagger json which is easy to hook between frontend and backend in dev-mode
[1] https://github.com/EXXETA/openapi-cop
Back in the early years of Snowplow, we adopted a similar approach for our support of 3rd party webhooks[1] as an event stream source supported natively by Snowplow (https://github.com/snowplow/snowplow). (The important background here is that all events and entities flowing through Snowplow are described using versioned JSON Schema).
We built a kind of Maven Central for 3rd party webhooks' schemas[2], and got to work adding schemas for various popular webhooks, e.g. Sendgrid and Pingdom. But, we never met a single SaaS vendor who was interested in 'adopting' the JSON Schemas for their webhook, let alone publishing versioned JSON Schemas for their whole API. This meant that at Snowplow we have stayed on the hook for keeping these vendors' webhook schema definitions up to date in our registry.
It's a real tragedy of the commons - oceans of developer time wasted on tedious low-leverage work (updating API client code) so that each SaaS vendor can 'move fast and break things'. The ultimate irony is that if these vendors were to adopt, publish and respect versioned schema definitions internally, using something like OpenAPI, they would see huge productivity gains (think enhanced CI/CD testing, auto-gen of client code etc).
1. https://docs.snowplowanalytics.com/docs/getting-started-on-s...