Unleash the power of the quicktype CLI

• how-to

Learn how to pass a directory of samples to the quicktype CLI to statically type all of your data in one step.

Let's make a music app

Suppose you're writing a music app that uses the Spotify API for artist, album, and playlist information from the /v1/artists, /v1/albums, and /v1/playlists API endpoints.

You'd begin by saving the sample responses from the Spotify API docs for each endpoint to data/artist.json, data/album.json, and data/playlist.json in your project directory. Then, you'd run quicktype on the data directory to generate client code for each language your app requires. In this case, pretend you have a Swift iOS app and TypeScript node server:

$ quicktype data -o models.swift # for Swift client
$ quicktype data -o models.ts    # for TypeScript server

quicktype considers all of the samples together, generating a coherent set of types to represent any substructures shared among the samples:

multiple-samples

Notice that playlists and albums both have tracks. quicktype detects this and ensures that the same type is used for the generated Album.tracks and Playlist.tracks properties. This inference isn't based on the property names, it's based on the inferred types of the data.

If quicktype didn't unify types across samples, you'd end up with code like this:

struct AlbumTrack {
    let title: String
}

struct PlaylistTrack {
    let title: String
}

struct Album {
    let tracks: [AlbumTrack]
}

struct Playlist {
    let tracks: [PlaylistTrack]
}

You'd have to pointlessly convert an AlbumTrack to a PlaylistTrack before adding it to a playlist—yuck!

Unifying samples of the same type

You can also provide multiple samples of the same type of data and quicktype will unify them. For example, if you have multiple samples of artist data, you could save them as data/artist/nirvana.json and data/artist/abba.json, and quicktype will generate an Artist type that is guaranteed to represent Nirvana and ABBA artist data:

multiple-samples-same-type-2

Notice that Artist.hits is inferred as an optional property, and Artist.members is inferred to have type number | Member[].

Typing live data

In any of these examples, you could replace a file like data/artist.json with data/artist.url, containing a single API URL. quicktype will crawl the URL and use the live data instead of static JSON. This is useful for public APIs that may introduce breaking changes; if the API changes in a way that's incompatible with your app, your app will fail to compile!

See these features in action

Here are a few demo videos that show the power of quicktyping a directory of sample data.

Swift + Xcode

TypeScript + VS Code

Let's have a contest!

We're running a contest to see who can write the best blog or make the best screencast showing off quicktype. Show how you use quicktype in your own projects, or demo an interesting use for quicktype that we haven't thought of yet. The best submissions will win one of the following:

  • Best Blog: $100 gift certificate, or $200 donated to charity in your name.
  • Best Screencast: $150 gift certificate, or $300 donated to charity in your name.

To enter the contest, simply publish a blog or screencast about quicktype and tweet it to @quicktypeio before January 1, 2018.

David

David