Skip to content

refactor(format): move format validation out of JsonValidator into Formats - #101

Merged
rawo merged 2 commits into
masterfrom
refactor/96-formats
Nov 6, 2026
Merged

rawo merged 2 commits into
masterfrom
refactor/96-formats

Conversation

@rawo

@rawo rawo commented Nov 6, 2026

Copy link
Copy Markdown
Owner

Summary

Moves format validation out of JsonValidator.kt into a new internal object Formats in Formats.kt, as proposed in #96. This is a pure move with no behaviour change.

  • Formats.isValid(format, value) holds the when dispatch from validateFormat. Its 20 branches are in the same order, and unknown formats still return true.
  • Moved verbatim:
    • date, time, date-time
    • email, idn-email and their helpers
    • json-pointer, relative-json-pointer, uuid
    • uri-template and its helpers
    • duration
    • their 12 companion constants (REGEX_UUID is re-indented)
  • JsonValidator keeps formatAssertion and the error. validateFormat() is still a function and now only reports a failed Formats.isValid(), with the same message and format keyword location.
  • Calls into Idna, EcmaRegex and UriSyntax are unchanged, now made from Formats.
  • The unused SchemaKeywords.FORMAT_* imports are removed from JsonValidator.
  • JsonValidator.kt goes from 2,031 to 1,701 lines. Formats.kt is 340 lines.
  • Docs: CLAUDE.md (new Architecture entry, the JsonValidator entry, the Format Validation section) and memory/MEMORY.md. There is no CHANGELOG entry because this is an internal refactor.

There is no interface or registry, per the issue (YAGNI).

Verification

  • ./gradlew ktlintFormat, then CI=true ./gradlew test ktlintCheck --rerun-tasks, including the official suite: 5,849 tests, 0 failures, 0 errors, 0 skipped, read from build/test-results/test/*.xml.
  • test_counts.py exits 0 and reports a full run of 5,849.
  • A script compared every moved function and constant with origin/master after normalising indentation and visibility. All 15 functions, the 12 constants with their comments, and the 20 when branches in order are identical.

Closes #96

🤖 Generated with Claude Code

…rmats

Move the `format` dispatch and the remaining format families into a new
`internal object Formats` (Formats.kt) with the entry point
`Formats.isValid(format, value)`: date, time and date-time; email with
its local-part and domain helpers, and idn-email; json-pointer,
relative-json-pointer and uuid; uri-template and its helpers; duration;
and the regex and character-set constants only they use. The `when`
keeps its branches in the same order, and unknown formats are still
valid. IDNA, the ECMA 262 regex dialect and the URI grammar stay in
Idna, EcmaRegex and UriSyntax, called from Formats.

JsonValidator keeps `formatAssertion` and the error: `validateFormat()`
now only reports a failed `Formats.isValid()` with the same message and
keyword location.

Why: the formats are their own vocabulary in the 2020-12 spec (DDD), and
their grammars change with their RFCs, not with keyword evaluation
(SRP). There is no FormatValidator interface or registry (YAGNI): one
implementation, no request for custom formats, and the `when` stays
compiler-checked.

Behaviour is unchanged: function bodies, comments and constants moved
verbatim (REGEX_UUID re-indented), and the full suite passes.

Closes #96

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 #101: format validation moved into Formats

I checked the "pure move, no behaviour change" claim against the merge base (99a45e0), and I agree with it. I found nothing blocking or should-fix, only three nits.

How the move was verified

  • Per-declaration comparison. A script pulled each declaration out of both versions: functions with their preceding KDoc and comments, and constants with their comment blocks. It compared each pair after stripping whitespace per line.
    • All 15 moved functions are byte-identical even before normalisation. They kept their 4-space indentation and their private modifier.
    • The 12 constants differ only in indentation (companion object at 8 spaces, object at 4). That includes the intended REGEX_UUID re-indent, and all their comments came along.
    • A negative control (changing 1..maxDay to 0..maxDay in a copy) was reported as DIFF, so the comparison does catch changes.
  • Whole-block diff. I diffed every line removed from JsonValidator.kt (imports excluded) against Formats.kt, ignoring whitespace. The only differences are the expected ones:
    • val valid = when (format) { became fun isValid(...): Boolean = when (format) {
    • if (!valid) { was dropped
    • the package line, KDoc and object header were added, plus a closing }
  • when branches. All 20 branches are identical and in the same order, including else -> true // Unknown formats are ignored.
  • Nothing lost or duplicated.
    • No function or constant from the base JsonValidator is missing from both files.
    • None of the moved names exists in both files.
    • No moved name is still referenced from JsonValidator.
    • All 19 FORMAT_* imports in Formats.kt are used, and none of them remain in JsonValidator.
  • Build. I ran CI=true ./gradlew test ktlintCheck --rerun-tasks on an export of the PR head, with the official suite as a sibling. It reported 5,849 tests, 0 failures, 0 errors, 0 skipped (read from build/test-results/test/*.xml), and ktlint is clean.

Blocking

None. Checked:

  • The error path. The message, keyword (FORMAT), instanceLocation (path) and schemaPath (at(schemaPath, FORMAT)) are unchanged.
  • The formatAssertion guard at the call site (JsonValidator.kt:1088, [P2] formatAssertion=false still asserts formats for Draft 2019-09 #61) is untouched. The diff has no hunk in validateString, so format still comes after pattern and the error order is unchanged.

Should-fix

None. Checked:

  • Visibility. Formats is internal, and isValid is its only non-private member. The only caller is JsonValidator.kt:1097. The PR adds no public declarations and removes none, so the public and Java API is unchanged.
  • Native-image rules and state.
    • No reflection and no runtime resources.
    • No mutable global state: the only vars are function locals, and the tables are Regexs and immutable setOf sets.
  • Initialisation order. The object's initialisers build only Regexs and sets. They touch no other object during <clinit>, and Idna, UriSyntax and EcmaRegex are reached only at call time, so the order is safe.
  • Constants. The dispatch uses the SchemaKeywords constants and no string literals.
  • Style. The layout matches Idna.kt and EcmaRegex.kt: a KDoc header, the public entry first, private helpers after it and the constants at the bottom. The KDoc on Formats and isValid is accurate.
  • Docs.
    • The figures are right. JsonValidator.kt is 1,701 lines and 84,321 bytes (about 82 KB). Formats.kt is 340 lines.
    • CLAUDE.md now says formats are added in Formats.isValid().
    • No current doc (README, docs/IMPLEMENTATION_STATUS.md, docs/FEATURES.md, docs/TESTING.md) still says formats are validated in JsonValidator. The remaining mentions are in historical summaries and plans.

Nits

  1. CLAUDE.md:389-399
    • Problem: "Helper validators live in Formats.kt, grouped by family, except the URI/IP grammar in UriSyntax.kt, the IDNA ones in Idna.kt and the regex dialect in EcmaRegex.kt:" is followed only by bullets for those three exceptions. No bullet describes a Formats.kt family.
    • Fix: add a bullet such as "Formats.kt: date/time/date-time (leap second only at 23:59 UTC), email and idn-email (shared findClosingQuote() and isValidEmailLocal*()), relative-json-pointer, uri-template (isValidUriTemplateExpression/Varspec/Varname()) and duration". Or reword the lead-in so the list reads as the exceptions.
  2. src/main/kotlin/org/ktson/JsonValidator.kt:1093-1095
    • Problem: the KDoc "Validates format keyword (basic implementation)" no longer describes the function. It now only turns a failed Formats.isValid() into an error.
    • Fix: change it to something like /** Reports a format error when [Formats.isValid] rejects [value]. */.
  3. src/main/kotlin/org/ktson/JsonValidator.kt:42 (already on master, out of scope)
    • Problem: import org.ktson.SchemaKeywords.SCHEMA has no use in the file, and ktlint does not flag it. The PR does not touch it.
    • Fix: remove it in a follow-up, or here if you prefer.

🤖 Generated with Claude Code

List the format families that live in Formats.kt in CLAUDE.md's Format
Validation section, fix the stale validateFormat KDoc, and drop the
unused SchemaKeywords.SCHEMA import from JsonValidator.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@rawo
rawo merged commit 489b815 into master Nov 6, 2026
1 check passed
@rawo
rawo deleted the refactor/96-formats branch November 6, 2026 11:04
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: move format validation out of JsonValidator into Formats.kt

1 participant