Doctor, Who?
The Doctor has always fascinated me as a character or concept. They are a one-off, unique lifeform unlike any other in the universe, and each generation of the Doctor is also unique.
The OpenAPI Doctor is named partially after my love of character, as well as because it’s a literal heath-check, testing, and monitoring application for OpenAPI.
FYI: I am not a fan of the current generation of Doctor Who.
The Doctor has a time and space machine, a spaceship that allows time travel and offers seemingly unlimited internal space. A long-running joke of the show is that when anyone new is introduced to the Doctor and the TARDIS, they are shocked at how much bigger it is on the inside, giving rise to the phrase:
“It’s bigger on the inside.”
The ship is called the TARDIS (Time And Relative Dimensions In Space), a living organism (in a sense).
This article isn’t about Dr Who or any more of the lore but about the OpenAPI Doctor
and the latest available feature: The TARDIS.
A Time Machine for OpenAPI
Tracking changes to an OpenAPI specification is critical in any API lifecycle and governance model.
Knowing when something has changed is important, but knowing if it’s broken your downstream consumers of that contract (like SDK generators, documentation, language bindings, and more).
Diffing with a difference
In January 2025, I started building The TARDIS, essentially a complete rebuild of openapi-changes
but with a much more advanced model powering it.
Every time the OpenAPI Doctor requests a diagnosis, the changes between each edit are captured and processed via
libopenapi and the what_changed module.
Like with openapi-changes, that change model is used to render out the changes, except the difference between the Doctor and openapi-changes is that the Doctor weaves the changes into the graph, allowing us to see the changed model and how it changed.
Weaving trees
Under the hood, the OpenAPI Doctor is doing a ton of work to determine how to render the changes in multiple dimensions.
It first builds out a high-level model of the document using a core library (named doctor) based on-top of libopenapi.
The Doctor’s core library has powerful features that are unavailable under the same MIT license as libopenapi..
It’s like a turbocharged version of libopenapi., available under the BUSL 1-1 license.
The Doctor then looks back in your document’s history to extract the last change made and does the same thing, but with the older version.
These left (old) and right (modified) documents are compared using libopenapi’s what-changed module.
This module will create a walkable tree of typed and structured changes that allows any application to make a change report in any way.
The Doctor’s core library has a feature called ‘The Changerator’ that weaves the change tree into the Doctor’s model using the visitor pattern.
What we end up with is a model that contains a tree of all the objects, and each object has a list of all the changes that apply specifically to that object.
We can now build features like the TARDIS that go beyond what openapi-changes can do alone.
View changes in a more meaningful way
The OpenAPI specification timeline updates with every change or block of changes, and by clicking on the timeline, we can explore each change in multiple ways.
Statistics inform us of the number of modifications, additions and removals, and breaking changes made to each change.
A change tree shows the objects (and their ancestors) that changed. We can view that change tree via the explorer view, which visualizes it. New icons showcase which objects in the tree changed.
Spot the difference
By clicking on any of these changes in the tree or the explorer graph, the TARDIS will render that selected object in
the inspector on the right and show the properties that changed and how they changed.
There is also diff control that shows how each property was modified, highlighting the changed parts of the property (either added or removed).
With each change, the Doctor also tracks each diagnosis score and all the violations recorded for each rule.
The timeline history composes these numbers into a few charts, making it easy to see how an OpenAPI specification changes over time.
Why not just integrate openapi-changes instead
The openapi-changes tool uses libopenapi to parse the difference between a left and right OpenAPI spec; it then renders out results based directly on what comes out of libopenapi.
The Doctor takes these raw results and processes them further by weaving them into the higher-level model used by the Doctor (it does the same thing with results from vacuum).
The Doctor’s core library adds a richer model to libopenapi, and the changes for each object are added alongside violations from vacuum.
The higher-level model provides a much richer set of meta-data to create useful renderings of how things have changed.
I plan to port this upgraded experience back into openapi-changes in the future.
What is available now is still early, more power is coming soon.
- Restore any change-set or any individual property.
- Import from github and generate an entire change timeline automatically.
- Export changes to a repo via a PR, bundling up or keeping changes as is.
- Track changes automatically from a repo.
- Create workspaces for multiple specs.
- Publish a public report changelog.
- Full supported API.
- Integration with CI/CD.