Exposing the JSON Schema for API endpoints?

Question

Is there a standard to where and how to expose the schema of API endpoints?

For example, let's say the following API endpoints are available:

api/companies/

api/companies/{id}/employees/

Where should the schema for the company and employee resources be exposed?

api/company-schema.json and api/employee-schema.json?

api/schemas/company.json and api/schemas/employee.json?

Answer 1

You can setup your schema endpoints any way you like, but you should use one of the recommended correlation methods. The idea is that there is no universal rule for accessing schemas. Instead, the resource itself identifies the schema that describes it.

So, feel free to expose your schemas any way you like. And then feel free to change it if you need to without fear of breaking client implementations. Just change your response headers to point to the new schema and clients should be able to handle the change dynamically.

The most straightforward correlation method is to include a describedby Link header.

HTTP/1.1 200 OK
Content-Type: application/json
Link: </schema/companies>; rel="describedby"

{ ... }

The other option is to use the schema content-type parameter. (Note: Previous versions of JSON Schema used profile instead of schema).

HTTP/1.1 200 OK
Content-Type: application/json; schema="/schema/companies"

{ ... }

However, the schema parameter is not actually defined for the application/json media-type, so there are potential interoperability issues with that method. That's one reason why the application/schema-instance+json media type was introduced. It works just like application/json, but defines a few capabilities that the normal JSON media-type doesn't.

HTTP/1.1 200 OK
Content-Type: application/schema-instance+json; schema="/schema/companies"

{ ... }

EDIT 2020/24/01: Fix broken link and update answer to reflect changes in recent drafts.