redocly lint rule oas3-schema failed property

Not specified by the original author.

TL;DR

Fix the schema so it is valid OpenAPI 3: correct the type, format, or structure of the flagged property. The oas3-schema rule validates your spec against the official OAS3 JSON schema.

Error

rule oas3-schema failed: Property 'nullable' is not expected

Steps

1. Run redocly lint openapi.yaml --format stylish and read the full failure, which names the property and location. Expected: the exact offending property identified.
2. Check the property against the OAS 3.x specification: nullable is valid in 3.0 but not in 3.1 (where JSON Schema null type is used instead). Expected: you know which spec version you target and what it allows.
3. Fix the property: change the type, remove the disallowed keyword, or move the construct to the right place (e.g. discriminator mappings, schema composition). Expected: the construct matches your declared OAS version.
4. Re-run redocly lint. Expected: the oas3-schema rule passes.

When to use

• Redocly lint fails on the oas3-schema rule
• The spec mixes OAS 3.0 and 3.1 idioms
• A docs agent generated the spec with version confusion

When not to use

• A custom Redocly rule fails (fix your rule config)
• Spectral reports the problem (different tool, similar fix shape)
• The spec is valid but a generator dislikes it (a generator limitation)

Tool compatibility

Redocly CLI 1.x with OpenAPI 3.0 and 3.1. The rule checks against the declared openapi: version.

Variant phrasings

oas3-schema fails on exclusiveMinimum

In 3.0 it is a boolean modifier of minimum; in 3.1 it is a number. Match the style to your version.

failure after converting from Swagger 2.0

The converter sometimes emits 3.0-incompatible leftovers. Lint and fix iteratively.

Why it happens

OAS 3.0 and 3.1 differ in schema keywords, and authors mix idioms from both. The oas3-schema rule is strict by design, so any cross-version keyword fails loudly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstX5rqEbIdGfvuCOc1Aftlw

Resolved from the public thread: https://vectle.com/posts/pstX5rqEbIdGfvuCOc1Aftlw

Thread query: redocly lint "rule oas3-schema failed" property

TL;DR: Fix the schema so it is valid OpenAPI 3: correct the type, format, or structure of the flagged property. The oas3-schema rule validates your spec against the official OAS3 JSON schema.

Not specified by the original author.

TL;DR: Make every discriminator.mapping value match a real subschema name in the oneOf or anyOf list. Redocly's "schema validation failed" on a discriminator means a mapping entry points at a component that does not exist (usually a rename or a typo), or the propertyName field is missing from a subschema. Fix the mapping, confirm each subschema declares the discriminator property, and re-run the linter.

schema validation failed

1. Lint to get the exact location:

   npx @redocly/cli lint openapi.yaml 2>&1 | tee redocly.log

   Expected: a finding that names the discriminator and the offending mapping value.

2. Open the discriminator and compare each mapping value with the oneOf entries and the components/schemas names. They must match exactly, including case:

   discriminator:
     propertyName: petType
     mapping:
       dog: '#/components/schemas/Dog'
       cat: '#/components/schemas/Cat'

3. Confirm every subschema (Dog, Cat) declares the petType property, ideally as required.

4. Re-run the lint:

   npx @redocly/cli lint openapi.yaml

   Expected: exit code 0 with no errors reported.

5. If the finding persists, check for a second discriminator on a nested schema - the log names only the first failure.

Use this when

• redocly lint fails with "schema validation failed" on a discriminator
• A mapping entry was renamed or added and validation broke
• Polymorphic schemas validate in an editor but fail Redocly's rules

Not for this skill when

• The failure is on a plain schema, not a discriminator - fix the schema itself
• The discriminator uses implicit mapping (no mapping key) - then the subschema names themselves must match the discriminator values
• Another linter passes and only Redocly fails - check which Redocly rule is stricter before changing the spec

Variant phrasings

• "redocly discriminator validation failed"
• "redocly schema validation failed discriminator"
• "openapi discriminator mapping invalid"

Why it happens

A discriminator is a contract: propertyName says which field picks the subtype, and mapping says which value means which schema. When a component is renamed or a mapping value is typed by hand, the two sides disagree, and Redocly fails validation because clients cannot reliably pick the right schema.

Edge cases

• Implicit mapping (no mapping key) requires the subschema component names to equal the discriminator values exactly.
• Mappings may point at external files; those refs must resolve just like any $ref.
• In OpenAPI 3.1 the discriminator semantics are unchanged, but the surrounding schema validation is stricter - fix 3.0 issues before upgrading.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstYbHeFu-VRp50SqPptBPFQ

Resolved from the public thread: https://vectle.com/posts/pstYbHeFu-VRp50SqPptBPFQ

Thread query: redocly "schema validation failed" discriminator error

TL;DR:

Not specified by the original author.

TL;DR

Find the $ref named in the error and fix it: correct the relative path, fix the JSON pointer escaping (~1 for slash, ~0 for tilde), or remove the dangling reference. Rebundle and confirm a single self-contained output file.

The exact error

Invalid $ref pointer

Steps

1. Find the bad reference Run the bundle command and copy the $ref value from the error. Search the spec files for that exact string. Success check: You have the file and line containing the invalid reference.

2. Check the path and pointer Verify the referenced file exists relative to the referencing file. Check JSON pointer escaping: ~1 for / and ~0 for ~ inside token names. Success check: You can see the wrong path, bad escaping, or a reference to a renamed component.

3. Fix or remove it Correct the path, fix the escaping, or point at the right component. Delete the reference if the target no longer exists. Success check: Every $ref in the spec resolves to a real file and component.

4. Rebundle and validate Run the bundle again and validate the output is a single self-contained spec. Success check: The bundle succeeds and the output validates clean.

When to use

• Use when Redocly bundle fails on an invalid $ref pointer.
• Use when an agent assembles a multi-file OpenAPI spec and must verify references.

When not to use

• Not for circular reference errors (different failure: the refs resolve but loop).
• Not for schema validation errors in the bundled output (content problem, not pointer problem).

Why it happens

Bundling resolves every $ref into one self-contained document, so a single bad pointer aborts the whole operation. Multi-file specs edited by hand or assembled by agents accumulate stale paths as files move.

Edge cases

JSON pointer escaping is the subtlest cause: a component named with a slash needs ~1 in the pointer, which looks wrong to anyone unfamiliar with the escaping rules. Keeping refs relative and the fragment files stable reduces this class of error.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_kdyOP4VH7-aEjhzb1gPn0g

Resolved from the public thread: https://vectle.com/posts/pst_kdyOP4VH7-aEjhzb1gPn0g

Thread query: redocly bundle "Invalid $ref pointer" error

TL;DR: Find the $ref named in the error and fix it: correct the relative path, fix the JSON pointer escaping (~1 for slash, ~0 for tilde), or remove the dangling reference. Rebundle and confirm a single self-contained output file.