Schema转JSON Schema

JSONSchema.make函数允许您从模式生成JSON Schema。

示例（为结构体创建JSON Schema）

以下示例定义了一个Person模式，包含name（字符串）和age（数字）属性。然后生成相应的JSON Schema。

import { JSONSchema, Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number
})

const jsonSchema = JSONSchema.make(Person)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "name",
    "age"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  },
  "additionalProperties": false
}
*/

JSONSchema.make函数旨在生成一个最优的JSON Schema，表示解码阶段的输入部分。 它通过从最嵌套的组件开始遍历模式，合并每个细化，并在遇到第一个转换时停止来实现这一点。

示例（在JSON Schema中排除转换）

考虑修改age字段以包含细化和转换。只有细化会反映在JSON Schema中。

import { JSONSchema, Schema } from "effect"

const Person = Schema.Struct({
  name: Schema.String,
  age: Schema.Number.pipe(
    // 细化包含在JSON Schema中
    Schema.int(),
    // 转换从JSON Schema中排除
    Schema.clamp(1, 10)
  )
})

const jsonSchema = JSONSchema.make(Person)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "name",
    "age"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "integer",
      "description": "an integer",
      "title": "integer"
    }
  },
  "additionalProperties": false
}
*/

在这种情况下，JSON Schema反映了整数细化，但不包括限制值的转换。

模式类型的特定输出

字面量

字面量在JSON Schema中转换为enum类型。

示例（单个字面量）

import { JSONSchema, Schema } from "effect"

const schema = Schema.Literal("a")

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "enum": [
    "a"
  ]
}
*/

示例（字面量联合）

import { JSONSchema, Schema } from "effect"

const schema = Schema.Literal("a", "b")

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "enum": [
    "a",
    "b"
  ]
}
*/

Void

import { JSONSchema, Schema } from "effect"

const schema = Schema.Void

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/void",
  "title": "void"
}
*/

Any

import { JSONSchema, Schema } from "effect"

const schema = Schema.Any

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/any",
  "title": "any"
}
*/

Unknown

import { JSONSchema, Schema } from "effect"

const schema = Schema.Unknown

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/unknown",
  "title": "unknown"
}
*/

Object

import { JSONSchema, Schema } from "effect"

const schema = Schema.Object

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "/schemas/object",
  "anyOf": [
    {
      "type": "object"
    },
    {
      "type": "array"
    }
  ],
  "description": "an object in the TypeScript meaning, i.e. the `object` type",
  "title": "object"
}
*/

String

import { JSONSchema, Schema } from "effect"

const schema = Schema.String

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string"
}
*/

Number

import { JSONSchema, Schema } from "effect"

const schema = Schema.Number

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "number"
}
*/

Boolean

import { JSONSchema, Schema } from "effect"

const schema = Schema.Boolean

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "boolean"
}
*/

Tuples

import { JSONSchema, Schema } from "effect"

const schema = Schema.Tuple(Schema.String, Schema.Number)

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "minItems": 2,
  "items": [
    {
      "type": "string"
    },
    {
      "type": "number"
    }
  ],
  "additionalItems": false
}
*/

Arrays

import { JSONSchema, Schema } from "effect"

const schema = Schema.Array(Schema.String)

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "items": {
    "type": "string"
  }
}
*/

非空数组

表示至少有一个元素的数组。

示例

import { JSONSchema, Schema } from "effect"

const schema = Schema.NonEmptyArray(Schema.String)

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "array",
  "minItems": 1,
  "items": {
    "type": "string"
  }
}
*/

Structs

import { JSONSchema, Schema } from "effect"

const schema = Schema.Struct({
  name: Schema.String,
  age: Schema.Number
})

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "name",
    "age"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  },
  "additionalProperties": false
}
*/

Records

import { JSONSchema, Schema } from "effect"

const schema = Schema.Record({
  key: Schema.String,
  value: Schema.Number
})

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [],
  "properties": {},
  "patternProperties": {
    "": {
      "type": "number"
    }
  }
}
*/

结构体与记录的混合

将结构体的固定属性与记录的动态属性相结合。

示例

import { JSONSchema, Schema } from "effect"

const schema = Schema.Struct(
  {
    name: Schema.String,
    age: Schema.Number
  },
  Schema.Record({
    key: Schema.String,
    value: Schema.Union(Schema.String, Schema.Number)
  })
)

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "name",
    "age"
  ],
  "properties": {
    "name": {
      "type": "string"
    },
    "age": {
      "type": "number"
    }
  },
  "patternProperties": {
    "": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        }
      ]
    }
  }
}
*/

Enums

import { JSONSchema, Schema } from "effect"

enum Fruits {
  Apple,
  Banana
}

const schema = Schema.Enums(Fruits)

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$comment": "/schemas/enums",
  "anyOf": [
    {
      "type": "number",
      "title": "Apple",
      "enum": [
        0
      ]
    },
    {
      "type": "number",
      "title": "Banana",
      "enum": [
        1
      ]
    }
  ]
}
*/

Template Literals

import { JSONSchema, Schema } from "effect"

const schema = Schema.TemplateLiteral(Schema.Literal("a"), Schema.Number)

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "title": "`a${number}`",
  "description": "a template literal",
  "pattern": "^a[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?$"
}
*/

联合

联合使用anyOf或enum表示，取决于涉及的类型：

示例（通用联合）

import { JSONSchema, Schema } from "effect"

const schema = Schema.Union(Schema.String, Schema.Number)

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "anyOf": [
    {
      "type": "string"
    },
    {
      "type": "number"
    }
  ]
}
*/

示例（字面量联合）

import { JSONSchema, Schema } from "effect"

const schema = Schema.Literal("a", "b")

console.log(JSON.stringify(JSONSchema.make(schema), null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "enum": [
    "a",
    "b"
  ]
}
*/

标识符注解

您可以向模式添加identifier注解以改善结构和可维护性。带注解的模式包含在JSON Schema根部的$defs对象中，并从那里引用。

示例（使用标识符注解）

import { JSONSchema, Schema } from "effect"

const Name = Schema.String.annotations({ identifier: "Name" })

const Age = Schema.Number.annotations({ identifier: "Age" })

const Person = Schema.Struct({
  name: Name,
  age: Age
})

const jsonSchema = JSONSchema.make(Person)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$defs": {
    "Name": {
      "type": "string",
      "description": "a string",
      "title": "string"
    },
    "Age": {
      "type": "number",
      "description": "a number",
      "title": "number"
    }
  },
  "type": "object",
  "required": [
    "name",
    "age"
  ],
  "properties": {
    "name": {
      "$ref": "#/$defs/Name"
    },
    "age": {
      "$ref": "#/$defs/Age"
    }
  },
  "additionalProperties": false
}
*/

通过使用标识符注解，模式可以更容易地重用和引用，特别是在复杂的JSON Schema中。

标准JSON Schema注解

支持标准JSON Schema注解，如title、description、default和examples。 这些注解允许您用元数据丰富模式，可以增强可读性并提供有关数据结构的附加信息。

示例（使用注解添加元数据）

import { JSONSchema, Schema } from "effect"

const schema = Schema.String.annotations({
  description: "my custom description",
  title: "my custom title",
  default: "",
  examples: ["a", "b"]
})

const jsonSchema = JSONSchema.make(schema)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "string",
  "description": "my custom description",
  "title": "my custom title",
  "examples": [
    "a",
    "b"
  ],
  "default": ""
}
*/

为结构体属性添加注解

为了增强JSON模式的清晰度，建议直接向属性签名添加注解，而不是向类型本身添加。 这种方法在语义上更合适，因为它将描述性标题和其他元数据特别链接到它们描述的属性，而不是链接到通用类型。

示例（带注解的结构体属性）

import { JSONSchema, Schema } from "effect"

const Person = Schema.Struct({
  firstName: Schema.propertySignature(Schema.String).annotations({
    title: "First name"
  }),
  lastName: Schema.propertySignature(Schema.String).annotations({
    title: "Last Name"
  })
})

const jsonSchema = JSONSchema.make(Person)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "firstName",
    "lastName"
  ],
  "properties": {
    "firstName": {
      "type": "string",
      "title": "First name"
    },
    "lastName": {
      "type": "string",
      "title": "Last Name"
    }
  },
  "additionalProperties": false
}
*/

递归和相互递归模式

支持递归和相互递归模式，但是对于这些类型的模式，必须使用identifier注解以确保生成的JSON Schema中的正确引用和定义。

示例（带有标识符注解的递归模式）

在此示例中，Category模式引用自身，因此需要使用identifier注解来促进引用。

import { JSONSchema, Schema } from "effect"

// 定义表示类别结构的接口
interface Category {
  readonly name: string
  readonly categories: ReadonlyArray<Category>
}

// 定义带有必需标识符注解的递归模式
const Category = Schema.Struct({
  name: Schema.String,
  categories: Schema.Array(
    // 对Category模式的递归引用
    Schema.suspend((): Schema.Schema<Category> => Category)
  )
}).annotations({ identifier: "Category" })

const jsonSchema = JSONSchema.make(Category)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$defs": {
    "Category": {
      "type": "object",
      "required": [
        "name",
        "categories"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "categories": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Category"
          }
        }
      },
      "additionalProperties": false
    }
  },
  "$ref": "#/$defs/Category"
}
*/

自定义JSON Schema生成

在使用JSON Schema时，某些数据类型（如bigint）缺乏直接表示，因为JSON Schema本身不支持它们。 这种缺失通常会在生成模式时导致错误。

示例（由于缺少注解导致的错误）

尝试为不支持的类型（如bigint）生成JSON Schema将导致缺少注解错误：

import { JSONSchema, Schema } from "effect"

const schema = Schema.Struct({
  a_bigint_field: Schema.BigIntFromSelf
})

const jsonSchema = JSONSchema.make(schema)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
抛出：
Error: Missing annotation
at path: ["a_bigint_field"]
details: Generating a JSON Schema for this schema requires a "jsonSchema" annotation
schema (BigIntKeyword): bigint
*/

为了解决这个问题，您可以使用自定义的jsonSchema注解来增强模式，定义您打算如何在JSON Schema中表示这些类型：

示例（为不支持的类型使用自定义注解）

import { JSONSchema, Schema } from "effect"

const schema = Schema.Struct({
  // 为`bigint`类型添加自定义JSON Schema注解
  a_bigint_field: Schema.BigIntFromSelf.annotations({
    jsonSchema: {
      type: "some custom way to represent a bigint in JSON Schema"
    }
  })
})

const jsonSchema = JSONSchema.make(schema)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "a_bigint_field"
  ],
  "properties": {
    "a_bigint_field": {
      "type": "some custom way to represent a bigint in JSON Schema"
    }
  },
  "additionalProperties": false
}
*/

细化

在定义细化时（例如，通过Schema.filter函数），您可以包含JSON Schema注解来描述细化。此注解作为”片段”添加，成为生成的JSON Schema的一部分。如果模式包含多个细化，它们各自的注解将合并到输出中。

示例（使用带有合并注解的细化）

import { JSONSchema, Schema } from "effect"

// 定义带有正数细化的模式
const Positive = Schema.Number.pipe(
  Schema.filter((n) => n > 0, {
    jsonSchema: { minimum: 0 }
  })
)

// 向模式添加上界细化
const schema = Positive.pipe(
  Schema.filter((n) => n <= 10, {
    jsonSchema: { maximum: 10 }
  })
)

const jsonSchema = JSONSchema.make(schema)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "number",
  "minimum": 0,
  "maximum": 10
}
*/

jsonSchema注解被定义为通用对象，允许它表示非标准扩展。这种灵活性将强制执行类型约束的责任留给用户。

如果您更喜欢更严格的类型强制执行或需要支持非标准扩展，您可以在对象字面量上引入satisfies约束。此约束应与您选择的类型库结合使用。

示例（确保类型正确性）

在以下示例中，我们使用了@types/json-schema包为JSON Schema提供TypeScript定义。这种方法不仅确保类型正确性，还在您的IDE中启用自动完成建议。

import { JSONSchema, Schema } from "effect"
import type { JSONSchema7 } from "json-schema"

const Positive = Schema.Number.pipe(
  Schema.filter((n) => n > 0, {
    jsonSchema: { minimum: 0 } // 通用对象，无类型强制执行
  })
)

const schema = Positive.pipe(
  Schema.filter((n) => n <= 10, {
    jsonSchema: { maximum: 10 } satisfies JSONSchema7 // 强制执行类型约束
  })
)

const jsonSchema = JSONSchema.make(schema)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "number",
  "minimum": 0,
  "maximum": 10
}
*/

对于除细化之外的模式类型，您可以通过提供自定义的jsonSchema注解来覆盖默认生成的JSON Schema。此注解的内容将替换系统生成的模式。

示例（结构体的自定义注解）

import { JSONSchema, Schema } from "effect"

// 定义带有自定义JSON Schema注解的结构体
const schema = Schema.Struct({ foo: Schema.String }).annotations({
  jsonSchema: { type: "object" }
})

const jsonSchema = JSONSchema.make(schema)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object"
}
默认情况下应该是：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "foo"
  ],
  "properties": {
    "foo": {
      "type": "string"
    }
  },
  "additionalProperties": false
}
*/

使用Schema.parseJson的专门JSON Schema生成

Schema.parseJson函数提供了一种独特的JSON Schema生成方法。它不是默认为表示转换”from”侧的普通字符串模式，而是基于参数中提供的结构生成模式。

这种行为确保生成的JSON Schema反映解析数据的预期结构，而不是原始JSON输入。

示例（为解析对象生成JSON Schema）

import { JSONSchema, Schema } from "effect"

// 定义将JSON字符串解析为结构化对象的模式
const schema = Schema.parseJson(
  Schema.Struct({
    // 嵌套解析：JSON字符串到数字
    a: Schema.parseJson(Schema.NumberFromString)
  })
)

const jsonSchema = JSONSchema.make(schema)

console.log(JSON.stringify(jsonSchema, null, 2))
/*
输出：
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": [
    "a"
  ],
  "properties": {
    "a": {
      "type": "string",
      "contentMediaType": "application/json"
    }
  },
  "additionalProperties": false
}
*/