For agents: start with the agent guide. Every page is Markdown by default; add Accept: text/html for HTML.

Schemas define the boundary

Schema defines accepted values, runtime checks, and associated TypeScript types. Decoding checks external input and produces an application value. Encoding produces its external representation. A codec connects these two representations.¶

Define the values the application accepts before writing the handler. Decode unknown input at the boundary. Encode results through the declared output schema.¶

Use one model for types and runtime checks

Schema.Struct describes a record. Schema.Literals describes a fixed set of alternatives. A schema’s Type describes its decoded value; Encoded describes its external representation. Those representations can differ when a codec transforms values.¶

const ContentKind = Schema.Literals(["law", "skill", "lore"]);

export const SearchMatch = Schema.Struct({
  description: Schema.String,
  digest: Schema.String,
  excerpt: Schema.String,
  id: Schema.String,
  kind: ContentKind,
  routePath: Schema.String,
  score: Schema.Finite,
  title: Schema.String,
});

Content kinds have three accepted values. A match must carry the declared fields and a finite score.¶

Derive the TypeScript type from the schema rather than maintaining a second interface. Use Schema.Union when accepted alternatives have different shapes, including tagged failures.¶

Put the schemas in the contract

A contract declares an action’s input, output, and failures. The file-inspection contract names its input, result, and failure.¶

export const inspectFileContract = defineContract("inspectFile", {
  annotations: { idempotent: true, readOnly: true },
  description: "Count bytes, characters, words, and lines in a file",
  failure: FileStatsError,
  input: Schema.Struct({
    path: Schema.String.annotate({ description: "File to inspect" }),
  }),
  output: FileStatsSchema,
});

The schemas check values at runtime.¶

Decode before dispatch

Schema.decodeUnknownEffect accepts unknown input and keeps decoding failures in the Effect error channel. Our code-mode invoker calls the handler only after decoding succeeds.¶

      return Schema.decodeUnknownEffect(item.contract.input)(input).pipe(
        Effect.matchEffect({
          onFailure: (error) =>
            Effect.succeed(invokeFailure("InvalidInput", error.message)),
          onSuccess: (decoded) =>
            run(decoded).pipe(
              Effect.provideContext(context),
              Effect.matchEffect({
                onFailure: (error) =>

Rejected input becomes InvalidInput. The domain handler receives the decoded value after validation.¶

The same invoker uses Schema.encodeUnknownEffect for declared outputs and failures. For an already-typed value, Schema.encodeEffect supplies the typed encoding API. JSON serialization alone does not check whether a result satisfies its contract.¶

A schema states what a value means

The interest contract separates contact consent from sharing consent. Accepting contact does not authorize sharing. Its answer fields are bounded strings.¶

AbuseVerdictSchema describes a hold flag, a finite score between zero and one, and signal names. The AbuseVerdict type derives from that schema. These are domain decisions; Schema does not choose them for us.¶

A generated input also does not supply a behavior assertion. Property tests¹⁸ still need an independent rule that those values must satisfy.¶

Common wrong approach

A type assertion changes what TypeScript believes. It does not reject a malformed external value. Decode at the boundary instead of casting it into a domain type.¶

Hand-written JSON parsing followed by a copied interface creates two models that can drift. Use the schema’s decoding and encoding APIs. Report malformed input separately from an expected domain refusal³⁶.¶

Effect idiom and house rule

• Schema defines runtime decoding, encoding, and the associated TypeScript types.¶
• In rat-stack, one capability contract²¹ supplies schemas to every interface projection.¶
• rat-stack also uses capabilities and a bodyless HTTP 400 response for malformed input.¶

See also: one schema, three surfaces²³, OpenAPI refusals¹⁵, services¹⁶, and testing²².¶

Last changed 2026-10-07 in f1a00f2. Source on GitHub. Change log.