Skip to content

refactor(validation): compute a schema's effective resource root and dynamic scope in one place - #103

Merged
rawo merged 3 commits into
masterfrom
refactor/98-enter-resource
Nov 6, 2026
Merged

rawo merged 3 commits into
masterfrom
refactor/98-enter-resource

Conversation

@rawo

@rawo rawo commented Nov 6, 2026

Copy link
Copy Markdown
Owner

Summary

  • validateElement, collectEvaluatedIndices and collectEvaluatedProperties each computed the effective resource root and dynamic scope for a schema with $id. They now call two private helpers, resourceRootAt() and scopeAt(), which share one startsResource() test, so the verdict and collection passes cannot drift apart again (guideline 8, [P2] unevaluated* resolves refs in branches of an inline $id subschema against the parent resource #90). The $id registration in validateElement uses the same test and stays where it was.
  • The three copies were equivalent: validateElement checked is JsonObject inline, and the collectors had already returned for non-objects. scopeAt() still grows the scope through entering() ([P1] Dynamic scope omits root resources that have a retrieval base but no explicit $id #64). When there is no $id, the helpers return their inputs unchanged, so nothing new is allocated.
  • Removes two orphaned KDoc comments that documented nothing: "Checks if a property name matches any pattern" and "Validates the structure of a schema itself".
  • Guideline 8 in CLAUDE.md now names the helpers.

Behaviour is unchanged.

Verification

  • ./gradlew ktlintFormat
  • CI=true ./gradlew test ktlintCheck --rerun-tasks: 5,850 tests, 0 failures, 0 errors, 0 skipped (from build/test-results/test/*.xml), including the official suite
  • python3 .claude/skills/fix-issue/scripts/test_counts.py: exit 0 (full run 5,850, custom 1,380)

Closes #98

🤖 Generated with Claude Code

…dynamic scope in one place

validateElement, collectEvaluatedIndices and collectEvaluatedProperties each
spelled out "a schema with $id becomes the resource root and enters the
dynamic scope". Guideline 8 requires the verdict pass and the unevaluated*
collectors to agree on this exactly; #90 was a bug from them disagreeing.
All three now use resourceRootAt() and scopeAt(), which share one
startsResource() test (an object with $id, whatever the value's type), and
the $id registration in validateElement uses the same test. The copies were
equivalent: validateElement checked `is JsonObject` inline, the collectors
had already returned for non-objects. The helpers return their inputs
unchanged when there is no $id, so nothing new is allocated.

Removes two orphaned KDoc comments that documented nothing: "Checks if a
property name matches any pattern" (above an already documented
matchesAnyPattern) and "Validates the structure of a schema itself"
(above the companion object).

Behaviour is unchanged.

Closes #98

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@rawo rawo added the refactor Restructuring without behaviour change label Nov 6, 2026
@rawo

rawo commented Nov 6, 2026

Copy link
Copy Markdown
Owner Author

Review of #103

The refactor does what it says. All three call sites compute exactly what they computed before, the hot path allocates nothing new, and both deleted comments documented nothing. I found nothing blocking. There is one should-fix about test coverage: with the PR applied, two of the four obvious ways the passes could drift apart again still pass the whole suite. A cheap test that catches both is below. The rest are a pre-existing semantics question that the new KDoc now states as intended, and nits.

Blocking

None. What I checked:

  • Equivalence at each call site. Every input gives the same result as before:
    • object with $id
    • object without $id
    • object whose $id is not a string
    • true/false
    • string, null, array
  • validateElement (JsonValidator.kt:230-231).
    • The old inline schemaElement is JsonObject && containsKey(ID) is now startsResource(), which is the same test.
    • The only early return is still the depth check, which still runs first.
    • Non-objects return resourceRoot and dynamicScope unchanged, as before.
  • The collectors (:1305-1306, :1455-1456).
    • The depth, JsonPrimitive and !is JsonObject early returns still come before the helpers, so the helpers only ever see a JsonObject.
    • For an object, the extra is JsonObject inside startsResource is always true, so the result is the same as the old containsKey(ID).
    • The helpers are pure (entering does not mutate), so it does not matter whether they run before or after the returns.
  • Registration block (:235). schemaElement is JsonObject && startsResource(schemaElement) is the same condition as before. It still uses the parent resourceRoot to resolve parentUri, not the effective one.
  • Build. I exported the PR head with git archive and ran CI=true ./gradlew test ktlintCheck --rerun-tasks with the official suite beside it.
    • 5,850 tests, 0 failures, 0 errors, 0 skipped, from the JUnit XML. OfficialTestSuiteRunner and OfficialOutputTestRunner both ran.
    • ktlint is clean.
    • The only compiler warnings are the existing ones at JsonValidator.kt:628 and OutputFormatTest.kt:108.

Should-fix

1. No test catches a collector that stops entering an inline resource into its dynamic scope. (JsonValidator.kt:1306, :1456)

I mutated each call site on the PR head and ran the full suite each time:

Mutation Result
collectEvaluatedProperties root back to resourceRoot (:1455) caught, 9 failures
collectEvaluatedIndices root back to resourceRoot (:1305) caught, 2 failures
collectEvaluatedProperties scope back to dynamicScope (:1456) all 5,850 pass
collectEvaluatedIndices scope back to dynamicScope (:1306) all 5,850 pass

So the single definition is only half protected: the root half is tested, the scope half is not. An inline resource's place in the dynamic scope matters when a $dynamicRef below it, reached through a $ref hop, has to resolve to that resource's $dynamicAnchor because it is the outermost one. I ran the test below on the PR head, where it passes, and against each scope mutant, where it fails for the matching keyword and only that one. It fits in UnevaluatedAcrossResourcesTest (or DynamicRefResourceTest), 2020-12 only:

// An inline subschema with $id joins the collector's dynamic scope, as it does the verdict pass's (#98)
describe("an inline resource is in the collectors' dynamic scope") {
    val d = '$'
    fun schema(keyword: String, outer: String, inner: String) = """
        {"${d}id":"https://ex.com/root",
         "allOf":[{"${d}id":"outer","${d}ref":"inner","${d}defs":{"x":{"${d}dynamicAnchor":"ext",$outer}}}],
         "$keyword":false,
         "${d}defs":{"inner":{"${d}id":"inner","${d}dynamicRef":"#ext","${d}defs":{"y":{"${d}dynamicAnchor":"ext",$inner}}}}}
    """
    fun isValid(schema: String, instance: String) =
        JsonValidator().validate(Json.parseToJsonElement(instance), JsonSchema.fromString(schema, SchemaVersion.DRAFT_2020_12)).isValid

    it("unevaluatedProperties") {
        val s = schema("unevaluatedProperties", """"properties":{"a":true}""", """"properties":{"b":true}""")
        isValid(s, """{"a":1}""") shouldBe true   // #ext -> outer's anchor, the outermost in scope
        isValid(s, """{"b":1}""") shouldBe false
    }
    it("unevaluatedItems") {
        val s = schema("unevaluatedItems", """"prefixItems":[true]""", """"prefixItems":[true,true]""")
        isValid(s, "[1]") shouldBe true
        isValid(s, "[1,2]") shouldBe false
    }
}

If you add it, update the test counts in the README, CLAUDE.md and memory/MEMORY.md.

2. (Pre-existing, now written into the KDoc.) startsResource treats a non-string $id as a resource, against the project's own rule. (JsonValidator.kt:182-186, CLAUDE.md:386)

CLAUDE.md:386 says $id counts "only when their value is a string (stringKeyword())". Every other $id reader follows that rule: AbsoluteLocations.kt:111/178, JsonPointer.kt:252/327/381/414/459 and JsonSchema.extractId. startsResource uses containsKey, and its KDoc now says "whatever the value's type". This is not a regression, because the merge base behaves the same. But the PR turns it into the single, documented definition. Here is the visible effect, on the head:

{"$id":"https://ex.com/root","$defs":{"a":{"type":"integer"}},
 "properties":{"x":{"$id":5,"$ref":"#/$defs/a"}}}

{"x":1} is Invalid in both drafts, with "Could not resolve reference: #/$defs/a". The subschema becomes its own resource root, so #/... is looked up inside it. Meanwhile the anchor searches and absoluteKeywordLocation treat the same subschema as part of the root resource. If startsResource used stringKeyword(ID) != null, the instance would be Valid. I checked that by mutating only :230.

Changing it alters verdicts, so per the commit rules it should be its own fix!: change, not part of this refactor. Suggested now:

  • Either remove "whatever the value's type" from the KDoc, or say outright that this one place deliberately differs from CLAUDE.md:386 and why.
  • Open a follow-up issue to decide between containsKey and stringKeyword.

All the other $id readers I grepped have legitimately different jobs: URI registration, anchor search, absolute locations. They already go through stringKeyword and skip const/enum data, so they do not need these helpers. resolveReferences' hop() (:398) enters the target resource of a hop, including loaded documents without $id (#64). That is a different rule, not a copy, and correctly not routed through scopeAt.

Nits

  • JsonValidator.kt:235: schemaElement is JsonObject && startsResource(schemaElement). The first check repeats what startsResource already tests. It is only there so the compiler smart-casts schemaElement for stringKeyword. That is fine, but a reader may wonder whether the two tests are meant to differ. A short comment (// is JsonObject: smart cast for stringKeyword) would help. Alternatively, nest the block in the is JsonObject -> branch below.
  • Cost. startsResource is evaluated three times per validateElement call, which is the same number of containsKey lookups as before. Both helpers return their inputs unchanged when there is no $id, so the hot path allocates nothing new. No action needed.
  • Names and KDoc. resourceRootAt / scopeAt read well at the call sites. The issue suggested a single enterResource() returning a pair; two helpers avoid allocating that pair, which is the right trade.
  • Deleted comments.
    • "Checks if a property name matches any pattern" sat directly above matchesAnyPattern's real KDoc. Kotlin attaches only the nearer one, so it was dead.
    • "Validates the structure of a schema itself" sat above companion object. It described a function that 1c22633 moved to MetaSchemaCheck.
    • No documentation was lost.
  • Docs.
    • The guideline 8 addition is accurate.
    • The size claims are still right: JsonValidator.kt is 1,610 lines and 80,431 bytes (≈78.5 KiB), matching "~1,600 lines, ~78KB" in CLAUDE.md:60 and "~1,600 lines" in memory/MEMORY.md:18.
    • No imports were added or removed (SchemaKeywords.ID is used qualified, as before), and ktlint passes.

🤖 Generated with Claude Code

rawo and others added 2 commits November 6, 2026 12:44
…c scope

Reverting either collector's scope (scopeAt -> plain dynamicScope) passed
the whole suite. A 2020-12 test now sends a $dynamicRef through an inline
$id resource that the scope must contain, for unevaluatedProperties and
unevaluatedItems; each reverted collector fails it. Test counts updated.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
The KDoc no longer presents a non-string $id starting a resource as
intended: it matches the three copies it replaced, unlike the string-only
$id handling elsewhere (#57). Notes that `is JsonObject` before
startsResource in validateElement is only for the smart cast. No
behaviour change.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@rawo
rawo merged commit ab37498 into master Nov 6, 2026
1 check passed
@rawo
rawo deleted the refactor/98-enter-resource branch November 6, 2026 11:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactor Restructuring without behaviour change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: compute a schema's effective resource root and dynamic scope in one place

1 participant