Problem
The TSchema guide page at `docs/content/docs/encoding/tschema.mdx` covers basic schemas (ByteArray, Integer, Struct, Variant, Array, Map, UndefinedOr) and codec creation, but is missing documentation for several important constructs and usage areas.
Missing Sections
Union — `TSchema.Union()` is the lower-level primitive that `Variant`, `TaggedStruct`, and other helpers are all built on. It is never documented on its own or explained in terms of when you'd reach for it directly over the helpers.
TaggedStruct — `TSchema.TaggedStruct()` creates discriminated unions with an explicit tag field (`_tag`, `type`, `kind`, `variant`). Auto-detection of tag fields inside `Union` members is a key feature that is not mentioned anywhere in the guide.
Literal — `TSchema.Literal()` for enum-style constructors with no fields. The `LiteralOptions` interface (`index`, `flatInUnion`) is not covered.
Tuple — `TSchema.Tuple()` for fixed-length positional data. No mention in the guide.
Boolean — `TSchema.Boolean` for Plutus-style booleans (Constr 0 = False, Constr 1 = True).
NullOr vs UndefinedOr — The guide only covers `UndefinedOr`. `NullOr` and the decision between them is absent.
Struct options — `flatFields`, `flatInUnion`, and `index` options on `TSchema.Struct()` are undocumented. These are critical for correctly matching Aiken on-chain encoding.
Variant vs Union vs TaggedStruct — No comparison section explaining when to use each and how they differ in CBOR encoding:
- Variant: wrapper-object shape (`{ VerificationKey: { hash } }`) — single-level CBOR
- TaggedStruct: discriminator-field shape (`{ _tag: "Mint", amount }`) — tag stripped in CBOR
- Union: raw position-based — constructor index determines variant
Schema utilities — `compose`, `filter`, `equivalence`, and `is` are exported but absent from the guide.
Acceptance Criteria
Problem
The TSchema guide page at `docs/content/docs/encoding/tschema.mdx` covers basic schemas (ByteArray, Integer, Struct, Variant, Array, Map, UndefinedOr) and codec creation, but is missing documentation for several important constructs and usage areas.
Missing Sections
Union — `TSchema.Union()` is the lower-level primitive that `Variant`, `TaggedStruct`, and other helpers are all built on. It is never documented on its own or explained in terms of when you'd reach for it directly over the helpers.
TaggedStruct — `TSchema.TaggedStruct()` creates discriminated unions with an explicit tag field (`_tag`, `type`, `kind`, `variant`). Auto-detection of tag fields inside `Union` members is a key feature that is not mentioned anywhere in the guide.
Literal — `TSchema.Literal()` for enum-style constructors with no fields. The `LiteralOptions` interface (`index`, `flatInUnion`) is not covered.
Tuple — `TSchema.Tuple()` for fixed-length positional data. No mention in the guide.
Boolean — `TSchema.Boolean` for Plutus-style booleans (Constr 0 = False, Constr 1 = True).
NullOr vs UndefinedOr — The guide only covers `UndefinedOr`. `NullOr` and the decision between them is absent.
Struct options — `flatFields`, `flatInUnion`, and `index` options on `TSchema.Struct()` are undocumented. These are critical for correctly matching Aiken on-chain encoding.
Variant vs Union vs TaggedStruct — No comparison section explaining when to use each and how they differ in CBOR encoding:
Schema utilities — `compose`, `filter`, `equivalence`, and `is` are exported but absent from the guide.
Acceptance Criteria