feat: Evaluate API

Signed-off-by: Dmitry Dygalo <dmitry@dygalo.dev>

Author: Stranger6667

MIGRATION.md

@@ -87,6 +87,32 @@ use jsonschema::primitive_type::{PrimitiveType, PrimitiveTypesBitMap};
 use jsonschema::types::{JsonType, JsonTypeSet};
 ```
 
+### Removal of `Validator::apply`, `Output`, and `BasicOutput`
+
+The legacy `apply()` API and its `BasicOutput`/`OutputUnit` structures have been removed in favor of
+the richer [`Validator::evaluate`](https://docs.rs/jsonschema/latest/jsonschema/struct.Validator.html#method.evaluate)
+interface that exposes the JSON Schema output formats directly.
+
+```rust
+// Old (0.34.x)
+let output = validator.apply(&instance).basic();
+match output {
+    BasicOutput::Valid(units) => println!("valid: {units:?}"),
+    BasicOutput::Invalid(errors) => println!("errors: {errors:?}"),
+}
+
+// New (0.35.0)
+let evaluation = validator.evaluate(&instance);
+if evaluation.flag().valid {
+    println!("valid");
+}
+let list = serde_json::to_value(evaluation.list())?;
+let hierarchical = serde_json::to_value(evaluation.hierarchical())?;
+```
+
+`Annotations` and `ErrorDescription` continue to be available if you need to inspect the evaluation
+tree manually.
+
 ## Upgrading from 0.33.x to 0.34.0
 
 ### Removed `Validator::config()`

codecov.yaml

@@ -6,9 +6,14 @@ coverage:
     project: off
     patch: off
 
-# Ignore test/benchmark infrastructure from coverage
+# Ignore test/benchmark infrastructure & dev-only suite helpers from coverage
 ignore:
   - "crates/benchmark/"
   - "crates/benchmark-suite/"
   - "crates/jsonschema-testsuite/"
+  - "crates/jsonschema-testsuite-codegen/"
+  - "crates/jsonschema-testsuite-internal/"
   - "crates/jsonschema-referencing-testsuite/"
+  - "crates/jsonschema-referencing-testsuite-codegen/"
+  - "crates/jsonschema-referencing-testsuite-internal/"
+  - "crates/testsuite-common/"

crates/jsonschema-py/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- Python bindings for `evaluate`: a new `jsonschema_rs.evaluate()` helper, `Validator.evaluate()`, and the `Evaluation` class for accessing flag/list/hierarchical outputs plus collected annotations & errors without re-validating in Python.
+
 ## [0.35.0] - 2025-11-16
 
 ### Added

crates/jsonschema-py/README.md

@@ -155,6 +155,36 @@ On instance:
     "unknown"'''
 ```
 
+### Structured Output with `evaluate`
+
+When you need more than a boolean result, use the `evaluate` helpers to access the JSON Schema output formats defined by the specification:
+
+```python
+import jsonschema_rs
+
+schema = {
+    "type": "object",
+    "required": ["name"],
+    "properties": {"name": {"type": "string"}, "age": {"type": "number", "minimum": 0}},
+}
+instance = {"name": "Alice", "age": -3}
+
+# One-off evaluation
+evaluation = jsonschema_rs.evaluate(schema, instance)
+
+# Or reuse a validator
+validator = jsonschema_rs.validator_for(schema)
+evaluation = validator.evaluate(instance)
+
+assert evaluation.valid is False
+print(evaluation.flag())          # {"valid": False}
+print(evaluation.list())          # Flat list of evaluation steps
+print(evaluation.hierarchical())  # Nested tree of evaluations
+
+for error in evaluation.errors():
+    print(error["instanceLocation"], error["error"])
+```
+
 ### Arbitrary-Precision Numbers
 
 The Python bindings always include the `arbitrary-precision` support from the Rust validator, so numeric

crates/jsonschema-py/python/jsonschema_rs/__init__.py

@@ -11,10 +11,12 @@
     Draft201909Validator,
     Draft202012,
     Draft202012Validator,
+    Evaluation,
     FancyRegexOptions,
     RegexOptions,
     Registry,
     ValidationErrorKind,
+    evaluate,
     is_valid,
     iter_errors,
     meta,
@@ -77,9 +79,11 @@ def __repr__(self) -> str:
     "ReferencingError",
     "ValidationError",
     "ValidationErrorKind",
+    "Evaluation",
     "is_valid",
     "validate",
     "iter_errors",
+    "evaluate",
     "validator_for",
     "Draft4",
     "Draft6",

crates/jsonschema-py/python/jsonschema_rs/__init__.pyi

@@ -1,11 +1,31 @@
 from collections.abc import Iterator
-from typing import Any, Callable, Protocol, TypeAlias, TypeVar, Union
+from typing import Any, Callable, List, Protocol, TypeAlias, TypeVar, TypedDict, Union
 
 _SchemaT = TypeVar("_SchemaT", bool, dict[str, Any])
 _FormatFunc = TypeVar("_FormatFunc", bound=Callable[[str], bool])
 JSONType: TypeAlias = dict[str, Any] | list | str | int | float | bool | None
 JSONPrimitive: TypeAlias = str | int | float | bool | None
 
+class EvaluationAnnotation(TypedDict):
+    schemaLocation: str
+    absoluteKeywordLocation: str | None
+    instanceLocation: str
+    annotations: JSONType
+
+class EvaluationErrorEntry(TypedDict):
+    schemaLocation: str
+    absoluteKeywordLocation: str | None
+    instanceLocation: str
+    error: str
+
+class Evaluation:
+    valid: bool
+    def flag(self) -> JSONType: ...
+    def list(self) -> JSONType: ...
+    def hierarchical(self) -> JSONType: ...
+    def annotations(self) -> List[EvaluationAnnotation]: ...
+    def errors(self) -> List[EvaluationErrorEntry]: ...
+
 class FancyRegexOptions:
     def __init__(
         self, backtrack_limit: int | None = None, size_limit: int | None = None, dfa_size_limit: int | None = None
@@ -56,10 +76,23 @@ def iter_errors(
     validate_formats: bool | None = None,
     ignore_unknown_formats: bool = True,
     retriever: RetrieverProtocol | None = None,
+    registry: Registry | None = None,
     mask: str | None = None,
     base_uri: str | None = None,
     pattern_options: PatternOptionsType | None = None,
 ) -> Iterator[ValidationError]: ...
+def evaluate(
+    schema: _SchemaT,
+    instance: Any,
+    draft: int | None = None,
+    formats: dict[str, _FormatFunc] | None = None,
+    validate_formats: bool | None = None,
+    ignore_unknown_formats: bool = True,
+    retriever: RetrieverProtocol | None = None,
+    registry: Registry | None = None,
+    base_uri: str | None = None,
+    pattern_options: PatternOptionsType | None = None,
+) -> Evaluation: ...
 
 class ReferencingError:
     message: str
@@ -195,6 +228,7 @@ class Draft4Validator:
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
     def iter_errors(self, instance: Any) -> Iterator[ValidationError]: ...
+    def evaluate(self, instance: Any) -> Evaluation: ...
 
 class Draft6Validator:
     def __init__(
@@ -212,6 +246,7 @@ class Draft6Validator:
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
     def iter_errors(self, instance: Any) -> Iterator[ValidationError]: ...
+    def evaluate(self, instance: Any) -> Evaluation: ...
 
 class Draft7Validator:
     def __init__(
@@ -229,6 +264,7 @@ class Draft7Validator:
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
     def iter_errors(self, instance: Any) -> Iterator[ValidationError]: ...
+    def evaluate(self, instance: Any) -> Evaluation: ...
 
 class Draft201909Validator:
     def __init__(
@@ -246,6 +282,7 @@ class Draft201909Validator:
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
     def iter_errors(self, instance: Any) -> Iterator[ValidationError]: ...
+    def evaluate(self, instance: Any) -> Evaluation: ...
 
 class Draft202012Validator:
     def __init__(
@@ -263,6 +300,7 @@ class Draft202012Validator:
     def is_valid(self, instance: Any) -> bool: ...
     def validate(self, instance: Any) -> None: ...
     def iter_errors(self, instance: Any) -> Iterator[ValidationError]: ...
+    def evaluate(self, instance: Any) -> Evaluation: ...
 
 def validator_for(
     schema: _SchemaT,