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 // => true

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. Schema.toJsonSchemaDocument uses the same representation as Schema.toCodecJson, so runtime serialization and the generated document agree.

Example (Describing the Encoded Side)

1
import { Schema } from "effect"
2

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

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_]+$/u),
7
)
8

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

JavaScript counts UTF-16 code units while JSON Schema counts Unicode code points. For this reason, isMinLength(3) is represented conservatively as minLength: 2 so the generated schema does not reject a string accepted by Effect.

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 // => { type: "string", 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: true
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: true
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: true
37
    }
38
  }
39
}
40
*/

Generation Options

Schema.toJsonSchemaDocument accepts four options:

referencePolicy: controls which schemas become named references.
onExcessProperty: "ignore" by default, leaving unmodeled properties open; "error" closes them when their key space can be represented.
generateDescriptions: generate missing check descriptions from expected annotations.
includeAnnotationKey: include selected non-standard annotation keys.

Example (Rejecting Additional Properties)

1
import { Schema } from "effect"
2

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

5
const document = Schema.toJsonSchemaDocument(schema, {
6
  onExcessProperty: "error",
7
})
8

9
document.schema.additionalProperties // => false

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"