Defining reusable components with the OpenAPI specification

A pattern I'm seeing increasingly, is to compose OpenAPI specification (OAS, formerly known as Swagger) documents from multiple files. This allows re-use, easier collaboration and makes larger documents much easier to follow.

The resultant document can be parsed by tools which fully understand and implement the JSON Reference specification (i.e. they include a resolver), or it can be 'bundled' by de-referencing external references using such a JSON Reference-implementing tool.

But what should those fragments of OAS documents look like?

The OAS specification makes no rulings on this, other than the object being referenced must be of the expected type.

Thus a parameter definition in a self-contained OAS document may look like this:

The problem with both styles of included document, is that neither is defined by any standard other than being valid JSON or YAML. Neither can be validated against a specification, even though their contents should be composed of valid OAS objects.

It raises questions such as: is it allowable to share the definition of the sortType schema across OAS v2 and OAS v3 documents, even though the definition of the Schema Object differs between the two specifications?

I would argue there are significant benefits in always structuring your included documents as fully valid OAS documents.

At the cost of the following six lines of metadata overhead (a little more in JSON), and slightly longer $ref values, our parameters.yaml document becomes:

This document now has the benefits that it can be validated, linted, converted, transformed and edited using OAS compliant tools. In the case of conversion, it means OAS v2 document fragments can be upgraded in place to OAS v3 without having to bundle the document into a monolith.

The minimal info object gives us properties to describe the expected usage of the fragment, and an ability to version it separately from the 'master' OAS documents which reference it.

Simply by the presence of the empty paths object, we can tell we are dealing with a fragment, not a fully-defined OAS document.

These reusable sub-documents can also be shared between projects, allowing for industry-specific standard components to emerge.

Currently I am working on a software project to develop a catalog of software tooling. As part of this project, I have developed a JSON Schema for describing tools. I want to avoid repeating myself, so I would like to incorporate this schema into my API contract which I am currently writing in OpenAPI 3.0. Do you think it would be problematic if I just incorporated the schema directly, even though I would be embedding a JSON Schema document into an OpenAPI document? What do you generally recommend for interoperability between the two?

Another possible approach is to use the x-oas-draft-alternativeSchema extension (github.com/OAI/OpenAPI-Specificati...) although as this is brand new, we don't yet know of any implementations - so would probably only suit your own tooling.