JSON Schema is the most important API specification today. I’ll fight anyone on this. It is more important than OpenAPI, AsyncAPI, GraphQL, Protocol Buffers, and even my own APIs.json. Why? Because every aspect of API operations is defined and validated by JSON Schema. OpenAPI and AsyncAPI both use JSON Schema. Every enterprise organization is using JSON Schema, most just are completely unaware they are, and aren’t very good at applying it evenly. JSON Schema is how API operations are defined and validated at design, develop, build, run, and distribute time.
As described on the JSON Schema site, “While JSON is probably the most popular format for exchanging data, JSON Schema is the vocabulary that enables JSON data consistency, validity, and interoperability at scale.” Everything I do is defined as JSON Schema. I don’t have a resource, capability, or process that isn’t defined as JSON Schema. Ironically I don’t actually edit any of my resources, capabilities, or processes in JSON, I do it in YAML, which I convert to JSON at build and run-time, or on the fly during design and development time so I can validate. I use JSON Schema so extensively not just for the sake of the technology, I do it because I do not trust myself to not phat finger, mix-up, or just get things plain wrong during the course of any day. Some days I am very detail-oriented and won’t make a mistake, but most days I am distracted, busy, and out of balance, and JSON Schema keeps me on the rails moving forward.
Most people do not understand JSON Schema. Most people use JSON Schema, from form validation on the web, to validating your OpenAPI in your design tool, to validating API responses in the gateway—JSON Schema validates us. Validation is an essential part of keeping us all moving forward, but I find the process of defining more worlds in a structured way using JSON Schema helps me slow down and properly define what is happening. Much like adopting a design-first approach to delivering your HTTP APIs using OpenAPI (which is all JSON Schema), defining API operations as small, modular, and human or machine-readable schema that are well defined as JSON Schema, helps you get all the Lego bricks organized in a way that lets you build the Lego City or Millennium Falcon of your dreams—ensuring all the pieces fit together properly.
The API Commons is now dedicated to being where you go to find the common properties of API contracts, providing the business and technical building blocks you need to define your API operations. APIs.json and all the common and community properties available in the API Commons are all defined and validated using JSON Schema. APIs.json employs less opinionated array-based common and API property structure, each with a type describing the property, so that the API contract structure can be flexible enough to describe any property of our API operations, but also independently validate properties using JSON Schema when possible. APIs.json API contracts can be used to define the internal, 1st-party, and 3rd-party APIs you produce or consume, with JSON Schema validating the overall contract, but also the individual OpenAPI, plans, SDKs, security, and other properties you need to define and govern your API operations. This is how JSON Schema can be used to define and validate your API operations.
I will keep evangelizing the importance of JSON Schema. I will keep forcing it on my clients when it comes to API contract management. I will keep investing in more guidance regarding how it can be used by product people as well as engineers. I actually think a YAMLized version with the right YAML management system (YMS) has huge potential for business stakeholders, but we have to get them more confident with stepping onto this bridge. I am confident that YAML + Git, with the right supporting services and tools, is the future of business alignment across the API lifecycle. YAML is the configuration and control business stakeholders are looking for when it comes to optimizing how they provide digital resources and capabilities in the internal, 1st-party, and 3rd-party desktop, web, mobile, and artificial intelligence applications they develop and maintain. I see YAML + Git like you ops people see Kubernetes, but instead of configuring, optimizing, and scaling infrastructure, I am looking to give business stakeholders the ability to configure, optimize, and scale the enterprise digital API supply chain, distribution channel, and factory floor.
