JSON Type Validation
A TypeScript library to perform type checking and validation on untyped JSON data at runtime.
This library owes thanks to:
- JsonDecoder by Daniel van den Eijkel
- Type-safe JSON Decoder by Wesley Merkel
- The Elm Json.Decode API
Installation
npm i @mojotech/json-type-validation
Projects using < [email protected]
will need a polyfill for the unknown
type, such as unknown-ts.
Motivation
Let's say we're creating a web app for our pet sitting business, and we've picked TypeScript as one of our core technologies. This is a great choice because the extra stability and type safety that TypeScript provides is really going to help us market our business.
We've defined the data we need to track about each client's pet:
interface Pet {
name: string;
species: string;
age?: number;
isCute?: boolean;
}
And we've got some data about current client's pets which is stored as JSON:
const croc: Pet = JSON.parse('{"name":"Lyle","species":"Crocodile","isCute":true}')
const moose: Pet = JSON.parse('{"name":"Bullwinkle","age":59}')
But that can't be right -- our data for moose
is missing information required
for the Pet
interface, but TypeScript compiles the code just fine!
Of course this isn't an issue with TypeScript, but with our own type
annotations. In TypeScript JSON.parse
has a return type of any
, which pushes
the responsibility of verifying the type of data onto the user. By assuming that
all of our data is correctly formed, we've left ourselves open to unexpected
errors at runtime.
Unfortunately TypeScript doesn't provide a good built-in way to deal with this issue. Providing run-time type information is one of TypeScript's non-goals, and our web app is too important to risk using a forked version of TypeScript with that added functionality. Type guards work, but are limited in that they circumvent type inference instead of working with it, and can be cumbersome to write.
With json-type-validation
we can define decoders that validate untyped json
input. Decoders are concise, composable, and typecheck against our defined types
and interfaces.
import {Decoder, object, string, optional, number, boolean} from '@mojotech/json-type-validation'
const petDecoder: Decoder<Pet> = object({
name: string(),
species: string(),
age: optional(number()),
isCute: optional(boolean())
})
Finally, we can choose from a number of decoding methods to validate json and report success or failure. When some json input fails validation the decoder clearly shows how the data was malformed.
const lyle: Pet = petDecoder.runWithException(croc)
const bullwinkle: Pet = petDecoder.runWithException(moose)
// Throws the exception:
// `Input: {"name":"Bullwinkle","age":59}
// Failed at input: the key 'species' is required but was not present`
Documentation
Building
With Nix
There exists some Nix infrastructure that can be used
to reproduce a build environment exactly. A helper shell script lives at
bin/jtv
that you can use to enter environments for multiple uses.
You'll need to follow the directions on the Nix website to install and use the
Nix package manager.
- To enter a shell suitable for building the library run
./bin/jtv build-shell
. This will leave you in the root of the project and automatically install any project and npm dependencies. You can run further yarn commands here. - To build the library for distribution and exit you can run
./bin/jtv distribute
. - To enter a build shell and run the build process, watching for changes, run
./bin/jtv build-watch
. - To run an arbitrary command in a build environment use
./bin/jtv run COMMAND
. For example,./bin/jtv run yarn test
will run the tests and exit.