Creating Schema for an API

From the outside, software development and magic are indistinguishable. Of course, with enough time you can understand how it works and for those of us who have made it through the frustration of learning to code, it’s really not all that magical after all. It’s just the application of a few simple rules.

I kind of felt that way about schema. I’d heard the term before and I had seen errors come up in my code editor saying that I had a schema validation error. As far as could tell though this all came about by some sort of magic. Well, it turns out this kind of magic can also be learned.

In my last blog post, I wrote about what it was like getting started with creating an Open API specification. In that post, I glossed over the part about creating a schema for the API. However, that was actually the hardest part of getting started with Open API for me. I realized that I didn’t really know that much about schema and how testers can use it. If you too are in that boat, I hope this article will help you out a bit!

What is an API Schema?

Well, when it comes to API schema, we are talking about a set of rules that dictate what the API request or response is allowed to look like. Creating an API schema is about finding the patterns in what the API does and creating rules that define those patterns.

At this point you might still be a bit confused and thinking “give me something concrete.” Well who am I to argue with you on this? When the people ask for concrete examples they get them, even if the people are only made up voices in my head.

Suppose you were looking at an API that gives you data about COVID cases in your country. One of the fields in the API response is the number of cases. You know some things about this field. For example, I’m pretty sure you can’t have less than 0 COVID cases (unfortunately). I’m also pretty sure you can’t have partial cases of covid. This means that you know that this field needs to be an integer that is greater than or equal to 0. These are some rules that you can apply to that field in your API response. What an API schema does is gives you a way to encode and document these rules.

How Does Open API use Schema?

Open API uses the JSON Schema as it’s starting point. It doesn’t use all the elements of JSON Schema and it does add some of it’s own elements as well, although the latest 3.1 Open API spec has pretty much synchronized the two. You can define the schema in a couple of ways. You can just do it directly inline with the resource you are trying to define, or you can create it in a shared schema section in the specification file and refer to it from the resource. I will show you an example of the second way of doing it.

In the previous post, I showed an example of defining an endpoint that looked like this:

paths:
  /endpoint/path/{pathParameter}:
    get:
      description: Makes the world a better place.
      responses:
        '200':
          description: You got a totally ok result.
       content:
            application/vnd.siren+json:
              schema:
                $ref: '#/components/schemas/SchemaName'

The $ref: part points to where it should be getting the schem from. You can create that section in the specification file and then add your schema into it.

components:
  schemas:
    SchemaName:

In this section you can then create the rules that you want to enforce. I have found the documentation on this page to be helpful with figuring out how to create the schema rules that I want. If you consider the example of an endpoint that should only have positive integers, you could specify the schema for it like this:

components:
  schemas:
    SchemaName:
      type: integer
      minimum: 1

By referencing this schema in a response, you would be saying that htis response can only contain integers that are 1 or more. There are of course, many other rules that you might want to specify in a schema, and you can see some great examples in the documentation I referenced above.

I know this is a very quick survey through the subject, but hopefully it helps you to get a grasp on what a schema is and on how and why you would want to use one in an Open API Specification.

Photo by Ivan Aleksic on Unsplash