Jan 20 · 4 min read — Data Model of Your Domain, API, and Application. Solved.

Since I have started the Good API consulting company, I have worked on hundreds of API designs across many domains. From simple, straightforward APIs to modeling the most complex domain interfaces that exist, one pattern started to emerge — the lack of information about semantics and structure of data.

Small, fast-moving organizations usually do not bother with a formal definition of data models. Larger enterprises frequently carry the burden of arcane, canonical data model which no longer works with the actual software development paradigms. In both cases, the result is the same — no formalization, no documentation, tribal knowledge of the data models used, zero visibility of models, and, inevitably, reinventing the wheel when it comes to defining new models.

No data documentation also means no discussion outside of the tribe. As a consequence, any attempt to use the data is complicated and often requires users to guess the meaning, shape or even cardinality of the data. Furthermore, without the formal description of data, every integration is tightly coupled, and any proper testing is impossible.

And when it comes to interfaces — the APIs — one is suddenly tasked to formalize data representations of information. Without any reliable source about the nature of the data, APIs often resort to exposing internal implementation framework or database models. Once again leading us on the slippery slope of tight coupling the components, which firmly welds the API clients to the internal libraries or databases.

“Supermodel helps your teams get to talking about their domains — as complex as they may be — so you can build software that matters.”

Luckily, the design-first paradigm together with API description formats (such as OpenAPI Specification, but also GraphQL or Avro Schema) is forcing us to define our data contracts. But modeling complex domains directly with these formats proved to be a chore. That is, until today. I am happy to present you!


Supermodel is a collaborative data-modeling tool and a data model registry. Supermodel uses JSON Schema in YAML format for its models. You can author the models directly at or locally on your computer and then push it to using the Supermodel command line tool (CLI).

I have created Supermodel to make my everyday work for my clients much easier, faster and efficient. I use it daily to model everything but simple API data models. I also use it to design the data once and then provide their representations in various API paradigms — the same data model then serves as the basis for derived REST and GraphQL APIs or Kafka topics!

Supermodel aspires to make data modeling accessible to modern engineers and architects while seamlessly integrating with the DevOps culture.

Once you publish a model, anybody can reference and reuse it. You can also use Supermodel to search and reuse other models including the vast collection of models based on (Google, Microsoft, Yandex & others -backed) and GS1 (Global Standards One — the nonprofit organization behind most of the Barcodes) vocabularies. visualization of Action

When you find a model that you would like to use, you can refer to it, consume it directly as JSON Schema in your development and DevOps workflow or use the Supermodel CLI tool to convert it to various other formats such as OpenAPI Specification, Apache Avro (Kafka) Schema, or GraphQL Schema.

The key objectives of Supermodel are to promote modern-day data modeling, manage complex domains, improve communication, and enable discovery and reuse of data models.

Supermodel consists of two part: — the schema registry and the Supermodel CLI — possibly one of the most comprehensive open-source tools for working with JSON Schema models. And I would like to invite you to try both try and let me know how it worked!

What are you modeling today?


– Z.

Good API

Good API Consulting Blog


Written by


Good API

Good API

Good API Consulting Blog

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade