3.6.3 emitted x-ref on every ObjectId field with a `ref` declaration. This
regressed Ajv strict-mode consumers, which throw "strict mode: unknown
keyword: x-ref" at compile time on any unknown x-* vendor extension.
Portability tests used strict:false, hiding the issue.
Fix: x-ref is opt-in via SchemaBuilderOptions.openApiExtensions = true.
Default OFF — output is keyword-clean and compiles under Ajv strict.
Turn ON to include vendor extensions for OpenAPI / Swagger / docgen.
builderOptions now threads through schemaTypeToJsonSchema →
subSchemaToJsonSchema → introspectArrayItems → jsonTypeFor (and into
jsonTypeFor's bare-Schema branch) so the flag reaches every recursion
level — including the [{type:ObjectId,ref:'X'}] shorthand path AND
array-of-array-of-subdocs with ref fields.
Migration: no action needed for validation consumers (arc, Fastify schema
validation) — the new default matches their expectation. Docgen consumers
that relied on x-ref being on by default should set the flag explicitly.
Tests: 13 new in mongooseToJsonSchema-parity.test.ts:
- Default keyword-clean assertions for ObjectId-with-ref at every nesting
level (top-level, subdoc, array shorthand, array-of-array-of-subdoc)
compile under Ajv strict:true
- Opt-in produces x-ref at every nesting level including
[[CellSchema-with-ref]] (catches future threading regressions)
- Opt-in throws expected "unknown keyword: x-ref" under Ajv strict:true
- Opt-in compiles under Ajv strict:false (standard docgen)
Full suite: 1766 passing, 4 perf opt-in skipped, 18.0s.