Schema to JSON Schema

Schema.toJsonSchemaDocument generates a JSON Schema Draft 2020-12 document for a schema’s canonical JSON representation.

Internally, Effect first derives Schema.toCodecJson(schema) and then describes that codec’s encoded side. The generated JSON Schema therefore matches the values accepted and produced by the canonical JSON codec, including the JSON representations of Effect data types.

Basic Conversion

Example (Generating JSON Schema for a Struct)

1
import { Schema } from "effect"
2

3
const Person = Schema.Struct({
4
  name: Schema.String,
5
  age: Schema.Finite,
6
})
7

8
const document = Schema.toJsonSchemaDocument(Person)
9

10
document.dialect // => "draft-2020-12"
11
document.schema.type // => "object"
12
document.schema.required // => ["name", "age"]
13
document.schema.additionalProperties // => false

The returned document contains:

dialect: the source dialect, always "draft-2020-12".
schema: the root JSON Schema.
definitions: definitions referenced through $ref.

JSON Schema generation is best-effort. Semantics that JSON Schema cannot express exactly may be approximated, and opaque declarations without a structural JSON codec produce an unconstrained schema.

Canonical JSON Representations

For codecs, the output describes the encoded JSON shape rather than the decoded Type.

Example (Describing the Encoded Side)

1
import { Schema } from "effect"
2

3
// Type: number, Encoded: string
4
Schema.toJsonSchemaDocument(Schema.FiniteFromString).schema // => { type: "string" }

Declarations such as Option, Duration, and BigInt define canonical JSON codecs. Their generated JSON Schemas describe those representations.

Example (Describing an Option’s JSON Representation)

1
import { Schema } from "effect"
2

3
const document = Schema.toJsonSchemaDocument(Schema.Option(Schema.String))
4

5
console.log(document.schema)
6
/*
7
Output:
8
{
9
  anyOf: [
10
    {
11
      type: "object",
12
      properties: {
13
        _tag: { type: "string", enum: ["Some"] },
14
        value: { type: "string" }
15
      },
16
      required: ["_tag", "value"],
17
      additionalProperties: false
18
    },
19
    {
20
      type: "object",
21
      properties: {
22
        _tag: { type: "string", enum: ["None"] }
23
      },
24
      required: ["_tag"],
25
      additionalProperties: false
26
    }
27
  ]
28
}
29
*/

When defining a custom declaration, provide a toCodecJson annotation if it has a meaningful JSON representation. Both Schema.toCodecJson and Schema.toJsonSchemaDocument will then use the same shape.

Other Drafts

Schema.toJsonSchemaDocument always emits Draft 2020-12. Convert the resulting document with the JsonSchema module when another draft is required.

Example (Converting to Draft 07)

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

3
const schema = Schema.Tuple([Schema.String, Schema.Finite])
4

5
const draft2020_12 = Schema.toJsonSchemaDocument(schema)
6
const draft07 = JsonSchema.toDocumentDraft07(draft2020_12)
7

8
draft07.dialect // => "draft-07"
9
draft07.schema.items // => [{ type: "string" }, { type: "number" }]

JsonSchema.toDocumentDraft04 similarly converts a document to Draft 04.

Annotations

The following standard JSON Schema annotations are emitted automatically:

title
description
default
examples
readOnly
writeOnly
format
contentEncoding
contentMediaType
contentSchema

Example (Adding Standard Metadata)

1
import { Schema } from "effect"
2

3
const Username = Schema.String.annotate({
4
  title: "Username",
5
  description: "A user name",
6
  default: "anonymous",
7
  examples: ["alice", "bob"],
8
})
9

10
const document = Schema.toJsonSchemaDocument(Username)
11

12
document.schema.title // => "Username"
13
document.schema.description // => "A user name"
14
document.schema.default // => "anonymous"
15
document.schema.examples // => ["alice", "bob"]

Annotating a Codec’s Encoded Side

Calling .annotate(...) on a codec annotates its decoded side. Use Schema.annotateEncoded for metadata that belongs to the JSON representation.

Example (Annotating Encoded Input)

1
import { Schema } from "effect"
2

3
const schema = Schema.Trim.pipe(
4
  Schema.annotateEncoded({
5
    title: "Encoded text",
6
    description: "Text before trimming",
7
  }),
8
)
9

10
const document = Schema.toJsonSchemaDocument(schema)
11

12
document.schema.type // => "string"
13
document.schema.title // => "Encoded text"
14
document.schema.description // => "Text before trimming"

Custom Annotation Keys

Use includeAnnotationKey to whitelist non-standard annotations such as editor metadata or vendor extensions. Standard keys are always included.

Example (Including Custom Metadata)

1
import { Schema } from "effect"
2

3
const schema = Schema.String.annotate({
4
  description: "A name",
5
  markdownDescription: "The **name** field",
6
  "x-widget": "text",
7
})
8

9
const document = Schema.toJsonSchemaDocument(schema, {
10
  includeAnnotationKey: (key) =>
11
    key === "markdownDescription" || key.startsWith("x-"),
12
})
13

14
document.schema.description // => "A name"
15
document.schema.markdownDescription // => "The **name** field"
16
document.schema["x-widget"] // => "text"

Filters and Constraints

Built-in filters contribute JSON Schema constraints such as minLength, maximum, pattern, and uniqueItems.

Example (Generating Validation Constraints)

1
import { Schema } from "effect"
2

3
const Username = Schema.String.check(
4
  Schema.isMinLength(3),
5
  Schema.isMaxLength(20),
6
  Schema.isPattern(/^[a-z0-9_]+$/),
7
)
8

9
Schema.toJsonSchemaDocument(Username).schema.allOf // => [{ minLength: 3 }, { maxLength: 20 }, { pattern: "^[a-z0-9_]+$" }]

For a custom filter, provide a toJsonSchema callback when its constraint has a JSON Schema equivalent.

Example (Describing a Custom Filter)

1
import { Schema } from "effect"
2

3
const LongString = Schema.String.check(
4
  Schema.makeFilter((value) => value.length >= 3, {
5
    expected: "a string with at least three characters",
6
    toJsonSchema: () => ({ minLength: 3 }),
7
  }),
8
)
9

10
Schema.toJsonSchemaDocument(LongString).schema.allOf // => [{ minLength: 3 }]

Set generateDescriptions: true to turn a check’s expected annotation into a description when no description was supplied explicitly.

Optional Properties

An optionalKey property is omitted from required. A property defined with optional is also omitted from required, and its explicit undefined case is represented as null because JSON has no undefined value.

Example (Optional Properties)

1
import { Schema } from "effect"
2

3
const schema = Schema.Struct({
4
  name: Schema.optionalKey(Schema.String),
5
  nickname: Schema.optional(Schema.String),
6
})
7

8
const document = Schema.toJsonSchemaDocument(schema)
9

10
console.log(document.schema)
11
/*
12
Output:
13
{
14
  type: "object",
15
  properties: {
16
    name: { type: "string" },
17
    nickname: {
18
      anyOf: [{ type: "string" }, { type: "null" }]
19
    }
20
  },
21
  additionalProperties: false
22
}
23
*/

References and Recursion

An identifier annotation creates a definition and replaces uses of that schema with $ref.

Example (Creating Reusable Definitions)

1
import { Schema } from "effect"
2

3
const Name = Schema.String.annotate({ identifier: "Name" })
4
const Person = Schema.Struct({ name: Name })
5

6
const document = Schema.toJsonSchemaDocument(Person)
7

8
console.log(document.schema)
9
/*
10
Output:
11
{
12
  type: "object",
13
  properties: {
14
    name: { $ref: "#/$defs/Name" }
15
  },
16
  required: ["name"],
17
  additionalProperties: false
18
}
19
*/

Recursive schemas require an identifier so their self-references can be emitted as $ref.

Example (Generating a Recursive JSON Schema)

1
import { Schema } from "effect"
2

3
interface Category {
4
  readonly name: string
5
  readonly categories: ReadonlyArray<Category>
6
}
7

8
const Category = Schema.Struct({
9
  name: Schema.String,
10
  categories: Schema.Array(
11
    Schema.suspend((): Schema.Codec<Category> => Category),
12
  ),
13
}).annotate({ identifier: "Category" })
14

15
const document = Schema.toJsonSchemaDocument(Category)
16

17
console.log(document)
18
/*
19
Output:
20
{
21
  dialect: "draft-2020-12",
22
  schema: {
23
    $ref: "#/$defs/Category"
24
  },
25
  definitions: {
26
    Category: {
27
      type: "object",
28
      properties: {
29
        name: { type: "string" },
30
        categories: {
31
          type: "array",
32
          items: { $ref: "#/$defs/Category" }
33
        }
34
      },
35
      required: ["name", "categories"],
36
      additionalProperties: false
37
    }
38
  }
39
}
40
*/

Generation Options

Schema.toJsonSchemaDocument accepts three options:

additionalProperties: false by default, true to allow extra properties, or a JSON Schema describing them.
generateDescriptions: generate missing check descriptions from expected annotations.
includeAnnotationKey: include selected non-standard annotation keys.

Example (Allowing Additional Properties)

1
import { Schema } from "effect"
2

3
const schema = Schema.Struct({ name: Schema.String })
4

5
const document = Schema.toJsonSchemaDocument(schema, {
6
  additionalProperties: true,
7
})
8

9
document.schema.additionalProperties // => true

JSON Strings

Schema.fromJsonString accepts a JSON string and decodes its parsed contents with another schema. Its JSON Schema describes the outer string and marks its media type as JSON.

Example (Describing a JSON String)

1
import { Schema } from "effect"
2

3
const schema = Schema.fromJsonString(Schema.Struct({ name: Schema.String }))
4

5
const document = Schema.toJsonSchemaDocument(schema)
6

7
document.schema.type // => "string"
8
document.schema.contentMediaType // => "application/json"