Corvus.JsonSchema

Generate strongly-typed C# from JSON Schema using the Roslyn source generator or the corvusjson CLI tool. Covers the JsonSchemaTypeGenerator attribute, CLI options, naming heuristics, AdditionalFiles registration, config file format, MSBuild properties, and troubleshooting generated output. USE FOR: generating types from schemas, configuring the source generator or CLI tool, understanding naming heuristics, inspecting generated output, troubleshooting generation issues. DO NOT USE FOR: modifying the generator internals (use corvus-keywords-and-validation), running benchmarks (use corvus-benchmarks).

Convert between YAML 1.2 and JSON using the high-performance ref struct tokenizer. Covers the two packages (Corvus.Text.Json.Yaml for full integration, Corvus.Yaml.SystemTextJson for System.Text.Json-only), YAML→JSON and JSON→YAML conversion, schema modes, anchor/alias support, multi-document streams, Utf8YamlWriter, and 100% yaml-test-suite JSON-testable conformance (373 of 402 tests). USE FOR: YAML-to-JSON conversion, JSON-to-YAML conversion, understanding the tokenizer architecture, troubleshooting YAML parsing issues. DO NOT USE FOR: JSON-only workflows with no YAML involvement.

Regenerate JSON Schema test classes from the JSON-Schema-Test-Suite git submodule. Covers the update-json-schema-test-suite.ps1 master script, the V5 test generator (Corvus.JsonSchemaTestSuite.CodeGenerator), exclusion configuration, and output directory structure. USE FOR: updating the test suite submodule, regenerating test classes after submodule or generator changes, understanding the test infrastructure. DO NOT USE FOR: running existing tests (use corvus-build-and-test), writing manual tests.

Implement OpenAPI server handlers using Corvus.Text.Json generated types. Covers the workspace-owned lifetime model, the Read/ReadMutable store pattern, builder pattern for responses, From<T>() for zero-copy cross-namespace values, TryX out-parameter pattern for lookups, EnumerateArray() iteration, and the two-hop cast requirement for Mutable→Source. USE FOR: implementing handler methods for generated IApi*Handler interfaces, reading/writing blob stores with correct document lifetime, building response bodies, avoiding memory leaks and use-after-free. DO NOT USE FOR: code generation itself (use corvus-codegen), mutable document manipulation details (use corvus-mutable-documents), parsing standalone documents (use corvus-parsed-documents-and-memory).

Understand and work with the Roslyn analyzers shipped with Corvus.Text.Json. Covers 10 production diagnostics (CTJ001-CTJ010) for correct and performant V5 code, the CTJ-NAV refactoring for navigating from types to JSON Schema definitions, and the analyzer packaging convention. USE FOR: understanding what each analyzer checks, writing code that passes analyzer checks, packaging analyzer DLLs. DO NOT USE FOR: the 25 migration analyzers (use corvus-v4-migration for the workflow and CVJ001-CVJ025 reference).

Run, interpret, and maintain BenchmarkDotNet benchmarks for JSON Schema validation and query languages. Covers the B/ (frozen baseline) vs C/ (current) directory convention, stale Job-* cleanup, --buildTimeout, result file polling, regenerating C/ models after codegen changes, and JSONata/JMESPath/JsonLogic/JSONPath benchmarks. USE FOR: running benchmarks, interpreting results, regenerating benchmark models, troubleshooting BDN issues, adding new benchmark schemas. DO NOT USE FOR: general .NET performance analysis (use the analyzing-dotnet-performance skill).

Test Corvus.JsonSchema against the JSON Schema Test Suite using Bowtie, the cross-implementation meta-validator. Covers local package building, configuring a local Bowtie checkout to use locally-built packages, running the test suite via Docker/Podman containers, interpreting results, the iteration loop, and teardown. Both V4 (dotnet-corvus-jsonschema-v4engine) and V5 (dotnet-corvus-jsonschema-v5engine) implementations are supported. USE FOR: running Bowtie conformance suites against local changes, setting up the local development loop, interpreting Bowtie failure reports, testing schema dialect compliance (Draft 4 through 2020-12). DO NOT USE FOR: running the in-repo MSTest test suite (use corvus-build-and-test), regenerating test classes from the submodule (use corvus-test-suite-regeneration).

Write allocation-efficient buffer code in Corvus.JsonSchema using the codebase's established three-tier pooling pattern: stackalloc → ArrayPool → ThreadStatic caches. Covers threshold constants, the rent/return pattern, UTF-8-first processing, thread-local writer and workspace caches, and PooledByteBufferWriter. USE FOR: writing any code that needs temporary byte/char buffers, adding new pooled caches, working with UTF-8 data, avoiding heap allocation on hot paths. DO NOT USE FOR: choosing which ref-struct collection to use (use corvus-low-alloc-data-structures), document model internals (use corvus-parsed-documents-and-memory).

Build, test, and run the Corvus.JsonSchema solution correctly. Covers multi-targeting (net9.0/net10.0/net481/netstandard2.0), mandatory test category filters, solution file selection, running specific test classes or methods, writing new tests, and diagnosing common build/test failures. USE FOR: building the solution, running tests, writing new test files, diagnosing test failures, understanding TFM targeting, finding the right test project for a feature area. DO NOT USE FOR: benchmark execution (use corvus-benchmarks), code generation (use corvus-codegen), test suite regeneration (use corvus-test-suite-regeneration).

Build, serve, and maintain the Corvus.Text.Json documentation website and the six Blazor WASM playgrounds (JSON Schema, JSONata, JMESPath, JsonLogic, JSONPath, YAML). Covers the 12-step build.ps1 pipeline (steps 0-11, with sub-steps), generated vs hand-authored file boundaries, incremental rebuild patterns, XmlDocToMarkdown API doc generation, SCSS/JS asset compilation, and playground startup with Monaco editor. USE FOR: building or previewing the docs site, modifying website content or theme, updating API documentation, running or modifying playgrounds. DO NOT USE FOR: library development (use other skills).

Translate ECMAScript 262 /u mode regular expressions to .NET regex patterns. Covers semantic differences between ECMAScript and .NET regex engines, supplementary code point handling via surrogate pairs, Unicode property escapes, backreference conditionals, character class strategies, and strict /u mode validation. USE FOR: understanding regex translation in generated validation code, debugging pattern matching issues in JSON Schema pattern/patternProperties, extending regex support for new Unicode properties or constructs. DO NOT USE FOR: general .NET regex usage, writing custom regex patterns.

Implement and extend JSON Schema keywords and validation handlers in the Corvus code generation system. Covers the IKeyword interface, behavioral marker interfaces, vocabulary registration, draft-specific keyword variations (Draft 4 through 2020-12), validation handler priorities, custom keyword extension points, and the TypeDeclaration data structure. USE FOR: adding new JSON Schema keywords, modifying validation behavior, understanding keyword evolution across drafts, extending the code generation engine, understanding vocabularies. DO NOT USE FOR: using generated types (use corvus-codegen), standalone evaluator internals (use corvus-standalone-evaluator).

Use and extend the custom low-allocation data structures in Corvus.JsonSchema. Covers ref-struct collections (Utf8KeyHashSet, UniqueItemsHashSet, ValueListBuilder, ValueStringBuilder, Utf8ValueStringBuilder, BitStack, Sequence), SIMD scanning patterns, bit manipulation tricks, and happy-path optimisations like lazy error messages. USE FOR: choosing which stack-allocated collection to use, writing new ref-struct types, adding SIMD-accelerated code paths, understanding branchless techniques, writing validation code that avoids allocation on success. DO NOT USE FOR: basic buffer allocation patterns (use corvus-buffer-and-pooling), document model (use corvus-parsed-documents-and-memory).

Create and manipulate mutable JSON documents using JsonWorkspace, JsonDocumentBuilder, and the builder pattern. Covers workspace creation (rented vs unrented), the canonical parse-build-mutate-serialize pattern, deep property mutation, array operations, cloning, and RFC 6902 JSON Patch via PatchBuilder. USE FOR: writing code that creates or modifies JSON, understanding the V5 mutation model, implementing JSON Patch operations, working with JsonWorkspace. DO NOT USE FOR: read-only parsing (use corvus-parsed-documents-and-memory), V4 mutation patterns (use corvus-v4-migration).

Understand and work with the Corvus.Text.Json numeric type system including parsed components, BigNumber arbitrary-precision decimal, format-based type selection, and precision-preserving validation. USE FOR: working with JSON numbers in Corvus types, understanding format validation for numeric schemas, implementing numeric operations, choosing between BigNumber and standard .NET numeric types. DO NOT USE FOR: general JSON parsing (use corvus-parsed-documents-and-memory).

Parse JSON into pooled-memory documents and manage memory correctly in the Corvus.Text.Json library. Covers ParsedJsonDocument, IJsonDocument, the IJsonElement CRTP pattern, the stackalloc/ArrayPool rent pattern with JsonConstants thresholds, UTF-8 transcoding helpers, and disposal requirements. USE FOR: parsing JSON, understanding the memory model, writing allocation-efficient code, handling UTF-8/UTF-16 transcoding, understanding the IJsonElement type system. DO NOT USE FOR: mutable documents (use corvus-mutable-documents), code generation (use corvus-codegen).

Work with JSONata, JMESPath, JsonLogic, and JSONPath query and transformation languages. Each has runtime (interpreted) and code-generated evaluation modes plus Roslyn source generators. Covers the JSONata evaluator API, JMESPath Search(), JsonLogic rule engine, JSONPath Query/QueryNodes with custom function extensions, conformance test suites, code generation for all four, and performance characteristics. USE FOR: evaluating queries and transforms, generating optimized evaluators, running conformance tests, understanding the dual (runtime + codegen) architecture. DO NOT USE FOR: JSON Schema validation (use corvus-keywords-and-validation or corvus-standalone-evaluator).

Generate and use standalone schema evaluators for validation-only and annotation collection scenarios without full type generation. Covers the two-pass generation architecture, SubschemaInfo, property matcher infrastructure (hash-based dispatch), bitmask tracking, regex pattern classification and optimization, discriminator fast paths, path provider fields, and the annotation extraction pipeline. USE FOR: generating evaluator-only code, collecting annotations from schema validation, understanding the evaluator internals, debugging validation behavior. DO NOT USE FOR: full type generation (use corvus-codegen), modifying keywords (use corvus-keywords-and-validation).

Migrate code from Corvus.Json V4 to Corvus.Text.Json V5. Covers namespace and type renames, parsing pattern changes, the mutation model shift from functional With*() to imperative Set*() with workspace/builder, validation API changes, composition type changes, migration analyzer diagnostics (CVJ001-CVJ025), and the Copilot-assisted migration workflow. USE FOR: migrating V4 consumer code to V5, understanding API differences between V4 and V5, using migration analyzers and code fixes. DO NOT USE FOR: general V5 development (use other skills), modifying the V4 engine itself.

Resolve Roslyn metadata references for dynamic compilation in cross-OS CI scenarios (build on Ubuntu, test on Windows net481). Covers the three-phase reference resolution pattern (DependencyContext → AppDomain replacement → directory scan + transitive), the facade vs GAC mscorlib problem, all six affected sites, and local WSL testing. USE FOR: modifying any code that calls CSharpCompilation.Create with dynamically resolved MetadataReferences, adding new dynamic compilation sites, debugging CS0012 or CS1705 errors in CodeGenConformanceFixture or DynamicCompiler tests. DO NOT USE FOR: source generator development (use corvus-codegen), Roslyn analyzer authoring (use corvus-analyzers).

Replace Func<> and Action<> with custom delegate types when any parameter or return type is a ref struct (Span<T>, ReadOnlySpan<T>, etc.). Ref structs cannot appear as generic type arguments, so Func<ReadOnlySpan<byte>, bool> is a compile error. The fix is a named delegate. USE FOR: writing public APIs that accept callbacks involving spans, storing span-accepting lambdas in fields, wrapping IJsonPathFunction or similar interfaces with delegate-based factories. DO NOT USE FOR: APIs where all parameters are regular (non-ref-struct) types — plain Func<>/Action<> is fine there.

Review and update copilot instructions and skill files after completing a piece of work. Covers when to review, what to check, common failure modes, and the verification process. USE FOR: post-work skill review, periodic instruction audits, adding new skills, fixing skill drift after codebase changes. DO NOT USE FOR: writing library code (use the relevant domain skill), verifying documentation code samples (use the code sample verification section in copilot-instructions.md).