Convert an OpenAPI YAML Specification to JSON

The whole document becomes one self-contained JSON object, ready for Postman or a generator.

Input (openapi.yaml):
openapi: 3.0.3
info:
  title: Pet API
  version: "1.0.0"
paths:
  /pets:
    get:
      responses:
        "200": { description: OK }

Output JSON (2-space):
{
  "openapi": "3.0.3",
  "info": { "title": "Pet API", "version": "1.0.0" },
  "paths": { "/pets": { "get": { "responses": { "200": { "description": "OK" } } } } }
}

Internal component refs survive as strings (correct). External file refs are also left literal — bundle first so the JSON is self-contained.

Input:
components:
  schemas:
    Pet:
      $ref: '#/components/schemas/Animal'   // internal — kept
    User:
      $ref: './schemas/user.yaml'          // external — kept literal

Output JSON:
{ "components": { "schemas": {
  "Pet":  { "$ref": "#/components/schemas/Animal" },
  "User": { "$ref": "./schemas/user.yaml" }
} } }

Fix for external refs: swagger-cli bundle openapi.yaml > bundled.yaml,
then convert bundled.yaml.

An unquoted swagger: 2.0 becomes the number 2, which is an invalid spec. Always quote the version.

Input (WRONG):
swagger: 2.0

Output JSON:
{ "swagger": 2 }   // invalid — tooling rejects it

Input (RIGHT):
swagger: "2.0"

Output JSON:
{ "swagger": "2.0" }   // valid Swagger 2.0 marker

Hand-written specs sometimes DRY up a repeated schema with an anchor. The converter inlines it — no aliases remain, so the JSON is fully self-contained.

Input:
components:
  schemas:
    Timestamps: &ts
      type: object
      properties:
        createdAt: { type: string, format: date-time }
    Post:
      allOf:
        - *ts
        - type: object
          properties: { title: { type: string } }

Output JSON: the *ts alias is replaced inline with the full
Timestamps object inside Post.allOf — no anchors left.

Vendor extensions pass through unchanged so the platform that reads them still works after conversion.

Input:
x-tagGroups:
  - name: Core
    tags: [pets, users]
paths:
  /pets:
    x-amazon-apigateway-integration:
      type: aws_proxy

Output JSON (extensions untouched):
{
  "x-tagGroups": [ { "name": "Core", "tags": ["pets", "users"] } ],
  "paths": { "/pets": { "x-amazon-apigateway-integration": { "type": "aws_proxy" } } }
}

$ref: './schemas/user.yaml' is preserved as a literal string, not inlined — $ref is an OpenAPI feature, not a YAML one, and there is no filesystem in the browser to read the other file. Bundle the spec into one file with swagger-cli bundle or @redocly/cli bundle before converting if you need a self-contained JSON.

Unquoted 2.0 is a float and serializes to 2, which is not a valid Swagger version marker — importers reject it. Always write swagger: "2.0". Same applies to a numeric info.version like 1.10, which becomes 1.1; quote it.

A tab in indentation throws tab characters must not be used in indentation with line/column. OpenAPI tooling would reject tabs too. Re-indent with spaces.

Two identical path keys, or two get: operations under one path, throw duplicated mapping key. The parser rejects rather than keeping the last — a good thing, since a duplicate path in a spec is a real bug. Fix it before converting.

Response codes should be quoted strings ("200") in OpenAPI. An unquoted 200: parses as a numeric key in YAML, and while js-yaml emits it as a JSON object key (always a string in JSON), some specs rely on the exact string form — quoting avoids ambiguity, especially for "default" alongside numeric codes.

An empty file parses to undefined, outputting the literal undefined rather than {}. Paste a real spec starting with openapi: or swagger:.

Specs have no custom YAML tags, but a stray !-prefixed value throws unknown tag. Only standard YAML 1.2 tags are recognised. Remove or quote the tagged value.

An example: 9007199254740993 (above 2^53−1) loses precision through the JS number type. For 64-bit ID examples, quote them as strings in the spec so they round-trip exactly.

Large bundled specs (every schema inlined) can exceed the 2 MB free-tier limit. Pro raises it to 100 MB. Alternatively, validate against the un-bundled spec and only bundle for the final artifact.

Internal #/components/... refs are preserved, not dereferenced — that is the correct, portable form, and Postman / generators resolve them. If you specifically need a fully-dereferenced spec, run a deref tool (e.g. @redocly/cli bundle --dereferenced) before converting.