Complete union and enum ergonomics

Author: adz

README.md

@@ -46,7 +46,7 @@ That is the core model of the library:
 - encode and decode come from the same definition
 - contract changes stay visible in one place
 
-That same authored path also covers explicit tagged unions and recursive case trees through `Schema.union`, `Schema.unionNamed`, and `Schema.delay`.
+That same authored path also covers explicit tagged unions, string-valued enums, message envelopes, and recursive case trees through `Schema.union`, `Schema.inlineUnion`, `Schema.envelope`, `Schema.stringEnum`, and `Schema.delay`.
 
 ## Why use it
 

TASKS.md

@@ -48,7 +48,11 @@ Completed rename, parser, bridge, compatibility, JSON Schema, docs, and projecti
   - Add one configuration-loading guide that shows layered environment/file input, explicit defaults, startup validation, and friendly failure reporting.
   - Keep the examples grounded in the existing stable DSL rather than introducing framework-specific schema systems.
 
-- [ ] **Task 39: Improve union and enum authoring ergonomics for app contracts**
+- [x] **Task 39: Improve union and enum authoring ergonomics for app contracts**
+  - Shipped the terminology cleanup from `case0` / `case1` to `tag` / `tagWith`, and aligned the public/docs wording around tagged unions and `TaggedCase`.
+  - Added `inlineUnion` / `inlineUnionNamed` for inline payload-member contracts, with readable docs plus malformed-input coverage.
+  - Added `stringEnum` / `stringEnumNamed` as first-class string-valued contracts, including JSON Schema `enum` export.
+  - Added `message`, `messageWith`, `envelope`, `envelopeNamed`, `inlineEnvelope`, and `inlineEnvelopeNamed` for common message and event contract shapes.
   - Add higher-level helpers for common string-enum, message-envelope, and public API union shapes so users do not have to hand-write projector/injector code for the most common cases.
   - Keep the explicit authored contract visible rather than hiding it behind reflection or attributes.
   - Cover JSON, XML, YAML, KeyValue, and JSON Schema export behavior for any new helpers.

docs/HOW_TO_EXPORT_JSON_SCHEMA.md

@@ -79,6 +79,8 @@ If you use `Schema.missingAsNone` inside a record field, the field is removed fr
 - objects with properties and required fields
 - nullable option shapes
 - authored tagged unions as `oneOf` object branches with `const` discriminators
+- authored inline tagged unions as `oneOf` object branches with merged payload properties
+- authored string enums as `"type":"string"` plus explicit `enum` values
 - recursive authored schemas through local `$defs` / `$ref` when the recursion is anchored with `Schema.delay`
 - mapped wrapper types as their underlying wire form
 
@@ -108,6 +110,10 @@ let schemaText = JsonSchema.generate statusSchema
 
 That exported schema uses one branch per case, with a `const` discriminator for the case name.
 
+`Schema.inlineUnion` exports the same `oneOf` structure, but merges payload properties into the same object branch as the discriminator instead of nesting them under a separate payload field.
+
+`Schema.stringEnum` exports as a string schema with an explicit `enum` list of allowed wire values.
+
 ## Export recursive authored schemas
 
 When recursion is authored explicitly with `Schema.delay`, `JsonSchema.generate` exports a local definition and references it from recursive branches:

docs/HOW_TO_MODEL_A_RECURSIVE_TAGGED_UNION.md

@@ -1,6 +1,6 @@
 # How To Model A Recursive Tagged Union
 
-Use `Schema.union` when the JSON/XML/YAML/KeyValue wire shape should be an explicit tagged contract, and use `Schema.delay` when one of those cases needs to recurse back to the same schema.
+Use `Schema.union` when the JSON/XML/YAML/KeyValue wire shape should be an explicit tagged contract with a separate payload field. Use `Schema.inlineUnion` when payload members should sit next to the discriminator at the same level. Use `Schema.delay` when one of those tags needs to recurse back to the same schema.
 
 This is the authored-schema path for recursive tree-like contracts. The wire contract stays explicit:
 
@@ -78,9 +78,11 @@ value.value.value=ok
 Use these helpers:
 
 - `tag` for a tag without payload
-- `tagWith` for a tag with exactly one payload value
+- `tagWith` for a tag with one payload value
 - `union` for the default field names `"case"` and `"value"`
 - `unionNamed` when another system expects different field names
+- `inlineUnion` when payload members should be merged next to the discriminator
+- `inlineUnionNamed` when that inline shape needs a custom discriminator name
 
 If you need the exact emitted JSON, XML, YAML, or KeyValue shapes, see [Tagged Union Wire Shape Reference](TAGGED_UNION_REFERENCE.md).
 

docs/INTRODUCTION.md

@@ -48,7 +48,8 @@ That makes it useful when:
 - the wire shape matters and should stay reviewable
 - JSON and XML should stay symmetric
 - domain refinement should be explicit with `Schema.map` or `Schema.tryMap`
-- tagged unions and recursive case trees should stay explicit in normal schema code
+- tagged unions, inline tagged unions, and recursive case trees should stay explicit in normal schema code
+- common string enums and message envelopes should still read like authored contracts rather than serializer magic
 - AOT and Fable compatibility matter more than serializer magic
 
 ## The first path to learn

docs/TAGGED_UNION_REFERENCE.md

@@ -6,6 +6,14 @@ This page is for lookup once you already know the authored tagged-union API:
 - `Schema.tagWith`
 - `Schema.union`
 - `Schema.unionNamed`
+- `Schema.inlineUnion`
+- `Schema.inlineUnionNamed`
+- `Schema.message`
+- `Schema.messageWith`
+- `Schema.envelope`
+- `Schema.envelopeNamed`
+- `Schema.inlineEnvelope`
+- `Schema.inlineEnvelopeNamed`
 - `Schema.delay`
 
 It describes the exact wire shapes currently emitted by the built-in codecs.
@@ -145,6 +153,117 @@ kind=failed
 details=boom
 ```
 
+## Inline payload fields with `inlineUnion`
+
+`Schema.inlineUnion` keeps the discriminator field, but merges payload members
+ into the same object level instead of nesting them under a separate payload
+ field.
+
+Example:
+
+```fsharp
+type CreatedData = { Id: int; Name: string }
+type Event =
+    | Ping
+    | Created of CreatedData
+
+let createdDataSchema =
+    define<CreatedData>
+    |> construct (fun id name -> { Id = id; Name = name })
+    |> field "id" _.Id
+    |> field "name" _.Name
+    |> build
+
+let eventSchema =
+    inlineUnion [
+        tag "ping" Ping ((=) Ping)
+        tagWith
+            "created"
+            (function Created payload -> Some payload | _ -> None)
+            Created
+            createdDataSchema
+    ]
+```
+
+JSON:
+
+```json
+{"case":"created","id":7,"name":"Ada"}
+```
+
+XML:
+
+```xml
+<event><case>created</case><id>7</id><name>Ada</name></event>
+```
+
+YAML:
+
+```yaml
+case: created
+id: 7
+name: Ada
+```
+
+KeyValue:
+
+```text
+case=created
+id=7
+name=Ada
+```
+
+Inline payload schemas must be object-shaped so the payload can contribute
+ named members cleanly across all formats. Record schemas are the intended
+ fit here.
+
+## Custom discriminator names with `inlineUnionNamed`
+
+`Schema.inlineUnionNamed discriminatorName` changes only the discriminator
+ field name for the inline shape.
+
+JSON:
+
+```json
+{"kind":"created","id":7,"name":"Ada"}
+```
+
+## Message and envelope helpers
+
+For message and event contracts, the helper names can read more directly than
+ the generic tagged-union names:
+
+- `message` is the same authored tag shape as `tag`
+- `messageWith` is the same authored tag shape as `tagWith`
+- `envelope` uses `"type"` / `"data"` field names by default
+- `inlineEnvelope` uses `"type"` and inlines payload members next to it
+
+Example envelope:
+
+```fsharp
+let eventSchema =
+    envelope [
+        message "ping" Ping ((=) Ping)
+        messageWith
+            "created"
+            (function Created payload -> Some payload | _ -> None)
+            Created
+            createdDataSchema
+    ]
+```
+
+JSON:
+
+```json
+{"type":"created","data":{"id":7,"name":"Ada"}}
+```
+
+Inline envelope JSON:
+
+```json
+{"type":"created","id":7,"name":"Ada"}
+```
+
 ## Recursive unions with `delay`
 
 `Schema.delay` lets a union point back to itself:
@@ -186,6 +305,9 @@ The codecs currently reject:
 - unknown case names
 - missing payload fields for payload cases
 - stray payload keys for payload-free KeyValue cases
+- unknown inline case names
+- missing inline payload fields for payload tags
+- stray inline payload fields for payload-free tags
 
 For KeyValue specifically, the payload-free case check matters because extra flattened keys would otherwise be easy to miss.
 

src/CodecMapper/Json.fs

@@ -829,6 +829,23 @@ module Json =
                         Decode = (fun src -> let struct (v, s) = Runtime.boolDecoder src in struct (box v, s))
                         MissingValue = None
                       }
+                    | StringEnum(_, tryGetName, parseName) ->
+                        {
+                            Encode =
+                                (fun w v ->
+                                    match tryGetName v with
+                                    | Some name ->
+                                        w.WriteByte(34uy)
+                                        w.WriteString(name)
+                                        w.WriteByte(34uy)
+                                    | None ->
+                                        failwithf "No string enum name matched value for type %O" schema.TargetType)
+                            Decode =
+                                (fun src ->
+                                    let struct (name, next) = Runtime.stringDecoder src
+                                    struct (parseName name, next))
+                            MissingValue = None
+                        }
                     | RawJsonValue ->
                         let writeEscapedString (writer: IByteWriter) (value: string) =
                             writer.WriteByte(34uy)
@@ -1329,6 +1346,134 @@ module Json =
                                     | _ -> failwith "Expected union object")
                             MissingValue = None
                         }
+                    | InlineUnion(discriminatorName, cases) ->
+                        let compiledCases =
+                            cases
+                            |> Array.map (fun case -> {|
+                                Case = case
+                                Codec =
+                                    case.Schema
+                                    |> Option.map (fun payloadSchema ->
+                                        if not (Schema.supportsInlinePayloadShape payloadSchema) then
+                                            failwithf
+                                                "Inline union case '%s' payload schema must be object-shaped"
+                                                case.Name
+
+                                        loop payloadSchema)
+                            |})
+
+                        let rawJsonCodec = loop (Schema.jsonValue :> ISchema)
+
+                        let encodeCaseName (writer: IByteWriter) (name: string) =
+                            writer.WriteByte(34uy)
+                            writer.WriteString(name)
+                            writer.WriteByte(34uy)
+
+                        let encodeInlinePayload (codec: CompiledCodec) (fieldValue: obj) =
+                            let writer = ResizableBuffer.Create(defaultSerializeBufferCapacity)
+
+                            try
+                                codec.Encode writer fieldValue
+
+                                let struct (rawPayload, rest) = rawJsonCodec.Decode(ByteSource(writer.InternalData, 0))
+                                let rest = Runtime.skipWhitespace rest
+
+                                if rest.Offset <> writer.InternalCount then
+                                    failwith "Inline union payload had trailing JSON content"
+
+                                match unbox<JsonValue> rawPayload with
+                                | JObject properties -> properties
+                                | _ -> failwith "Inline union payload schema must encode as a JSON object"
+                            finally
+                                writer.Release()
+
+                        let decodeInlinePayload (codec: CompiledCodec) (properties: (string * JsonValue) list) =
+                            let payloadObject = JObject properties
+                            let writer = ResizableBuffer.Create(defaultSerializeBufferCapacity)
+
+                            try
+                                rawJsonCodec.Encode writer (box payloadObject)
+                                let struct (fieldValue, rest) = codec.Decode(ByteSource(writer.InternalData, 0))
+                                let rest = Runtime.skipWhitespace rest
+
+                                if rest.Offset <> writer.InternalCount then
+                                    failwith "Inline union payload had trailing JSON content"
+
+                                fieldValue
+                            finally
+                                writer.Release()
+
+                        {
+                            Encode =
+                                (fun writer value ->
+                                    match
+                                        compiledCases
+                                        |> Array.tryPick (fun compiled ->
+                                            compiled.Case.TryGetValue value
+                                            |> Option.map (fun fieldValue -> compiled, fieldValue))
+                                    with
+                                    | Some(compiled, fieldValue) ->
+                                        let payloadProperties =
+                                            match compiled.Codec with
+                                            | Some codec -> encodeInlinePayload codec fieldValue
+                                            | None -> []
+
+                                        writer.WriteByte(123uy)
+                                        encodeCaseName writer discriminatorName
+                                        writer.WriteByte(58uy)
+                                        encodeCaseName writer compiled.Case.Name
+
+                                        for propertyName, propertyValue in payloadProperties do
+                                            if propertyName = discriminatorName then
+                                                failwithf
+                                                    "Inline union case '%s' payload cannot reuse discriminator field '%s'"
+                                                    compiled.Case.Name
+                                                    discriminatorName
+
+                                            writer.WriteByte(44uy)
+                                            encodeCaseName writer propertyName
+                                            writer.WriteByte(58uy)
+                                            rawJsonCodec.Encode writer (box propertyValue)
+
+                                        writer.WriteByte(125uy)
+                                    | None ->
+                                        failwithf "No union case matched value for type %O" schema.TargetType)
+                            Decode =
+                                (fun src ->
+                                    let struct (rawValue, next) = Runtime.jsonValueDecoder src
+
+                                    match rawValue with
+                                    | JObject properties ->
+                                        let tryFind name =
+                                            properties |> List.tryFind (fun (key, _) -> key = name) |> Option.map snd
+
+                                        let caseName =
+                                            match tryFind discriminatorName with
+                                            | Some(JString value) -> value
+                                            | Some _ -> failwithf "Union discriminator '%s' must be a string" discriminatorName
+                                            | None -> failwithf "Missing union discriminator '%s'" discriminatorName
+
+                                        let payloadProperties =
+                                            properties |> List.filter (fun (key, _) -> key <> discriminatorName)
+
+                                        match compiledCases |> Array.tryFind (fun compiled -> compiled.Case.Name = caseName) with
+                                        | Some compiled ->
+                                            match compiled.Codec with
+                                            | None ->
+                                                if List.isEmpty payloadProperties then
+                                                    struct (compiled.Case.Construct None, next)
+                                                else
+                                                    failwithf
+                                                        "Union case '%s' does not accept payload fields alongside '%s'"
+                                                        caseName
+                                                        discriminatorName
+                                            | Some codec ->
+                                                let fieldValue = decodeInlinePayload codec payloadProperties
+                                                struct (compiled.Case.Construct(Some fieldValue), next)
+                                        | None -> failwithf "Unknown union case '%s'" caseName
+                                    | _ -> failwith "Expected union object")
+                            MissingValue = None
+                        }
                     | Delay factory -> loop (factory ())
                     | List innerSchema ->
                         let innerCodec = loop innerSchema