Mintlify ignores the JSON Schema examples keyword when generating request code samples

[jeremycohensolal-paylead]

Bug report: Mintlify ignores the JSON Schema examples keyword when generating request code samples

Summary

When Mintlify generates the request code samples (cURL / Python / JavaScript) shown on an
OpenAPI operation page, it reads only the singular, deprecated example keyword on a
Schema Object property. It ignores the plural, standard examples keyword (JSON Schema
2020-12) unless the property happens to sit inside an anyOf/oneOf.

The practical consequences:

1. A property that provides a value via examples (plural) renders as a placeholder
   ("<string>") instead of its example value.
2. An enum property whose only example metadata is examples (plural) is dropped
   entirely from the generated body — even when it is required. The sample then omits a
   mandatory field, so a user who copies it produces an invalid request.

This is backwards relative to the specifications: example (singular) is deprecated in
OpenAPI 3.1, and examples (plural array) is the standard JSON Schema 2020-12 keyword —
and it is exactly the form emitted by common generators such as Pydantic v2
(Field(examples=[...])).

Environment

• Mintlify OpenAPI rendering (autogenerated code samples), reproduced locally with mint dev.
• Spec: OpenAPI 3.1.0 (Schema Object is a superset of JSON Schema 2020-12).
• The request body has no media-type-level example/examples, so the sample is
  synthesized entirely from per-property schema metadata (this is what isolates the bug).

Minimal reproduction

1. A complete, self-contained OpenAPI 3.1 spec

Four properties, all string, all required. They differ only by which example keyword
they use. Save as repro.json (or .yaml).

{
  "openapi": "3.1.0",
  "info": { "title": "Example keyword repro", "version": "1.0.0" },
  "servers": [{ "url": "https://api.example.com" }],
  "paths": {
    "/demo": {
      "post": {
        "summary": "Reproduce example vs examples",
        "operationId": "demo_repro",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Demo" }
            }
          }
        },
        "responses": { "200": { "description": "OK" } }
      }
    }
  },
  "components": {
    "schemas": {
      "Demo": {
        "type": "object",
        "required": ["with_example", "with_examples", "enum_example", "enum_examples"],
        "properties": {
          "with_example":  { "type": "string", "example":  "HELLO" },
          "with_examples": { "type": "string", "examples": ["HELLO"] },
          "enum_example":  { "type": "string", "enum": ["a", "b", "c"], "example":  "a" },
          "enum_examples": { "type": "string", "enum": ["a", "b", "c"], "examples": ["a"] }
        }
      }
    }
  }
}

2. Render it

Reference the spec from docs.json and start the dev server:

mint dev      # or: mintlify dev

Open the generated operation page and read the cURL sample in the right-hand panel.

Note: mint dev does not hot-reload spec changes — restart it after editing the spec.

3. Observed output (verbatim, captured from mint dev)

{
  "with_example": "HELLO",
  "with_examples": "<string>",
  "enum_example": "a"
}

4. Expected output

{
  "with_example": "HELLO",
  "with_examples": "HELLO",
  "enum_example": "a",
  "enum_examples": "a"
}

What this proves

Property	Keyword used	Rendered value	Verdict
with_example	example (singular)	"HELLO"	✅ correct
with_examples	examples (plural)	"<string>"	❌ example ignored
enum_example	example (singular)	"a"	✅ correct
enum_examples	examples (plural)	absent	❌ required field dropped

with_example and with_examples are byte-for-byte identical except for the keyword name and
carry the same value — so the only variable explaining the difference is the keyword itself.
enum_examples disappears from the payload entirely, which is the more damaging case: the
generated sample silently omits a required field.

Additional observed behavior (same test method)

For completeness, the full behavior matrix we verified:

• examples (plural) on a bare property → ignored (placeholder).
• examples (plural) on a property inside anyOf/oneOf → honored (Mintlify's
  union preprocessing copies examples[0] into each branch as a singular example). This is
  why nullable properties (anyOf: [{...}, {"type": "null"}]) render their examples but plain
  ones do not — an internal inconsistency.
• example (singular) as a sibling of a $ref, or placed directly on the referenced
  component schema → honored.
• An enum property with no derivable singular example/default → omitted from the
  sample (not placeholdered), required or not.
• default → honored.

Why this is a bug (standards references)

OpenAPI 3.1 defines the Schema Object as "a superset of the JSON Schema Specification Draft
2020-12", and JSON Schema 2020-12 provides the examples keyword:

§9.5 examples — "The value of this keyword MUST be an array. There are no restrictions
placed on the values within the array."
— https://json-schema.org/draft/2020-12/json-schema-validation#name-examples

The singular example keyword on the Schema Object is deprecated in OpenAPI 3.1:

Schema Object → example — "A free-form property to include an example of an instance
for this schema. […] Deprecated: The example property has been deprecated in favor of
the JSON Schema examples keyword. Use of example is discouraged, and later versions of
this specification may remove it."
— https://spec.openapis.org/oas/v3.1.0.html#schema-object

So Mintlify currently honors the deprecated form and ignores the standard, recommended
form for Schema Object properties. Tooling that follows the spec — e.g. Pydantic v2, which
emits Field(examples=[...]) → "examples": [...] — produces samples that are wrong or
incomplete in Mintlify.

Distinction that matters: at the Parameter Object / Media Type Object level, OpenAPI
defines its own example (single value) and examples (a map of named Example
Objects), and "only one of the two fields can be present." That is a different construct and
is not what this report is about. This bug is specifically about the Schema Object
property level, where examples is the JSON Schema array and is the only
non-deprecated way to attach a sample value.

Impact

• Copy-pasteable request samples contain <string> placeholders where real values were
  provided, and silently omit required enum-typed fields — users send invalid requests.
• Specs generated by standard tooling (Pydantic v2, FastAPI, and any generator emitting
  JSON Schema 2020-12) are affected out of the box, with no authoring mistake on the API side.

Workarounds (until fixed upstream)

1. Mirror examples[0] into a sibling singular example on every schema property
   (keep the plural array for spec correctness). This is the minimal, spec-compatible fix and
   is what unblocks the samples today.
2. For enum properties, ensure a singular example is derivable — set it on the referenced
   component schema so one edit covers every referencing property.
3. As a fallback for a whole body, a media-type-level
   requestBody.content["application/json"].example overrides the synthesized sample entirely.

References

• OpenAPI 3.1.0 — Schema Object (fixed field example, deprecation note):
  https://spec.openapis.org/oas/v3.1.0.html#schema-object
• OpenAPI 3.1.0 — Data Types / JSON Schema 2020-12 basis (§4.4):
  https://spec.openapis.org/oas/v3.1.0.html#data-types
• JSON Schema 2020-12 (Validation) — §9.5 examples:
  https://json-schema.org/draft/2020-12/json-schema-validation#name-examples
• Related community thread (playground prefill honors only default):
  https://github.com/orgs/mintlify/discussions/759