Schema Should Be as Important as API Definitions

The importance of a machine-readable API definition has grown significantly over the last couple of years, with a lot of attention being spent (rightfully so) on helping educate API providers of the value of having an OpenAPI Spec, an API Blueprint, or another format. This is something I want to continue contributing to in 2017, but I also want to also shine a light on the importance of having your data schema well defined.

When you look through the documentation of many API providers, some of them provide an example request that might give hints at the underlying data model; however, you rarely ever see API providers openly sharing their schema in any usable format. You do come across some of a complete OpenAPI Spec or API Blueprints from time to time, but usually, when you find API definitions, the schema definition portion is incomplete. 

Not having your schema well-defined, shareable, and machine-readable is one of the contributing factors to a lack of common, shared schema in the API space. We have healthy examples of this in action with Schema.org, but for some reason, many of us don't bring schema front-and-center in our API operations. We are accepting them as input for our API requests and returning them with API responses, but we don't always share examples of this in our documentation, complete sections in our API definitions, or share JSON Schema as part of our developer resources. This all contributes to a lack of consistency within a single API operation, as well as the wider industry.

I am going to spend more time in 2017 talking to people about the schema that they use in their API operations and shining a light on existing schema that has been published by API providers. I will be also continuing to support important schema like Open Referral that helps streamline how our world works. It is no secret that when we speak using common schema, things work smoother and that we will make sense to a wider audience. I hope that in 2017, we can invest more in defining and sharing the schema we put to use and reusing some the most common examples out there.