How do I incorporate JSON schema into my OpenAPI file?

Question

Say I have an OpenAPI swagger.yml file that looks like:

openapi: '3.0.2'
info:
  title: Simplest ever
  version: '1.0'
servers:
  - url: https://api.server.test/v1
paths:
  /test:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string

I prefer to keep the source of truth schema in my schemas/ directory, for example schemas/get.json looks like:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "message": {
      "type": "string"
    }
  }
}

The intent is for the schemas/*.json to used in my backend code base for validation for incoming and outgoing messages. Goal is to have strong API contracts.

What I don't understand is how to build the swagger.yml file using these JSON schema, instead of duplicating the work in YAML which is really tedious and error prone.

score 8 · Answer 1 · answered Feb 15 '22 at 06:24

In OpenAPI 3.1, you can reference your JSON Schemas directly:

          # openapi: 3.1.0

          content:
            application/json:
              schema:
                $ref: 'schemas/get.json'

Earlier OpenAPI versions expect that the JSON Schemas be converted to the OpenAPI Schema Object format (which can be represented as both YAML and JSON). The necessary changes include, for example:

removing unsupported keywords: $schema, patternProperties, and others;
replacing type: [<foo>, 'null'] with type: <foo> + nullable: true;
replacing other type arrays type: [type1, type2, ...] with oneOf/anyOf (OAS3) or removing them (OAS2).

json-schema-to-openapi-schema can automate the conversion.

You can try to $ref vanilla JSON Schemas directly from OAS 2.0 and 3.0 definitions, but some tools will error out on unexpected keywords and constructs.

How do I incorporate JSON schema into my OpenAPI file?

1 Answers1