TransformSiblingRefs correctly rewrites a top-level component schema declared as {$ref: ..., <siblings>} into an equivalent allOf, matching OpenAPI 3.1 / JSON Schema 2020-12 semantics. However, the same shape declared in a subschema (under properties, items, additionalProperties, an allOf/anyOf/oneOf member, a parameter schema, a request/response body schema, etc.) is not transformed.
The siblings are silently dropped: the resulting *SchemaProxy reports IsReference() == true and Schema() returns only the resolved target's shape with no record of the sibling keywords.
This is a meaningful gap because property-level (and other subschema) $ref+siblings are common, such as to mark a property, whose schema comes from a $ref, as deprecated.
Here's an example spec that doesn't get transformed correctly
openapi: 3.1.0
info:
title: SiblingRefRepro
version: 1.0.0
components:
schemas:
Name:
type: string
TopLevel:
$ref: '#/components/schemas/Name'
deprecated: true
Container:
type: object
properties:
foo:
$ref: '#/components/schemas/Name'
deprecated: trueIn the above example, the TopLevel schema is processed correctly, but the schema for the foo property of Container does not.
Top-level component schemas go through low/base.SchemaProxy.Build(), which checks idx.GetConfig().TransformSiblingRefs and runs SiblingRefTransformer on the YAML node before the proxy's value node is set.
But subschema locations (object properties, items, allOf members, parameter/body schemas, etc.) take a different path:
The end result is that TransformSiblingRefs is effectively a top-level-component-only feature, despite OpenAPI 3.1 / JSON Schema 2020-12 allowing $ref with siblings anywhere a schema appears.
TransformSiblingRefscorrectly rewrites a top-level component schema declared as{$ref: ..., <siblings>}into an equivalentallOf, matching OpenAPI 3.1 / JSON Schema 2020-12 semantics. However, the same shape declared in a subschema (underproperties,items,additionalProperties, anallOf/anyOf/oneOfmember, a parameter schema, a request/response body schema, etc.) is not transformed.The siblings are silently dropped: the resulting
*SchemaProxyreportsIsReference() == trueandSchema()returns only the resolved target's shape with no record of the sibling keywords.This is a meaningful gap because property-level (and other subschema)
$ref+siblingsare common, such as to mark a property, whose schema comes from a$ref, asdeprecated.Here's an example spec that doesn't get transformed correctly
In the above example, the
TopLevelschema is processed correctly, but the schema for thefooproperty ofContainerdoes not.Top-level component schemas go through
low/base.SchemaProxy.Build(), which checksidx.GetConfig().TransformSiblingRefsand runsSiblingRefTransformeron the YAML node before the proxy's value node is set.But subschema locations (object properties, items, allOf members, parameter/body schemas, etc.) take a different path:
prepareForResolvedBuildinstead ofBuild; the former skips the sibling-transformation step entirely.The end result is that
TransformSiblingRefsis effectively a top-level-component-only feature, despite OpenAPI 3.1 / JSON Schema 2020-12 allowing$refwith siblings anywhere a schema appears.