Skip to content

docs: TSchema guide is missing Union, TaggedStruct, Literal, Tuple, Boolean, and Struct options #153

@solidsnakedev

Description

@solidsnakedev

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

  • Each missing schema type has its own subsection with description and code example
  • A comparison section for Union vs Variant vs TaggedStruct with CBOR encoding differences
  • Struct options (`flatFields`, `flatInUnion`, `index`) documented with encoding examples
  • All examples use `twoslash` code fences and compile
  • Page structure: Overview → Quick Start → Core Concepts → Reference → Best Practices

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationenhancementNew feature or request

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions