数据类型

JSON Schema 2020-12 的任意值、对象开放性、数组、字典、组合、引用、约束和缺省语义。

本页适用于 baijimu-types 14.0.0。混合 Type 位置使用以下包装；后续示例除参数外均为包装内部的标准 Schema。

{ "@type": "JsonSchema", "schema": { "type": "string" } }

基本类型与任意 JSON

标准 type 支持 null、boolean、object、array、number、integer、string，也接受这些类型组成的非空数组。integer 按数值是否为整数判断，1.0 仍是整数。类型名没有 unknown、any、json、date 或 instant。

Schema	接受的值
`true` 或 `{}`	任意 JSON，包括对象、数组、标量和 null
`false`	不接受任何值
`{"type":"object"}`	任意对象，不接受数组、标量或 null
`{"type":["string","null"]}`	字符串或 null
`{"type":"string","format":"date"}`	合法日期字符串

时间点使用 Unix epoch 毫秒整数，见时间类型。数据可空通过类型联合或组合表达，不使用 nullable。

true

对象开放性

{ "type": "object", "properties": {} }

省略 properties 或声明 properties: {} 都不会关闭对象。这个例子接受 {} 和 {"data":[1,"text",null]}，拒绝根数组、标量和 null。

{
  "type": "object",
  "properties": {
    "sku": { "type": "string" },
    "note": { "type": ["string", "null"] }
  },
  "required": ["sku"],
  "additionalProperties": false
}

properties 约束出现时的值，required 决定键是否必须出现，additionalProperties: false 显式拒绝其他键。上例允许省略 note，也允许它为 null。

{ "type": "object", "properties": {}, "additionalProperties": false }

这个例子才是封闭空对象，只接受 {}。从旧类型迁移时必须保留原对象的开放或封闭语义，不能仅删除标签。

数组与字典

{ "type": "array", "items": { "type": "object" }, "minItems": 1 }

items 约束元素，prefixItems 描述元组前缀，contains 配合 minContains / maxContains 约束匹配元素数量。uniqueItems 按 JSON 值判断唯一性。

字典使用对象的 additionalProperties 指定值 Schema，不再使用独立 Map 类型：

{
  "type": "object",
  "additionalProperties": { "type": "integer", "minimum": 0 },
  "minProperties": 1
}

组合、枚举与约束

anyOf 至少匹配一个分支，oneOf 恰好匹配一个分支，allOf 匹配全部分支。分支都是标准 Schema；与同层其他约束同时生效。不要把 allOf 当成合并封闭对象字段的操作。

{ "anyOf": [{ "type": "string" }, { "type": "integer" }, { "type": "null" }] }

number 与 integer 有交集，同时放入 oneOf 会让整数匹配两个分支而被拒绝。

{ "type": "string", "enum": ["pending", "done"] }

用途	标准关键字
固定值与枚举	`const`、`enum`
字符串	`minLength`、`maxLength`、`pattern`、`format`
数值	`minimum`、`maximum`、`exclusiveMinimum`、`exclusiveMaximum`、`multipleOf`
数组	`items`、`prefixItems`、`contains`、`minItems`、`maxItems`、`uniqueItems`
对象	`properties`、`required`、`additionalProperties`、`patternProperties`、`propertyNames`、`minProperties`、`maxProperties`
条件与组合	`anyOf`、`oneOf`、`allOf`、`not`、`if`、`then`、`else`、`dependentRequired`、`dependentSchemas`
未求值成员	`unevaluatedProperties`、`unevaluatedItems`
复用与递归	`$id`、`$defs`、`$ref`、`$anchor`、`$dynamicRef`、`$dynamicAnchor`

使用 JSON Schema 的标准大小写，例如 oneOf、minLength；旧 one_of、min_length、value_type 和 nullable 不会作为无效注释被默默接受。若声明 $schema，必须使用 https://json-schema.org/draft/2020-12/schema。未知必需 vocabulary 与其他方言被拒绝。平台的数据校验启用 format assertion，未知 format 被拒绝。

引用资源由已授权的精确资源集合提供，URI 不会自动触发网络或文件下载。合法递归保留为引用图；不消耗实例层级、无法前进的引用环会被拒绝。具体作用域见命名类型与精确引用。

必填、可空与默认值

问题	声明位置	含义
对象键必须出现	Schema 的 `required` 数组	与出现后能否为 null 分开
数据允许 null	`type` 包含 `null`，或相应组合分支	不等于允许省略必填键
方法参数必须传入	参数定义的 `required` 布尔值	必须显式填写
方法参数默认值	参数定义的 `default_value`	缺失与显式 null 保留区别
Schema 的默认注释	标准 `default`	不会自动插入字段或修改实例

{
  "name": "limit",
  "type": { "@type": "JsonSchema", "schema": { "type": "integer", "minimum": 1 } },
  "required": false,
  "default_value": 20
}

default_value 是参数契约中的字面值，不是表达式；不要与 Module 属性 defaultValue 的字段规则混用。

模型严格结构化输出

普通数据校验与模型严格输出的支持范围不同。公共库提供保守的 strict-output 能力检查：对象必须显式 additionalProperties: false，所有属性必须已在 required 中声明，数组必须有 items。

该检查拒绝动态字段、未约束 Schema、引用，以及 oneOf、allOf、条件、元组、contains 等超出范围的关键字。不同模型的额外能力由对应适配器验证。通过时返回原 Schema，不自动补 required、不补 null、不关闭对象、不丢弃约束。 合法的数据 Schema 仍可能不适用于严格输出。

{
  "type": "object",
  "properties": {
    "approved": { "type": "boolean" },
    "reason": { "type": ["string", "null"] }
  },
  "required": ["approved", "reason"],
  "additionalProperties": false
}