Canonical Codecs

A schema describes a domain value and the input that decodes into it. Sometimes you need another representation of the same value, such as JSON for an API or a tree of strings for a form.

A canonical codec derives that representation from the schema. The derived codec keeps the original decoded Type and gives it a format-specific encoded side.

Derivation builds a new codec. It does not encode or decode a value by itself. Pass the result to the usual Schema parsing functions, such as Schema.encodeSync or Schema.decodeUnknownSync.

JSON

Schema.toCodecJson derives a codec whose encoded side contains only JSON values. Effect walks nested structs, tuples, arrays, unions, and suspended schemas. Built-in schemas define representations for values such as Date, URL, Option, and BigInt.

Built-in schemas provide these mappings. For custom declarations that need a JSON conversion, define a toCodecJson or toCodec annotation, as described below.

Example (Deriving JSON for a Nested Schema)

1
import { Schema } from "effect"
2

3
const Event = Schema.Struct({
4
  createdAt: Schema.Date,
5
  links: Schema.Array(Schema.URL),
6
})
7

8
const JsonEvent = Schema.toCodecJson(Event)
9

10
const encoded = Schema.encodeSync(JsonEvent)({
11
  createdAt: new Date("2025-01-01T00:00:00.000Z"),
12
  links: [new URL("https://effect.website/docs/")],
13
})
14

15
encoded // => { createdAt: "2025-01-01T00:00:00.000Z", links: ["https://effect.website/docs/"] }
16

17
const decoded = Schema.decodeUnknownSync(JsonEvent)(encoded)
18
decoded.createdAt instanceof Date // => true
19
decoded.links[0] instanceof URL // => true

The traversal respects an explicit encoding already present in the schema. For example, if a Date first encodes to epoch milliseconds, the JSON codec keeps that number representation instead of replacing it with the built-in ISO date string.

StringTree

Schema.toCodecStringTree preserves arrays and objects but converts their leaf values to strings. Its encoded type is:

type StringTree =
  | string
  | undefined
  | { readonly [key: string]: StringTree }
  | ReadonlyArray<StringTree>

Example (Encoding Structured Values as Strings)

1
import { Schema } from "effect"
2

3
const Search = Schema.Struct({
4
  page: Schema.Int,
5
  exact: Schema.Boolean,
6
  tags: Schema.Array(Schema.String),
7
})
8

9
const StringTreeSearch = Schema.toCodecStringTree(Search)
10

11
Schema.encodeSync(StringTreeSearch)({
12
  page: 2,
13
  exact: true,
14
  tags: ["schema", "effect"],
15
}) // => { page: "2", exact: "true", tags: ["schema", "effect"] }
16

17
Schema.decodeUnknownSync(StringTreeSearch)({
18
  page: "2",
19
  exact: "true",
20
  tags: ["schema", "effect"],
21
}) // => { page: 2, exact: true, tags: ["schema", "effect"] }

Query parameters and form data are common uses for this representation because they encode numbers and booleans as strings.

Iso

Schema.toCodecIso derives a codec between a schema’s decoded Type and its Iso representation. The Optic.ts module performs structural updates on plain JavaScript objects and arrays. The codec converts other data types to one of those shapes before an optic traverses or updates them, then converts the result back. For example, a class schema’s Iso is a plain object containing the class fields.

Example (Converting a Class to Its Iso Representation)

1
import { Schema } from "effect"
2

3
class Person extends Schema.Class<Person>("Person")({
4
  name: Schema.String,
5
  age: Schema.Number,
6
}) {}
7

8
const PersonIso = Schema.toCodecIso(Person)
9
const person = new Person({ name: "Ada", age: 36 })
10

11
const encoded = Schema.encodeSync(PersonIso)(person)
12
encoded // => { name: "Ada", age: 36 }
13

14
Schema.decodeUnknownSync(PersonIso)(encoded) instanceof Person // => true

Custom declarations

Declarations are opaque to the recursive traversal. Add a codec annotation to tell Effect which structural representation to use.

Use a format-specific annotation when formats need different representations. Use toCodec for a representation shared by every derivation. A toCodecJson or toCodecStringTree callback may return undefined to mark the declaration as already canonical for that format.

The next example gives Point a JSON tuple representation. StringTree derivation can reuse that JSON link, then recursively convert the numbers to strings.

Example (Defining a Representation for a Declaration)

1
import { Schema, SchemaTransformation } from "effect"
2

3
class Point {
4
  constructor(
5
    readonly x: number,
6
    readonly y: number,
7
  ) {}
8
}
9

10
const PointSchema = Schema.instanceOf(Point, {
11
  toCodecJson: () =>
12
    Schema.link<Point>()(
13
      Schema.Tuple([Schema.Finite, Schema.Finite]),
14
      SchemaTransformation.transform({
15
        decode: ([x, y]) => new Point(x, y),
16
        encode: (point) => [point.x, point.y] as const,
17
      }),
18
    ),
19
})
20

21
const point = new Point(1, 2)
22

23
Schema.encodeSync(Schema.toCodecJson(PointSchema))(point) // => [1, 2]
24
Schema.encodeSync(Schema.toCodecStringTree(PointSchema))(point) // => ["1", "2"]

Codec annotations may contain fallible or effectful transformations. The parser used to consume the derived codec controls their execution and failure handling. Schema.toIso consumes toCodecIso synchronously, so transformations used through that API must complete synchronously. An annotation cannot add a required service that is absent from the derived codec’s service type.

Relationship to JSON Schema

Schema.toJsonSchemaDocument(schema) first derives the canonical JSON codec, then describes its encoded side. A custom toCodecJson annotation therefore defines both the runtime JSON representation and the shape emitted as JSON Schema.

For the PointSchema above, JSON Schema generation describes a two-item array of numbers. An opaque declaration without a structural JSON codec produces an unconstrained JSON Schema instead. See JSON Schema for generation options and limitations.