Add canonical contract pattern docs

adz · adz · commit 11145f2f775a · 2026-03-10T23:37:17.000+10:30
diff --git a/README.md b/README.md
@@ -14,18 +14,9 @@
 [![Last Commit](https://img.shields.io/github/last-commit/adz/CodecMapper)](https://github.com/adz/CodecMapper/commits/main)
 [![Stars](https://img.shields.io/github/stars/adz/CodecMapper?style=social)](https://github.com/adz/CodecMapper/stargazers)
 
-`CodecMapper` is a schema-first serialization library for F# focused on explicit wire contracts, symmetric encode/decode behavior, and execution that stays friendly to Native AOT and Fable-style targets.
+`CodecMapper` is a schema-first serialization library for F# focused on explicit wire contracts, symmetric encode/decode behavior, and portability to Native AOT and Fable-style targets.
 
-It is for the cases where serializer attributes and implicit conventions stop being helpful: you want the wire shape to be visible in code, you want encode and decode to stay in sync, and you want the contract to read like the data it describes.
-
-The core idea is simple: define one schema that mirrors your record shape, then compile it into reusable codecs.
-
-That sits between two common extremes:
-
-- Put serializer attributes directly on domain types and let wire concerns leak into the model.
-- Introduce separate DTOs and mapping layers so the wire contract stays explicit, but now maintain extra types and conversion code.
-
-`CodecMapper` keeps the useful part of the DTO approach, explicit contracts, without forcing a duplicate object model for every message shape. The schema is the contract, and it sits next to the data instead of behind a second translation layer.
+It is for cases where serializer attributes and implicit conventions stop being helpful. You define one schema that mirrors the wire shape, then compile it into reusable codecs.
 
 ## Why the schema feels different
 
@@ -84,16 +75,13 @@ The result is not hidden serializer behavior. It is the contract itself, written
 
 If you want the compile step to read a bit smaller in samples, the format modules also expose `Json.codec`, `Xml.codec`, `Yaml.codec`, and `KeyValue.codec` as direct aliases for `compile`.
 
-## Why this is useful
+## Why use it
 
 - The schema mirrors the data, so changes to the wire contract are visible in one place.
 - Encode and decode come from the same definition, so drift is harder to introduce accidentally.
 - `Json.compile` / `Json.codec` and `Xml.compile` / `Xml.codec` reuse the same schema instead of making you maintain separate mappings.
 - Domain refinement stays explicit through `Schema.map` and `Schema.tryMap` instead of being buried in serializer settings.
-- Versioned message and config contracts stay deliberate because the wire shape is authored directly instead of inferred from whatever the current model happens to look like.
-- Migration is easier to stage: keep the external contract stable, refine the in-memory domain behind `map` / `tryMap`, and only introduce DTOs when you genuinely need a separate transport model.
-
-See [When models evolve](#when-models-evolve) for the concrete version of this tradeoff.
+- Versioned message and config contracts stay deliberate because the wire shape is authored directly.
 
 ## Why not just use X?
 
@@ -109,35 +97,15 @@ See [When models evolve](#when-models-evolve) for the concrete version of this t
 | JSON Schema-first | Varies | Varies | External schema owned | Integrating with schema-owned systems |
 | `CodecMapper` | Strong | Strong | Authored schema contract | Explicit message/config contracts across JSON/XML |
 
-Other dimensions that matter:
-
-- Format symmetry: `CodecMapper` is centered on one contract driving both JSON and XML, while most alternatives are JSON-only or serializer-specific.
-- Model evolution: `CodecMapper` keeps contract edits explicit and supports domain refinement with `Schema.map` / `Schema.tryMap` before you reach for DTO duplication. See [When models evolve](#when-models-evolve).
-- Tooling relationship: `CodecMapper` can export JSON Schema from the authored contract and also import external JSON Schema when you are adapting to another system.
-
-If your question is "why not just use `System.Text.Json`?", the short answer is: use it when convention-based object serialization is enough. Use `CodecMapper` when you want the contract itself to be visible, reviewable, reusable, and stable across model evolution.
+Use `System.Text.Json` when convention-based object serialization is enough. Use `CodecMapper` when you want the contract itself to be visible, reviewable, reusable, and stable across model evolution.
 
 ## Where it fits well
 
 `CodecMapper` is strongest when the wire contract matters and you want it to stay explicit.
 
-For message contracts:
-
-- Define the exact payload shape once.
-- Compile it into reusable codecs.
-- Keep version changes visible in the schema instead of relying on serializer conventions.
-
-For configuration contracts:
-
-- Treat config as a real contract rather than as incidental object serialization.
-- Keep migration and versioning logic deliberate.
-- Use the schema as the stable boundary even if the in-memory domain gets richer over time.
-
-For domain models:
-
-- Keep the domain type close to the wire contract when that is useful.
-- Use `Schema.map` and `Schema.tryMap` when the runtime model should be stronger than the serialized shape.
-- Introduce separate DTOs only when the transport model genuinely needs to diverge.
+- Message contracts: define the payload shape once and keep changes visible in the schema.
+- Config contracts: treat configuration as a versioned boundary instead of incidental object serialization.
+- Domain refinement: use `Schema.map` and `Schema.tryMap` when the runtime model should be stronger than the serialized shape.
 
 ## How JSON Schema fits in
 
@@ -252,31 +220,14 @@ Compared with DTO-heavy designs, the difference is:
 - The shared sentinel now includes selected invalid and out-of-range numeric cases, so the portability story covers failure behavior as well as happy-path round-trips.
 - The contract bridge in [src/CodecMapper.Bridge](/home/adam/projects/CodecMapper/src/CodecMapper.Bridge) is `.NET`-only by design; the portable surface is the core schema/JSON/XML library in [src/CodecMapper](/home/adam/projects/CodecMapper/src/CodecMapper).
 
-## Start here
-
-- Read [Getting started](docs/GETTING_STARTED.md) for the core mental model and schema DSL.
-
-## More docs
-
-Tutorials:
-
-- [Getting started](docs/GETTING_STARTED.md)
-
-How-to guides:
-
-- [How to export JSON Schema](docs/HOW_TO_EXPORT_JSON_SCHEMA.md)
-- [How to import existing C# contracts](docs/HOW_TO_IMPORT_CSHARP_CONTRACTS.md)
-- [Configuration contracts guide](docs/CONFIG_CONTRACTS.md)
-
-Reference:
-
-- [JSON Schema support reference](docs/JSON_SCHEMA_SUPPORT.md)
-- [API docs](https://adz.github.io/CodecMapper/)
-
-Explanations:
+## Docs
 
-- [JSON Schema in CodecMapper](docs/JSON_SCHEMA_EXPLANATION.md)
-- [C# attribute bridge design](docs/CSHARP_ATTRIBUTE_BRIDGE.md)
+- Start with [Getting started](docs/GETTING_STARTED.md).
+- Copy from [How to model common contract patterns](docs/HOW_TO_MODEL_COMMON_CONTRACT_PATTERNS.md).
+- Use [Configuration contracts guide](docs/CONFIG_CONTRACTS.md) for versioned config shapes.
+- Use [How to export JSON Schema](docs/HOW_TO_EXPORT_JSON_SCHEMA.md) and [JSON Schema support reference](docs/JSON_SCHEMA_SUPPORT.md) for schema interchange.
+- Use [How to import existing C# contracts](docs/HOW_TO_IMPORT_CSHARP_CONTRACTS.md) and [C# attribute bridge design](docs/CSHARP_ATTRIBUTE_BRIDGE.md) for the bridge/facade story.
+- Browse the [API docs](https://adz.github.io/CodecMapper/).
 
 ## Benchmarks
 
diff --git a/TASKS.md b/TASKS.md
@@ -25,10 +25,7 @@ Completed rename, parser, bridge, compatibility, JSON Schema, docs, and projecti
 
 - [x] **Task 32:** Added path-aware decode diagnostics across `Json`, `Xml`, `KeyValue`, and `Yaml`, including missing-field paths, collection indices/items, and `Schema.tryMap` validation context, with matching regression coverage in the unit test suite.
 
-- [ ] **Task 33: Ship canonical pattern docs**
-  - Add copy-pasteable reference patterns for basic records, nested records, validated wrappers, versioned contracts, config contracts, JSON Schema import, and the C# bridge.
-  - Keep the examples aligned with the stable `Schema.define |> Schema.construct |> ... |> Schema.build` DSL.
-  - Make the “small explicit DSL” and compile-once workflow easy to discover from README and docs landing pages.
+- [x] **Task 33:** Added a canonical contract-pattern guide covering basic records, nested records, validated wrappers, versioned contracts, config contracts, JSON Schema import, and the C# bridge, and linked it from the README and docs landing pages so the copy-paste patterns are easy to find.
 
 - [ ] **Task 34: Keep Task 18 focused on build-time code generation**
   - Generate ordinary checked-in F# schema code rather than introducing a second runtime schema system.
diff --git a/docs/HOW_TO_MODEL_COMMON_CONTRACT_PATTERNS.md b/docs/HOW_TO_MODEL_COMMON_CONTRACT_PATTERNS.md
@@ -0,0 +1,168 @@
+# How To Model Common Contract Patterns
+
+Use this guide when you already know the kind of contract you want to model and need a copy-pasteable starting point.
+
+All examples stay on the stable authored DSL:
+
+```fsharp
+Schema.define<'T>
+|> Schema.construct ctor
+|> Schema.field ...
+|> Schema.build
+```
+
+## Basic record
+
+```fsharp
+open CodecMapper
+
+type Person = { Id: int; Name: string }
+let makePerson id name = { Id = id; Name = name }
+
+let personSchema =
+    Schema.define<Person>
+    |> Schema.construct makePerson
+    |> Schema.field "id" _.Id
+    |> Schema.field "name" _.Name
+    |> Schema.build
+
+let codec = Json.codec personSchema
+```
+
+## Nested record
+
+```fsharp
+type Address = { Street: string; City: string }
+let makeAddress street city = { Street = street; City = city }
+
+type Person = { Id: int; Name: string; Home: Address }
+let makePerson id name home = { Id = id; Name = name; Home = home }
+
+let addressSchema =
+    Schema.define<Address>
+    |> Schema.construct makeAddress
+    |> Schema.field "street" _.Street
+    |> Schema.field "city" _.City
+    |> Schema.build
+
+let personSchema =
+    Schema.define<Person>
+    |> Schema.construct makePerson
+    |> Schema.field "id" _.Id
+    |> Schema.field "name" _.Name
+    |> Schema.fieldWith "home" _.Home addressSchema
+    |> Schema.build
+```
+
+Use `Schema.fieldWith` when the child value has its own explicit schema boundary.
+
+## Validated wrapper
+
+```fsharp
+type UserId = UserId of int
+
+module UserId =
+    let create value =
+        if value > 0 then Ok(UserId value)
+        else Error "UserId must be positive"
+
+    let value (UserId value) = value
+
+type Account = { Id: UserId; Name: string }
+let makeAccount id name = { Id = id; Name = name }
+
+let userIdSchema =
+    Schema.int
+    |> Schema.tryMap UserId.create UserId.value
+
+let accountSchema =
+    Schema.define<Account>
+    |> Schema.construct makeAccount
+    |> Schema.fieldWith "id" _.Id userIdSchema
+    |> Schema.field "name" _.Name
+    |> Schema.build
+```
+
+If a wrapper rule repeats across multiple contracts, extract that `Schema.tryMap` pipeline into a named schema value and reuse it explicitly.
+
+## Versioned contract
+
+For config files or messages that evolve over time, use an explicit envelope:
+
+```fsharp
+type SettingsV2 = {
+    Version: int
+    Mode: string
+    Region: string option
+}
+
+let makeSettingsV2 version mode region =
+    { Version = version; Mode = mode; Region = region }
+
+let settingsV2Schema =
+    Schema.define<SettingsV2>
+    |> Schema.construct makeSettingsV2
+    |> Schema.fieldWith "version" _.Version (
+        Schema.int
+        |> Schema.tryMap
+            (fun value ->
+                if value > 0 then Ok value
+                else Error "version must be positive")
+            id
+    )
+    |> Schema.field "mode" _.Mode
+    |> Schema.field "region" _.Region
+    |> Schema.build
+```
+
+If you need defaults and omission policies, compose the field-policy helpers directly at the field boundary.
+
+## Config contract
+
+Compile the same authored schema into config-oriented projections when the wire surface is flat or YAML-shaped:
+
+```fsharp
+let keyValueCodec = KeyValue.codec settingsV2Schema
+let yamlCodec = Yaml.codec settingsV2Schema
+```
+
+For a larger walkthrough of versioned configuration patterns, see [Config Contracts Guide](CONFIG_CONTRACTS.md).
+
+## External JSON Schema import
+
+Use the importer when another system owns the contract and you need a deterministic receive-side shape:
+
+```fsharp
+let report =
+    JsonSchema.importWithReport """
+    {
+      "type": "object",
+      "properties": {
+        "kind": { "type": "string" },
+        "count": { "type": "integer" }
+      },
+      "required": [ "kind", "count" ]
+    }
+    """
+
+let codec = Json.codec report.Schema
+```
+
+Imported schemas target `Schema<JsonValue>`. Keep authored `Schema<'T>` values as the source of truth when you control the contract.
+
+## C# contract bridge
+
+If you already have existing C# contracts, import them through the bridge or author a new explicit schema through the C# facade:
+
+```csharp
+var userSchema =
+    CSharpSchema.Record(() => new User())
+        .Field("id", x => x.Id, (x, field) => x.Id = field)
+        .Field("display_name", x => x.DisplayName, (x, field) => x.DisplayName = field)
+        .Build();
+
+var jsonCodec = CSharpSchema.Json(userSchema);
+var yamlCodec = CSharpSchema.Yaml(userSchema);
+```
+
+For bridge import details and tradeoffs, see [How To Import Existing C# Contracts](HOW_TO_IMPORT_CSHARP_CONTRACTS.md) and [C# Attribute Bridge Design](CSHARP_ATTRIBUTE_BRIDGE.md).
diff --git a/docs/index.md b/docs/index.md
@@ -19,6 +19,8 @@ Use how-to guides when you already know what you want to accomplish.
   Generate JSON Schema documents or import external JSON Schema contracts.
 - [How To Import Existing C# Contracts](HOW_TO_IMPORT_CSHARP_CONTRACTS.md)
   Bring `System.Text.Json`, `Newtonsoft.Json`, or `DataContract` models into `CodecMapper`.
+- [How To Model Common Contract Patterns](HOW_TO_MODEL_COMMON_CONTRACT_PATTERNS.md)
+  Start from copy-pasteable patterns for basic records, validated wrappers, config contracts, and bridge scenarios.
 - [Config Contracts Guide](CONFIG_CONTRACTS.md)
   Treat application configuration as an explicit versioned wire contract.
 
