Skip to content

fix(base): keep unevaluated keywords beside allOf for sibling refs - #709

Open
Tjmstudios wants to merge 3 commits into
pb33f:mainfrom
Tjmstudios:sibling-ref-unevaluated
Open

Tjmstudios wants to merge 3 commits into
pb33f:mainfrom
Tjmstudios:sibling-ref-unevaluated

Conversation

@Tjmstudios

@Tjmstudios Tjmstudios commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Summary

The sibling-ref transformer moves every sibling of $ref into allOf member 0. For unevaluatedProperties/unevaluatedItems that's wrong, since they can't see what the $ref target evaluated from inside member 0. For $id, $defs, $anchor and the other resource keywords it changes what references resolve against. This keeps both groups on the wrapper, beside allOf.

Problem

Base:
  type: object
  properties:
    a: {type: integer}
Closed:
  $ref: '#/components/schemas/Base'
  unevaluatedProperties: false

Closed is transformed to:

allOf:
  - unevaluatedProperties: false
  - $ref: '#/components/schemas/Base'

In 2020-12, unevaluatedProperties only sees annotations from adjacent keywords. Member 0 has none, so it rejects every property. libopenapi-validator validates against RenderInline, so it rejects {"a": 1}. unevaluatedItems with a prefixItems target fails the same way. Affects 3.1 and 3.2.

Moving only unevaluated* out isn't enough when the schema has its own $id:

Scoped:
  $ref: 'base'
  $id: 'https://example.com/schemas/scoped'
  $defs:
    Extra: {type: string}
  unevaluatedProperties:
    $ref: '#/$defs/Extra'

If $id and $defs go into member 0, #/$defs/Extra on the wrapper and base in member 1 no longer resolve against https://example.com/schemas/scoped. A $anchor in member 0 names only that member, so a $ref: '#anchor' skips the $ref target.

Changes

  • createAllOfStructureWithSiblingNode: unevaluatedProperties, unevaluatedItems, $id, $schema, $vocabulary, $anchor, $dynamicAnchor, $defs and definitions stay on the wrapper. Other siblings go in member 0. If no other siblings are left, allOf holds just the $ref. The sibling node is used as member 0 as is unless a keyword moves, so the common case doesn't allocate more than main.
  • buildSemanticAllOfSchemaView: same shape in the high-level model, using the same keyword list. A test fails if the two lists drift apart.
  • renderTransformedRefWithSiblings: collapses the new shape back to $ref + siblings so Render still round-trips. Only for 3.1 and later, since 3.0 ignores siblings of $ref.
  • Boolean siblings render as allOf: [<bool>, {$ref}] from every entry point, including MarshalYAMLInline. Resource keywords stay on the wrapper. unevaluated* are dropped, since the boolean replaces the sibling's assertions.

GetTransformedRefAllOfSchema and BuildTransformedRefSemanticSchema now return a one-member allOf when the only siblings are keywords that stay on the wrapper. Nothing in the repo indexes member 1. Doc comments updated.

Tests

New tests and subtests in datamodel/low/base/sibling_ref_transformer_test.go, datamodel/high/base/schema_proxy_test.go, bundler/bundler_test.go, document_test.go and renderer/schema_renderer_test.go.

TestDocument_SiblingRefUnevaluatedKeywordsKeepResourceScope compiles GetTransformedRefAllOfSchema() and the RenderInline() output for Scoped with pb33f/jsonschema/v6 and checks they validate like the authored schema. This adds github.com/pb33f/jsonschema/v6 v6.0.3 to go.mod (and golang.org/x/text as indirect). It's only used by tests.

As a reference, the cases from these tests were run through pb33f/jsonschema v6.0.3, santhosh-tekuri/jsonschema v6.0.3, kaptinlin/jsonschema v0.9.10, python-jsonschema 4.26.0 and openapi-schema-validator 0.9.0. Each checked the authored schema, the allOf schema, the RenderInline output and the bundler output. On the authored schema all five give the result 2020-12 requires. Whether the libopenapi output gives the same result:

Case main this branch
$ref + required + unevaluatedProperties: false no, rejects {"a": 1} yes
$ref + unevaluatedProperties: false no, rejects {"a": 1} yes
$ref + unevaluatedItems over prefixItems no, rejects [1] yes
external-file $ref + unevaluatedProperties: false (bundled) no, rejects {"a": 1} yes
$ref: base with $id, recursive $defs and unevaluatedProperties no yes
$anchor beside $ref, used through $ref: '#anchor' no, accepts {"t": {"a": "x"}} yes
all resource keywords together no, base doesn't resolve yes

kaptinlin can't follow a JSON pointer into definitions under 2020-12, so it errors on the authored schema in the last case too.

The sibling-ref transformer moved every sibling of a $ref into allOf
member 0. unevaluatedProperties and unevaluatedItems only see what
adjacent keywords evaluated, so inside that member they could no longer
see the properties and items the $ref target evaluated. A schema like
{$ref: Base, unevaluatedProperties: false} then rejected every property
Base declares.

Keep both keywords on the wrapper, beside allOf. The other siblings
still go into member 0, and when unevaluated* are the only siblings,
allOf holds just the $ref. The high-level semantic view does the same,
and renderTransformedRefWithSiblings still collapses the wrapper back
to $ref plus siblings, so rendered documents keep their authored shape.
@codecov

codecov Bot commented Nov 12, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (88615e4) to head (3eeeedb).

Additional details and impacted files
@@            Coverage Diff            @@
##              main      #709   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files          315       315           
  Lines        39758     39833   +75     
=========================================
+ Hits         39758     39833   +75     
Flag Coverage Δ
unittests 100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

for i := 0; i+1 < len(siblingSchemaNode.Content); i += 2 {
keyNode, valueNode := siblingSchemaNode.Content[i], siblingSchemaNode.Content[i+1]
if isUnevaluatedKeyword(keyNode.Value) {
allOfNode.Content = append(allOfNode.Content, keyNode, valueNode)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Preserve the resource scope of the moved keyword. With sibling $id, $defs, and unevaluatedProperties: {$ref: '#/$defs/Extra'}, this moves the reference to the wrapper while $id and $defs stay in allOf[0]. I compiled GetTransformedRefAllOfSchema() with pb33f/jsonschema/v6. The base output compiled. On this head the compiler looked for #/$defs/Extra at the document root and failed. Please preserve the resource scope and add a compile test that keeps the reference intact.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. $id, $schema, $vocabulary, $anchor, $dynamicAnchor, $defs and definitions now stay on the wrapper next to unevaluatedProperties/unevaluatedItems, so #/$defs/Extra resolves against the same $id again, and so does a relative $ref like base. The high-level allOf view moves the same keywords. TestSchemaProxy_BesideAllOfKeywordsMatchTransformer fails if the two lists drift apart.

Added the compile test: TestDocument_SiblingRefUnevaluatedKeywordsKeepResourceScope uses your example. It compiles GetTransformedRefAllOfSchema() with pb33f/jsonschema/v6, so if $id or $defs end up back in allOf[0] the compile fails and the test fails. It also compiles the RenderInline() output, and checks both validate like the authored schema: {"a":1} and {"a":1,"x":"s"} pass, {"a":1,"x":2} and {"a":"s"} fail. This adds github.com/pb33f/jsonschema/v6 to go.mod as a test dependency. If you don't want it there, I can drop the compile step and keep the YAML assertions.

I ran the same cases through santhosh-tekuri/jsonschema, kaptinlin/jsonschema, python-jsonschema and openapi-schema-validator as well. The allOf schema, inline render and bundler output now validate the same as the authored schema in all of them.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One more thing on this: $id, $schema, $vocabulary, $anchor, $dynamicAnchor, $defs and definitions now always move beside allOf when they're siblings of a $ref, not only when unevaluated* is there. They describe the object holding the $ref, so leaving them on the wrapper means refs keep resolving against the same resource either way.

Also pushed a small follow-up for the codecov gap: the empty-schema build in the high-level view can't fail, so I dropped that check, and the boolean branch now has a test for when the outer schema fails to build.

Comment thread datamodel/high/base/schema_proxy.go Outdated
schema.AllOf[0] = CreateSchemaProxy(&siblingCopy)
case 1:
// every authored sibling was an unevaluated* keyword, so allOf only holds the $ref.
if len(high.NewNodeBuilder(&siblingCopy, nil).Render().Content) > 0 {

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Preserve a false boolean schema during inline rendering. I parsed a $ref whose only sibling was unevaluatedProperties: false, set proxy.Schema().BooleanSchema to a pointer to false, and called proxy.MarshalYAMLInline(). The base emitted a false member in allOf. This branch drops that member, so the output can accept an object that the edited schema rejects. Please handle BooleanSchema explicitly before using mapping content to test for an empty sibling.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed. BooleanSchema is checked before the empty-mapping check now, so with unevaluatedProperties: false as the only sibling and BooleanSchema = false, MarshalYAMLInline() renders allOf: [false, {$ref}] like main did. The "boolean sibling stays in allOf" subtest covers true and false, including the inline render.

With a boolean sibling, $id/$anchor etc. stay on the wrapper since the $ref resolves against them. unevaluated* are dropped, since the boolean replaces the sibling's assertions.

if isUnevaluatedKeyword(keyNode.Value) {
allOfNode.Content = append(allOfNode.Content, keyNode, valueNode)
} else {
kept = append(kept, keyNode, valueNode)

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Allocate kept only when a keyword moves. For a $ref with title, description, and required, I measured 28 allocations per TransformSiblingRef call on this head versus 25 on the base. All three siblings stay in the original node, so the new slice is discarded. On the first keyword that moves, copy the preceding pairs and start collecting the remaining ones.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Changed. The sibling node is used as the allOf member until a keyword has to move. At that point the earlier pairs get copied and the rest are collected from there. With only title/description/required siblings it's 25 allocs per call, same as main (previous head was 28). TestSiblingRefTransformer_CreateAllOfStructure catches a bad copy of the earlier pairs.

$id, $schema, $vocabulary, $anchor, $dynamicAnchor, $defs and definitions
now stay on the allOf wrapper with unevaluatedProperties and
unevaluatedItems, so a relative $ref still resolves against the authored
$id, $anchor still names the whole object, and $defs pointers still reach
their subschemas. The high-level allOf view moves the same keywords, the
collapse back to the $ref form only applies to OpenAPI 3.1 and later, and
a boolean sibling renders as allOf: [bool, {$ref}] from every entry point.
The member is only copied when a keyword moves.

The document test compiles the allOf schema and the inline render with
pb33f/jsonschema and checks they validate like the authored schema, which
adds github.com/pb33f/jsonschema/v6 to go.mod.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants