feat: evaluate() top-level function for convenient access to structured validation output

Signed-off-by: Dmitry Dygalo <[email protected]>

Author: Stranger6667

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## [Unreleased]
 
+### Added
+
+- `evaluate()` top-level function for convenient access to structured validation output.
+
 ### Changed
 
 - **BREAKING**: `ValidationError` fields are private; use `instance()`, `kind()`, `instance_path()`, and `schema_path()` instead of accessing struct fields directly.

crates/jsonschema/benches/jsonschema.rs

@@ -18,9 +18,7 @@ mod bench {
             BenchmarkId::new("is_valid", name),
             instance,
             |b, instance| {
-                b.iter(|| {
-                    let _ = validator.is_valid(instance);
-                });
+                b.iter(|| black_box(validator.is_valid(instance)));
             },
         );
     }
@@ -31,9 +29,7 @@ mod bench {
             BenchmarkId::new("validate", name),
             instance,
             |b, instance| {
-                b.iter(|| {
-                    let _ = validator.validate(instance);
-                });
+                b.iter(|| black_box(validator.validate(instance)));
             },
         );
     }

crates/jsonschema/src/lib.rs

@@ -976,6 +976,33 @@ pub fn validate<'i>(schema: &Value, instance: &'i Value) -> Result<(), Validatio
         .validate(instance)
 }
 
+/// Evaluate `instance` against `schema` and return structured validation output. Draft is detected automatically.
+///
+/// Returns an [`Evaluation`] containing detailed validation results in JSON Schema Output v1 format,
+/// including annotations and errors across the entire validation tree.
+///
+/// # Examples
+///
+/// ```rust
+/// use serde_json::json;
+///
+/// let schema = json!({"type": "string", "minLength": 3});
+/// let instance = json!("foo");
+/// let evaluation = jsonschema::evaluate(&schema, &instance);
+/// assert!(evaluation.flag().valid);
+/// ```
+///
+/// # Panics
+///
+/// This function panics if an invalid schema is passed.
+#[must_use]
+#[inline]
+pub fn evaluate(schema: &Value, instance: &Value) -> Evaluation {
+    validator_for(schema)
+        .expect("Invalid schema")
+        .evaluate(instance)
+}
+
 /// Create a validator for the input schema with automatic draft detection and default options.
 ///
 /// # Examples
@@ -2724,6 +2751,35 @@ mod tests {
         assert!(validate_fn(&schema, &invalid_instance).is_err());
     }
 
+    #[test]
+    fn test_evaluate() {
+        let schema = json!({
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "age": {"type": "integer", "minimum": 0}
+            },
+            "required": ["name"]
+        });
+
+        let valid_instance = json!({
+            "name": "John Doe",
+            "age": 30
+        });
+
+        let invalid_instance = json!({
+            "age": -5
+        });
+
+        let valid_eval = crate::evaluate(&schema, &valid_instance);
+        assert!(valid_eval.flag().valid);
+
+        let invalid_eval = crate::evaluate(&schema, &invalid_instance);
+        assert!(!invalid_eval.flag().valid);
+        let errors: Vec<_> = invalid_eval.iter_errors().collect();
+        assert!(!errors.is_empty());
+    }
+
     #[test_case(crate::meta::validate, crate::meta::is_valid ; "autodetect")]
     #[test_case(crate::draft4::meta::validate, crate::draft4::meta::is_valid ; "draft4")]
     #[test_case(crate::draft6::meta::validate, crate::draft6::meta::is_valid ; "draft6")]