API Evangelist Conversation with David Biesack on JSON Schema, OpenAPI Extensions, and Building Banking APIs from Source

I’m Dave Biesack, and I’m Chief API Officer at Apiture. Apiture is a software company that provides software as a service for digital online banking for several hundred community banks and credit unions around the United States. As our name implies, the API is a big part of what we do. We have a digital banking platform that is API-driven, and we provide those APIs to partners to build applications on top of our platform — some of those partners might be the financial institutions themselves, and some might be third parties. But we build everything with APIs. We use OpenAPI 3.1 to define our APIs and then provide those on a developer portal.

OpenAPI originally defined its own way of describing schemas, back in 1.2, 2.0, and 3.0. With 3.1 they basically adopted the standard — JSON Schema, using the 2020-12 definition — with a vocabulary for the things specific to OpenAPI, using JSON Schema’s own extensibility. What that gives us is the ability to reuse JSON Schema as an open standard for the data models of our request bodies and response bodies, as well as query and header parameters. It’s a standard way to define all the data that flows in and out of our APIs, and that’s really powerful. Early on I wrote a tool called Model Gen that parses the schemas inside an OpenAPI document and extracts them into a single schema bundle. That lets a developer or tester create test data and validate it directly against the bundle without having to understand how to pull schemas out of a whole OpenAPI document.

One of the great benefits of OpenAPI, especially from 3.0 on, is the notion of components — a structure that lets you split a complex API across multiple files for reuse. We have a common OpenAPI document shared across most of our other APIs that describes reusable elements; for our error responses, for instance, we adopted application/problem+json from RFC 9457. When we define the banking APIs — accounts, transfers, transactions, ACH — they all reference those common schemas instead of copying and pasting. But that complexity can be a reach for the people implementing or testing against the APIs. So we open-sourced a tool called API Ref Resolver that bundles a document split across many files into one self-contained document with no external references. It understands the component model and works for OpenAPI as well as AsyncAPI, and it eliminates a lot of that reference complexity.

Within our pipeline we build all of our APIs from source. We have a source file managed in Git, then we run several tools that preprocess that source to produce the fully resolved, generated OpenAPI document. That’s what gets published into our developer portal, and it also gets published into our internal software repositories for other people to consume. So if the backend team is building an implementation, they can do code generation off that to build data transfer objects and the rest of the API. And when they get to that point of generating code, they don’t have to worry about any of these external references — everything is standalone and self-contained, so their job is much simpler.

Very early in our API design planning we decided that, as well as a release number on the API itself, we’d produce a version number on every schema. We start at 1.0.0; add a property, it’s a minor bump; clarify documentation or change an example, it’s a patch; a breaking change is a major version. Those versions get injected into the schema title so everyone can see them, and we publish the schemas alongside the docs so you can diff 1.1 against 1.2 over time. We also generate a release log as a YAML file — easier for authors than JSON — that’s validated against a JSON Schema. When you add a feature you create an entry referencing the Jira ticket, the description, and the version changes. We track dependencies, so if schema A changes and schema B has a property based on A, B’s version increments automatically. And when you open a pull request, the tooling validates the release notes against the schema — you can’t commit something that doesn’t conform.

We stick with YAML as much as possible because humans are doing the bulk of the work. Our OpenAPI documents are authored in YAML, and so are those release notes, because the bulk of them is free-text descriptions of what changed and why — and that’s awkward to write in JSON. Then the tools simply convert YAML to JSON when they need to process it; we use an open-source tool for that conversion and constrain ourselves to the subset of YAML that’s fully compliant with JSON, no extensions. I’ve had people show up to workshops insisting YAML and JSON are not the same thing — and they’re right, they aren’t. So we just say we’re going to stick with the subset of YAML that supports the JSON vocabulary. Authors live in YAML; the machines get JSON.

The OpenAPI authors were very prescient — they built in the ability to extend the specification, because an OpenAPI document is itself structured data we can process. We have a bunch of home-built extensions and a tool on top of our pipeline that reads the source we author and generates a fully embedded OpenAPI document. One example: a JSON Schema enum is just a list of strings with no description of what they mean. In banking we enumerate account product types — checking, savings, CD, money market. So we have an x-apiture-enum extension plus a labels file that gives each value a readable English label and a full description, and the tool injects those into the schema’s description. We do the same for deprecation: x-apiture-deprecation records when it was introduced, when it’ll be removed, and a replacement. Crucially, every one of these extensions has its own JSON Schema, so if someone mistypes a value we reject it right at processing time. We rely on JSON Schema to validate our own extensions.

It is, it is. It takes a little bit of work, but it’s there. That’s what’s nice about it — it has a defined model and a defined extensibility model as well, so people can implement tools to do all sorts of things with it. What we’ve done with our enum extension is a good example: we also partner with Speakeasy, who generate our TypeScript SDKs, and they handle enumerations with their own specification extension. Because it’s all data-driven, with a simple, schema-validated data model behind what we store in the document, it was trivial for us to convert our annotation into theirs to feed their SDK generation. Once you know the structure, it’s quite easy to write tools that do something reasonable with it — code generation, runtime validation, whatever. It’s very, very powerful.

There’s actually quite a bit of really good documentation on the json-schema.org page — good introductions and use cases. But I think it’s incumbent on us as practitioners to go out there and share. Conferences like API Days are a great place if you’re new, to get plugged in and meet people; that’s how I got my start. What’s always amazed me is how open and free this community is — people are available to answer questions, and there’s a really good community Slack you can join from json-schema.org where you’ll get great responses. There’s a Learn JSON Schema resource that covers a lot of the nuances, and I write about the subtleties on my API Design Matters blog — things like what allOf and $ref really do, or unevaluated versus additional properties, where one works and one doesn’t. It’s everywhere and it’s important to learn and use correctly. It’s easy to do it wrong, and I worry that’s what’ll happen with vibe coding — you get code generation that works for the first ten or twenty percent and breaks on the rest. So it takes some understanding, but we’ll get there.