IntersectMBO / IntersectMBO/evolution-sdk

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

Open
#153 0 comments 0 reactions 0 assignees View on GitHub
documentation enhancement
Dominant language
TypeScript
Stars
22
Forks
30
Avg merge
5h 29m
Merged PRs (30d)
12

Description

## 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

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.