Skip to content

[dependencies] Evaluate replacing JSONSchema.swift with DynamicJSON #127

Description

@DandyLyons

Problem / outcome

After #124 introduces DynamicJSON for RFC 9535 JSONPath, assess and, if parity is demonstrated, migrate md-utils JSON Schema validation from JSONSchema.swift to DynamicJSON. The goal is to consolidate the portable JSON value/query/schema stack and remove the JSONSchema.swift dependency and its WASI compatibility patch only after all existing behavior is preserved.

This issue is justified by an initial source and compatibility assessment: DynamicJSON includes a Draft 2020-12 validator, external resource providers and registries, anchors and dynamic anchors, located validation results, annotations/defaults, no package dependencies, and current Swift Package Index builds for Apple platforms, Linux, and WebAssembly.

In scope

  • Build a narrow md-utils schema-validation adapter around DynamicJSON.
  • Verify parity for MarkdownTypeChecker, MarkdownRuleChecker, CLI configuration validation, fm-var fixture validation, and OKF tests.
  • Preserve the existing explicit schema-resource model: no implicit filesystem or network retrieval.
  • Preserve external reference graph handling, canonical identifiers, nested identifiers, anchors, dynamic references, missing-resource errors, cycle rejection, and conflicting identifier rejection.
  • Preserve stable instance locations and required-property diagnostics/fix-its, or document and test any intentional diagnostic changes.
  • Isolate DynamicJSON's mutable, documented non-thread-safe registry so public md-utils types remain concurrency-safe.
  • Compare DynamicJSON's vendored JSON Schema conformance suite and ignored cases with the behavior md-utils relies on.
  • Verify Apple, native Linux, and WebAssembly builds before changing dependencies.
  • Remove JSONSchema.swift and the version-specific WASI patch only after the migration is complete and verified.

Acceptance criteria

  • Existing JSON Schema tests pass through the DynamicJSON adapter, including Draft 2020-12 const, contains, allOf, required-property, and nested external-reference coverage.
  • External resources are supplied only by the caller; validation performs no filesystem or network I/O.
  • Missing resources, cycles, conflicting identifiers, anchors, and dynamic references have deterministic tested behavior.
  • Validation diagnostics retain useful instance locations and required-property fix-it behavior.
  • Registry and validator use are safe under Swift 6 strict concurrency without exposing shared mutable non-Sendable state.
  • MarkdownUtilitiesCore builds and representative validation runs on Apple platforms, native Linux, and WebAssembly.
  • JSONSchema.swift is removed from Package.swift only after parity is demonstrated, and the obsolete WASI compatibility patch and documentation are removed in the same change.

Explicitly out of scope

  • Removing jmespath.swift. DynamicJSON implements JSONPath, not JMESPath; md-utils currently exposes JMESPath as user-facing syntax in fm search, fm unique, and rule configuration.
  • Implementing JSONPath in this issue; that remains [fm-var] Implement RFC 9535 JSONPath querying #124.
  • Hand-rolling a JSON Schema implementation.

Dependency

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or request

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions