re: Defining reusable components with the OpenAPI specification VIEW POST


Thank you for this post.

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?


If you can limit yourself to the common subset of JSON Schema draft 5 and OpenAPI 3.0 schema objects, you'll be fine. If that's a problem, take a look at speccy ( which implements a filter to convert JSON Schema to OAS schema objects, using


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

code of conduct - report abuse