corvus-v4-migration - SKILL.md Agent Skill

name: corvus-v4-migration description: > 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.

V4 to V5 Migration

Overview

V5 is a ground-up rewrite. Key architectural changes:

Namespace: Corvus.Json → Corvus.Text.Json
Types: JsonAny/JsonString/JsonNumber removed → everything is JsonElement
Parsing: ParsedValue<T>.Instance → ParsedJsonDocument<T>.RootElement
Mutation: Functional With*() → imperative Set*() with JsonWorkspace + JsonDocumentBuilder
Validation: Validate(ValidationContext, ValidationLevel) → EvaluateSchema() / EvaluateSchema(collector)
Type reduction: V5 reduces ALL simple+format types to project-local globals (V4 only reduced some)

Migration Workflow

Install the migration analyzer package:

<PackageReference Include="Corvus.Text.Json.Migration.Analyzers" Version="*" />

Migrate file-by-file, building between each file
Follow the analyzer diagnostics (CVJ001-CVJ025) — each has a code fix
For AI-assisted migration, reference the transformation rules in docs/copilot/CopilotMigrationInstructions.md (optimized for AI consumption)

Key Transformation Patterns

Parsing

// V4
using ParsedValue<MyType> parsed = ParsedValue<MyType>.Parse(json);
MyType value = parsed.Instance;

// V5
using ParsedJsonDocument<MyType> doc = ParsedJsonDocument<MyType>.Parse(json);
MyType value = doc.RootElement;

Property Access

// V4
JsonString name = person.Name;
string nameStr = (string)name;

// V5
JsonElement name = person.Name;
string nameStr = (string)name;
// Or: person.Name.GetString() for the string value

Mutation

// V4 (functional — returns new instance)
person = person.WithName("Alice");

// V5 (imperative — mutates in place)
using JsonWorkspace workspace = JsonWorkspace.Create();
using var builder = person.CreateBuilder(workspace);
builder.RootElement.Name = "Alice";

Validation

// V4
ValidationContext result = value.Validate(ValidationContext.ValidContext, ValidationLevel.Detailed);
bool isValid = result.IsValid;

// V5 — EvaluateSchema() returns bool directly
bool isValid = value.EvaluateSchema();

// V5 — with detailed results, pass a collector
var collector = new MyResultsCollector();
bool isValid = value.EvaluateSchema(collector);

Migration Analyzers (CVJ001-CVJ025)

Key diagnostics:

CVJ001: Corvus.Json namespace → Corvus.Text.Json
CVJ002: Type renames (JsonAny → JsonElement, etc.)
CVJ003-005: Parsing pattern changes
CVJ006-010: Property access changes
CVJ011-015: Validation API changes
CVJ016-020: Mutation pattern changes
CVJ021-025: Composition and enum changes

Full reference: docs/MigrationAnalyzers.md

Detailed Transformation Rules

The file docs/copilot/CopilotMigrationInstructions.md contains comprehensive, AI-optimized transformation rules organized by category:

Namespace changes
Type name mapping (all V4 types → V5 equivalents)
Parsing patterns
Property access patterns
Object creation and mutation
Array operations
String operations
Composition types (oneOf, anyOf, allOf)
Enum types
Validation patterns

Reference this file for the complete rule set — it covers every transformation scenario.

Common Pitfalls

Don't migrate all at once: Migrate file-by-file and build between each.
V5 mutation requires workspace: You can't just rename WithX to SetX — the mutation model is fundamentally different.
V5 global types: In V4, JsonString was a shared library type. In V5, each project generates its own local type. Don't try to reference V4-style shared types.

Cross-References

For the migration analyzer reference, see docs/MigrationAnalyzers.md
For AI-optimized transformation rules, see docs/copilot/CopilotMigrationInstructions.md
For the V5 mutation model, see corvus-mutable-documents
For the V5 parsing model, see corvus-parsed-documents-and-memory