https://github.com/OAI/OpenAPI-Specification/blob/9218ce60424b03794411a8c6d0454c1c6d31aba0/schemas/v3.0/schema.json#L1631 This causes OAS 3 documents that are valid against the spec to fail. (and breaks tooling that relies on the schema for validation) Here's an example encoding object which fails validation: ```yaml encoding: url: headers: id: $ref: '#/components/headers/id' ``` The schema should be ```json "additionalProperties": { "oneOf": [ { "$ref": "#/definitions/Header" }, { "$ref": "#/definitions/Reference" }, ] } ``` I'll submit a PR with this change for you.