JsonSchemaResultsCollector

Definition

Namespace: Corvus.Text.Json
Assembly: Corvus.Text.Json.dll
Source: JsonSchemaResultsCollector.cs

Collects and manages results from JSON schema validation operations with high-performance memory management, stack-based evaluation tracking, and configurable verbosity levels.

public sealed class JsonSchemaResultsCollector : IJsonSchemaResultsCollector, IDisposable

Remarks

Core Architecture: The JsonSchemaResultsCollector provides a sophisticated result collection system optimized for JSON schema validation workflows. It manages multiple evaluation paths simultaneously and supports hierarchical validation contexts through a stack-based approach. - Multi-Path Tracking: Maintains evaluation, schema, and document paths separately for precise error reporting - Stack-Based Contexts: Hierarchical validation contexts with proper nesting and cleanup - Pooled Memory Management: Thread-local pooling for high-throughput validation scenarios - Configurable Verbosity: Three levels from basic failures to comprehensive validation logs - UTF-8 Optimized: Direct UTF-8 processing for reduced encoding overhead Lifecycle Management: The collector follows a strict lifecycle pattern designed for efficient resource management: - Creation: Use Create for pooled instances or CreateUnrented for standalone use - Configuration: Set verbosity level and capacity estimates during creation - Collection: Use context methods to track validation hierarchy and results - Enumeration: Access results through EnumerateResults after validation completion - Disposal: Always dispose to return pooled resources and clear sensitive data Memory Management: Designed for high-performance scenarios with minimal garbage collection pressure: - Pooled Instances: Thread-local caching reduces allocation overhead in high-throughput scenarios - ArrayPool Integration: Uses shared array pools for internal buffers with proper cleanup - Stack Allocation: ValueStack structures minimize heap allocations for context management - Capacity Estimation: Pre-sizing based on expected result count prevents reallocations - Security Clearing: Sensitive data is explicitly cleared on disposal Performance Characteristics: - Time Complexity: O(1) result insertion, O(n) enumeration where n is result count - Space Complexity: O(d + r) where d is max validation depth, r is result count - Memory Overhead: ~32 bytes per path segment, ~128 bytes per message (configurable) - Thread Safety: Not thread-safe; use separate instances per thread Verbosity Level Guidance: - Basic: Failure messages only - minimal overhead, use for production validation - Detailed: Failure messages with detailed context - moderate overhead, use for debugging - Verbose: All validation events including successes - high overhead, use for comprehensive analysis Usage Patterns: - High-Throughput: Use pooled instances with accurate capacity estimation - One-Off Validation: Use unpooled instances for occasional validation - Debugging: Use Detailed or Verbose levels with comprehensive result analysis - Production: Use Basic level with pooled instances for optimal performance Context Hierarchy: The collector maintains a stack-based context system where each validation step creates a child context. Contexts must be completed in reverse order (stack discipline) using either commit or pop operations. This enables precise error location tracking and efficient resource cleanup. Thread Safety: This class is not thread-safe. Each thread must use its own collector instance. The internal thread-local pooling system handles concurrent access to the cache safely.

Inheritance

Object → JsonSchemaResultsCollector

Implements

IJsonSchemaResultsCollector, IDisposable

Methods

Example

Basic validation with pooled collector: csharp using var collector = JsonSchemaResultsCollector.Create(JsonSchemaResultsLevel.Basic, estimatedCapacity: 50); // Perform validation operations... int context = collector.BeginChildContext(0, evaluationPath, schemaPath, documentPath); collector.CommitChildContext(context, parentMatch: true, childMatch: false, messageProvider); // Enumerate results foreach (var result in collector.EnumerateResults()) { if (!result.IsMatch) { Console.WriteLine($"Validation failed: {result.GetMessageText()}"); Console.WriteLine($" Location: {result.GetDocumentEvaluationLocationText()}"); } }

Applies To