Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

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

Open
  • Is something wrong?
#153 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
52/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Stale
Tech stack
typescript
Domain
documentation

Research direction

Start with docs/content/docs/encoding/tschema.mdx and its existing TSchema examples, then map each missing construct and option to a subsection. Add compiling twoslash examples, explain the Union, Variant, and TaggedStruct CBOR differences, and finish with the requested page structure and best-practices guidance.

Written by the indexing model from the issue text.

Description

documentation enhancement

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
Dominant language
TypeScript
Stars
22
Forks
31
Avg merge
3d 4h
Merged PRs (30d)
27

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from IntersectMBO/evolution-sdk

All issues in IntersectMBO/evolution-sdk

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.