---
docStatus: current
---

# 数据类型

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

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

```json
{ "@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 毫秒整数，见[时间类型](/development/data-contracts/time/)。数据可空通过类型联合或组合表达，不使用 `nullable`。

```json
true
```

## 对象开放性

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

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

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

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

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

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

## 数组与字典

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

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

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

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

## 组合、枚举与约束

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

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

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

```json
{ "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 不会自动触发网络或文件下载。合法递归保留为引用图；不消耗实例层级、无法前进的引用环会被拒绝。具体作用域见[命名类型与精确引用](/development/type-system/references/)。

## 必填、可空与默认值

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

```json
{
  "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 仍可能不适用于严格输出。

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