json-schema-engine 0.0.1__tar.gz → 0.0.3__tar.gz

json_schema_engine-0.0.3/CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to `json-schema-engine` (the Python engine). The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/);
+versions follow [SemVer](https://semver.org/) with the 0.x caveat that
+minor versions may change public API.
+
+## [0.0.3] - 2026-09-21
+
+### Added
+
+- `compile_evaluator`: compiles a registered root schema into an evaluator
+  serving every output format the interpreter does (errors, annotations,
+  dropped records, the application trace), not only the verdict `flag`
+  level.
+- Plan-time resolution of `$dynamicRef`/`$recursiveRef`: a reference site
+  whose target is the same on every path that can reach it compiles as an
+  ordinary static edge instead of falling back to the interpreter;
+  `explain_compilation` reports such sites through `resolved_dynamic_sites`.
+- Runtime coverage tracking: an `unevaluated*` consumer whose evaluated
+  coverage depends on runtime branching (an `anyOf`/`oneOf` alternative, an
+  `if`'s condition) compiles directly instead of islanding, folding a
+  runtime coverage channel instead of a static licence.
+- Public `json_schema_engine.core.lowering`: the compiler lowering IR a
+  custom keyword's `lower()` is built from, previously private to the
+  engine's own keyword modules.
+
+### Changed
+
+- `first_duplicate_pair` returns a list.
+- Compiled error messages now match the interpreter's for `oneOf`,
+  `contains`, `uniqueItems`, and `type`.
+- A dialect refusing unknown keywords no longer compiles those units
+  silently: an unknown keyword under such a dialect now falls back to the
+  interpreter like any other unlowerable case, rather than being planned
+  as if the keyword were absent.
+
+## [0.0.2] - 2026-09-21
+
+The first functional release. Everything below is new relative to the
+0.0.1 name reservation.
+
+### Added
+
+- `json_schema_engine.core`: the interpreter tier. Draft 2020-12 (default),
+  2019-09, draft-07, and draft-06 with each draft's own semantics
+  (`$dynamicRef`, `$recursiveRef`, `$ref` sibling handling); `$vocabulary`
+  processing with the bundled metaschemas; loaders for remote references
+  with source-position reporting (`parse_json_with_ranges`,
+  `positions=True`, `Engine.locate`); metaschema validation on request
+  (`validate_schemas=True`); the `flag`, `basic`, `detailed`, `verbose`,
+  `list`, and `hierarchical` output formats with annotation selection,
+  error params, verbose levels, and the application trace; ECMA-262
+  regular expressions through `ecma-regex`, with a Python `re`
+  passthrough dialect and the optional `regex` backend; the
+  `reject_unsafe_regex` screen, `max_depth`, and O(n) `uniqueItems`.
+- `json_schema_engine.compiler`: `compile_validator` (a verdict-only
+  Python function bound to a registry snapshot, trampolining into the
+  interpreter for whatever it cannot lower), `emit_standalone` (a module
+  importable without the compiler), and `explain_compilation`.
+- `json_schema_engine.formats`: every format the four drafts define,
+  implemented from the RFCs and verified against the official
+  `optional/format` suites; the `idna` extra for IDNA2008
+  (`idn-hostname`, A-label checks in `hostname`); assertion opt-in through
+  `create_engine(formats=..., assert_formats=...)` and the 2020-12
+  format-assertion vocabulary.
+- Every distribution portion ships a `py.typed` marker.
+
+### Changed
+
+- The distribution depends on `ecma-regex>=0.1,<0.2`.
+- The sdist no longer carries the test tree, which needs the repository's
+  test-kit and the suite submodule.
+
+## [0.0.1] - 2026-09-20
+
+Name reservation on PyPI; no functionality.

json_schema_engine-0.0.3/PKG-INFO

@@ -0,0 +1,329 @@
+Metadata-Version: 2.5
+Name: json-schema-engine
+Version: 0.0.3
+Summary: A spec-complete, annotation-first JSON Schema engine for Python: interpreter, compiler, formats, every standard output format.
+Project-URL: Homepage, https://github.com/handrews/py-json-schema-engine
+Project-URL: Repository, https://github.com/handrews/py-json-schema-engine
+Project-URL: Issues, https://github.com/handrews/py-json-schema-engine/issues
+Author: Henry Andrews
+License-Expression: MIT
+License-File: LICENSE
+Keywords: json,json-schema,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: ecma-regex<0.2,>=0.1
+Provides-Extra: idna
+Requires-Dist: idna>=3.7; extra == 'idna'
+Provides-Extra: regex
+Requires-Dist: regex; extra == 'regex'
+Description-Content-Type: text/markdown
+
+# json-schema-engine (Python)
+
+A JSON Schema implementation for Python that aims to be both spec-complete
+and built for speed: an interpreter that is the reference semantics, a
+compiler tier for hot paths, full annotation collection, and every standard
+output format. It is the Python counterpart of
+[handrews/json-schema-engine](https://github.com/handrews/json-schema-engine)
+and shares its architecture: two tiers, one keyword registry, a frame-scoped
+record channel, and the new (2026)
+[IETF working group draft-03](https://www.ietf.org/archive/id/draft-ietf-jsonschema-json-schema-03.html)
+relevance model.
+
+Produced by Henry Andrews via Claude Code.
+
+**Status: `0.0.3` is fully compliant except for draft-04 support.**
+
+See [CHANGELOG.md](CHANGELOG.md) for the current release's contents.
+[DESIGN.md](DESIGN.md) is the design contract and carries the milestone
+status.
+
+All `0.0.x` releases will have AI-written documentation.  Version
+`0.1.0` will indicate that the documentation has been audited and revised
+by a human.
+
+The regular-expression translator lives in its own package,
+[`ecma-regex`](packages/ecma-regex/README.md) (`0.1.0`): ECMA-262 patterns
+for Python, with JavaScript semantics, no dependency on this engine.
+
+## Install
+
+```sh
+pip install json-schema-engine
+```
+
+Python 3.12+. Extras: `[idna]` for IDNA2008 support (`idn-hostname`, and the
+`xn--` label check inside `hostname`); `[regex]` to swap in the `regex`
+package as the pattern backend.
+
+## Use
+
+```python
+from json_schema_engine.core import create_engine
+
+engine = create_engine()
+uri = engine.register_schema(
+    {
+        "type": "object",
+        "properties": {"name": {"type": "string"}},
+        "required": ["name"],
+    },
+    "https://example.com/person",
+)
+assert engine.evaluate(uri, {"name": "Ada"}).valid
+result = engine.evaluate(uri, {}, output="list")
+assert result.errors is not None and result.errors[0]["evaluationPath"] == "/required"
+```
+
+Four drafts are built in: 2020-12 (the default), 2019-09, draft-07, and
+draft-06. A document's `$schema` selects its dialect; `create_engine(
+default_dialect=DIALECT_DRAFT_07)` sets the dialect for documents without
+one. Each keeps its own semantics, so a draft-07 `$ref` ignores its
+siblings while a 2019-09 one does not.
+
+Every standard output format is available by name: `flag` (the default),
+`basic`, `detailed`, and `verbose` from the
+[IETF working group draft-03](https://www.ietf.org/archive/id/draft-ietf-jsonschema-json-schema-03.html)
+output sections, and `list` and `hierarchical` from the
+[machines-oriented proposal](https://github.com/json-schema-org/json-schema-spec/blob/main/specs/output/jsonschema-validation-output-machines.md).
+Annotations are a separate control (`annotations=True`, or an
+`AnnotationSelection`), `verbose=True` asks `list`/`hierarchical` for the
+verbose level with irrelevant records marked as dropped, and `trace=True`
+adds the application tree with error indexes into `result.errors`.
+
+```python
+result = engine.evaluate(uri, {"name": 3}, output="hierarchical")
+assert result.output_document == {
+    "valid": False,
+    "evaluationPath": "",
+    "schemaLocation": "https://example.com/person#",
+    "instanceLocation": "",
+    "details": [
+        {
+            "valid": False,
+            "evaluationPath": "/properties/name",
+            "schemaLocation": "https://example.com/person#/properties/name",
+            "instanceLocation": "/name",
+            "errors": {"type": "expected string"},
+        }
+    ],
+}
+```
+
+`create_engine(validate_schemas=True)` checks every registered document
+against its metaschema and raises `SchemaValidationError` with the errors.
+A loader that reports source positions (see `parse_json_with_ranges`,
+exported from `json_schema_engine.core`) lets `evaluate(..., positions=True)`
+attach a `source` location to every error and annotation, and
+`engine.locate()` answers the same question for any schema location.
+
+## Compile
+
+The compiler tier turns a registered schema into a Python function. It is
+not a second implementation: any subschema it cannot emit (a `$dynamicRef`
+whose target differs by path, an in-place cycle) calls back into the
+interpreter, so a compiled validator is exactly
+as correct as `Engine.evaluate` and never less complete. Tier choice is a
+performance decision, not a semantic one.
+
+```python
+from json_schema_engine.compiler import compile_validator, emit_standalone
+
+compiled = compile_validator(engine, uri)
+assert compiled.validate({"name": "Ada"}) is True
+assert compiled.validate({}) is False
+print(compiled.source)  # the emitted module, for reading
+module_source = emit_standalone(engine, uri)  # importable without the compiler
+assert "def validate" in module_source
+assert "import json_schema_engine.compiler" not in module_source
+```
+
+`compile_validator` returns a verdict-only validator (the flag level) that
+binds a snapshot of the registries at compile time, so register everything
+first. `emit_standalone` writes the same code as a module that imports
+only the standard library and this package's pure helpers; it refuses,
+with `StandaloneUnsupportedError`, a schema that would need the
+interpreter at evaluation time. Compiled code assumes plain data as
+`json.loads` produces it (`dict`, `list`, `str`, `int`, `float`, `bool`,
+`None`); subclasses of those types belong to the interpreter.
+
+`compile_evaluator` compiles a schema into an evaluator serving every
+output format the interpreter does — errors, annotations, dropped
+records, and the application trace, not only the verdict. The annotation
+selection is fixed at compile time; every other control (`output`,
+`error_params`, `verbose`, `trace`, `positions`) is chosen per call, same
+as `Engine.evaluate`.
+
+```python
+from json_schema_engine.compiler import compile_evaluator
+
+evaluator = compile_evaluator(engine, uri, annotations=True)
+compiled_result = evaluator.evaluate({}, output="list", error_params=True)
+interpreted_result = engine.evaluate(
+    uri, {}, output="list", error_params=True, annotations=True
+)
+assert compiled_result.errors == interpreted_result.errors
+```
+
+## Formats
+
+`format` annotates by default in every dialect (the specs' default, and
+what the official `format.json` legs require). Assertion is opt-in, from a
+format table implemented from each format's RFC and verified against the
+official `optional/format` suite:
+
+```python
+from json_schema_engine.core import create_engine
+from json_schema_engine.formats import FORMATS_2020_12, format_table_for
+
+# The 2020-12 format-assertion vocabulary: a metaschema declaring it makes
+# `format` assert; names the table lacks are refused at registration.
+engine = create_engine(formats=FORMATS_2020_12)
+# Best effort in every standard dialect: known names assert, unknown names
+# annotate only.
+engine = create_engine(formats=FORMATS_2020_12, assert_formats=True)
+uri = engine.register_schema({"format": "date-time"}, "https://example.com/dt")
+assert engine.evaluate(uri, "1998-12-31T23:59:60Z").valid
+assert not engine.evaluate(uri, "1998-12-31T22:59:60Z").valid
+```
+
+`FORMATS_2020_12` (also 2019-09) carries the nineteen defined formats;
+`FORMATS_DRAFT_07` and `FORMATS_DRAFT_06` carry each draft's list, and
+`format_table_for(dialect_uri)` picks one. A metaschema that declares the
+format-assertion vocabulary on an engine without a table raises
+`FormatsRequiredError`, and `assert_formats=True` without a table does too.
+A custom table is any mapping of names to `FormatDefinition(test, types)`;
+`types` scopes a format to instance types other than strings.
+
+`idn-hostname` and the A-label checks inside `hostname` need IDNA2008,
+provided by the `idna` extra:
+
+```sh
+pip install 'json-schema-engine[idna]'
+```
+
+Without it, asserting `idn-hostname` raises `FormatUnavailableError` at
+registration, and `hostname` accepts a well-formed `xn--` label without
+decoding it. Compiled validators assert formats too; a standalone module
+imports the predicates it needs from `json_schema_engine.formats`, so the
+extra must be installed wherever such a module runs.
+
+## Documentation
+
+- [User guide](docs/guide/index.md) — validation, output formats,
+  annotations, dialects, loaders, source positions, metaschemas, custom
+  keywords, security, compiling schemas, and formats, topic by topic.
+- [API reference](docs/reference.md) — every public name, by package.
+- [CONTRIBUTING.md](CONTRIBUTING.md) — setup, gates, and conventions.
+- [CHANGELOG.md](CHANGELOG.md) — what changed, release by release.
+- [DESIGN.md](DESIGN.md) — the engineering design contract and milestone
+  status.
+
+## Security
+
+Schemas and instances are both often untrusted input. The interpreter
+generates no code — there is no `compile()` or `exec()` on its path — so
+code-injection concerns do not apply to it; a denial-of-service bound is
+best effort, not a guarantee, so treat wildly untrusted schemas with the
+same care as any other untrusted program input. Three specific vectors have
+a bound or an opt-out.
+
+**Regular expressions (ReDoS).** `pattern` and `patternProperties` compile
+untrusted regexes and run them against untrusted strings; Python's `re` can
+backtrack catastrophically on a pattern like `(a+)+$`. `reject_unsafe_regex`
+screens for nested unbounded quantifiers at registration:
+
+```python
+from json_schema_engine.core import create_engine, UnsafeRegexError
+
+engine = create_engine(reject_unsafe_regex=True)
+try:
+    engine.register_schema({"pattern": "(a+)+$"}, "https://ex/redos")
+except UnsafeRegexError:
+    pass  # rejected before it ever runs
+else:
+    raise AssertionError("expected UnsafeRegexError")
+```
+
+Patterns are ECMA-262 by default, translated by the `ecma-regex` package to
+the `re` backend (a `regex` backend is available via the `regex` extra);
+neither backend is linear-time, so the screen is a heuristic, not a proof.
+`regex_dialect="python"` hands patterns to `re` untouched, for schemas
+written for Python only.
+
+**Recursion depth.** `max_depth` (default 512) bounds both registration
+nesting and evaluation nesting, raising the typed `MaxDepthExceededError`
+before CPython's own stack limit can produce an untyped `RecursionError`; a
+stray `RecursionError` that does slip through is still converted to the
+same typed error. The engine stays usable afterward — each `evaluate` or
+`register_schema` call runs in fresh state, so a rejected document does not
+poison later calls.
+
+**Array uniqueness.** `uniqueItems` compares elements in O(n) by bucketing
+on a canonical key and confirming collisions with full JSON equality, so
+large arrays of distinct values do not incur quadratic cost, while genuine
+duplicates — including numbers equal across `int`/`float` and objects that
+differ only in member order — are still reported.
+
+## Development
+
+```sh
+uv sync --all-packages --all-groups
+uv run pytest -q
+uv run ruff check . && uv run ruff format --check .
+uv run pyright
+uv run lint-imports
+```
+
+The official test suite is a git submodule at `test-suite/`; clone with
+`--recurse-submodules` or run `git submodule update --init`.
+
+The [Bowtie](https://bowtie.report) conformance leg builds a container
+image and runs the suite through Bowtie's harness protocol. It needs a
+reachable container engine (Docker, or `podman machine start`) and fetches
+Bowtie through `uvx`:
+
+```sh
+uv run python scripts/bowtie_check.py
+```
+
+### Benchmarks
+
+```sh
+uv run python scripts/bench.py --budget-ms 250 --filter user
+```
+
+`scripts/bench.py` times every jse tier (the interpreter, the compiler's
+flag validator and evaluator, and the standalone artifact) against two
+competitors (fastjsonschema, jsonschema) over seven corpora in
+`packages/bench`: three small hand-authored schemas, the official OpenAPI
+3.1 schema against a real document, a generated API-payload corpus, and
+two 2000-record corpora. Every jse tier is timed against every corpus,
+`jse standalone` against `oas-document` included, since its `$dynamicRef`
+sites resolve at plan time and leave no interpreted unit. Two subjects
+measure the record-producing tier against the verdict-only tiers:
+`jse interpreter list` and `jse compiled evaluator (list)`, both timing
+`output="list"`. The bench is report-only (it enforces no performance
+threshold) and, per the IP policy below, runs the competitors only, never
+reading or porting their source. `--filter` takes a regex over
+corpus/subject/partition names; omit `--out` to skip writing JSON;
+`--compare BEFORE AFTER` prints a before/after comparison of two results
+files. The committed run lives at `packages/bench/results/results.json`
+(`--budget-ms 250`). The interpreter is the reference semantics, so ratios
+are informational, not a compatibility claim.
+[`packages/bench/README.md`](packages/bench/README.md) covers corpus
+provenance and licensing, methodology, and the recorded exclusions.
+
+## IP policy
+
+The implementation is written from the JSON Schema specifications and the
+official test suite only. Other validators are executed as benchmark subjects
+and correctness oracles; their source is never used as an implementation
+reference. See [DESIGN.md](DESIGN.md) §0.