OpenAPI JSON vs YAML: Preserve the Same API Description

Separate serialization from the API being described

An OpenAPI document can be represented in JSON or YAML. Choosing one of those serializations does not decide the media type of requests or responses sent by the API. An OpenAPI file written in YAML can describe a JSON response, an image upload or an empty response body.

The OpenAPI 3.1.1 format section explains the representation requirements. The example in this guide intentionally declares version 3.1.1 so the contract is explicit. Use the version supported by your own validator, documentation renderer and client generator rather than silently upgrading a document while changing its indentation.

Compare a minimal path in both formats

Here is a small fictional status operation in JSON. Its successful response has a description but makes no claim about a JSON body. This keeps the example focused on serialization and response-map keys.

{
  "openapi": "3.1.1",
  "info": {"title": "Local Status API", "version": "1.0.0"},
  "paths": {
    "/status": {
      "get": {
        "responses": {"204": {"description": "No response body"}}
      }
    }
  }
}

The equivalent YAML keeps the response code quoted. That makes its role as a string map key explicit instead of depending on a parser's treatment of an unquoted number.

openapi: 3.1.1
info:
  title: Local Status API
  version: 1.0.0
paths:
  /status:
    get:
      responses:
        '204':
          description: No response body

After parsing either form, locate paths, then /status, then get, then responses, then the string key "204". Both objects should contain exactly the same response description. If a converter has turned the response mapping into a sequence or moved it under info, the visual appearance of valid YAML is not enough.

Preserve reference locations as well as reference text

For a split description, a relative reference is interpreted in the context of the document containing it. Moving a file into another directory while converting its extension can therefore change where an unchanged relative reference resolves. Record the original location and the intended target before reorganizing a description.

A reference such as ./schemas/item.yaml also needs deliberate attention if that target becomes item.json. Converting the entry document alone does not automatically rewrite every connected document. Keep an inventory of local references and verify that each target exists in the released description bundle.

Internal references, such as a pointer into components.schemas, should continue to point to the same component name. Names are case-sensitive. A formatting or naming convention change that modifies the component key must update every corresponding reference, which is a separate semantic edit worth reviewing independently.

Stay within a portable data subset

Use ordinary string keys and JSON-compatible values when you need reliable conversion between the formats. Avoid custom YAML tags or non-string mapping keys in an OpenAPI document intended for JSON conversion. These features do not become portable merely because one YAML parser accepts them.

Quote example values when their identity as strings matters. A customer code "0012" should not become the number twelve. A boolean schema example should remain a boolean, while the literal word "false" in a text field should remain text. Add those cases to a conversion fixture instead of checking only descriptions.

YAML comments may be useful during editing, but a conventional JSON serialization has no place to carry them. If a comment explains an operational decision, keep that explanation in project documentation or an appropriate OpenAPI description field rather than assuming a round trip retains it.

Validate the document and the downstream result

The local JSON to YAML converter can transform the example's representation. It does not replace a version-aware OpenAPI validator. Parse the output, compare its data with the original, and then run the validator used by your project.

The converter rejects YAML features outside its supported JSON-compatible subset, including specialized date values, non-finite numbers and numbers that would lose precision. If a real API example uses a very large numeric identifier, keep the original representation and use a suitable lossless conversion workflow; do not change the API's declared type merely to make this converter accept it.

Finally, preview the API documentation and run the client generation or contract checks that consume the file. Check the operation, response code and reference targets in the generated output. Keep conversion separate from endpoint changes so a reviewer can identify whether a difference came from serialization or a deliberate API revision.

Related guides

YAML vs JSON Examples: Check Values, Types and Nesting

Compare matching YAML and JSON examples, distinguish strings from booleans and nulls, and test nested lists and conversion round trips.

JSON vs YAML vs TOML: Choose a Configuration Contract

Compare JSON, YAML and TOML using equivalent settings, explicit value types and round-trip checks, including comments, nulls and dates.

WordPress JSON-LD: Inspect and Maintain the Rendered Markup

Find the JSON-LD WordPress already emits, choose one publishing owner, serialize content safely, and verify changes on rendered article pages.