feat: 扩展 JSON Schema 支持 — 完整关键字覆盖计划 #82

New Issue

2026-06-01T00:55:13Z

xiaoju commented

2026-06-01 00:55:13 +00:00

问题

当前 meta-schema 和 isValidSchema() 仅支持 12 个 JSON Schema 关键字，任何使用未支持关键字的 schema 都会被拒绝存入。这限制了用户定义有效数据约束的能力。

JSON Schema 关键字完整覆盖表

基于 JSON Schema Draft 2020-12 / Draft-07 常用关键字。

✅ 已支持（12 个）

关键字	分类	`isValidSchema()`	`collectRefs()`	备注
`type`	通用	✅	—	支持 string 和 array
`properties`	对象	✅	✅	递归验证 + ref 提取
`required`	对象	✅	—
`additionalProperties`	对象	✅	✅	boolean 或 schema
`anyOf`	组合	✅	✅
`oneOf`	组合	✅	✅
`items`	数组	✅	✅
`format`	字符串	✅	✅	`cas_ref` 自定义格式
`title`	元数据	✅	—
`description`	元数据	✅	—
`enum`	通用	✅	—
`const`	通用	✅	—

🔴 未支持 — 需要 `collectRefs()` 适配（有 cas_ref 风险）

关键字	分类	影响	优先级
`allOf`	组合	子 schema 可含 cas_ref	P1
`not`	组合	子 schema 可含 cas_ref（罕见）	P3
`if` / `then` / `else`	条件	子 schema 可含 cas_ref	P2
`patternProperties`	对象	值是 schema，可含 cas_ref	P2
`prefixItems`	数组	元组，每项可含 cas_ref	P2
`contains`	数组	子 schema 可含 cas_ref	P3
`propertyNames`	对象	约束 key 名，不含值引用	P3
`$ref` / `$defs`	引用	完全不同的复杂度级别	P4（暂不考虑）

🟡 未支持 — 纯约束/叶子（无 cas_ref 风险，加白名单即可）

关键字	分类	优先级
`minimum`	数值	P1
`maximum`	数值	P1
`exclusiveMinimum`	数值	P1
`exclusiveMaximum`	数值	P1
`multipleOf`	数值	P2
`minLength`	字符串	P1
`maxLength`	字符串	P1
`pattern`	字符串	P1
`minItems`	数组	P1
`maxItems`	数组	P1
`uniqueItems`	数组	P1
`minProperties`	对象	P2
`maxProperties`	对象	P2
`default`	元数据	P2
`examples`	元数据	P3
`readOnly`	元数据	P3
`writeOnly`	元数据	P3
`deprecated`	元数据	P3
`$comment`	元数据	P3
`$id`	标识	P4
`$schema`	标识	P4

实施计划

Phase 1 — 叶子约束（🟡 P1）

加白名单即可，不需要改 collectRefs()。

数值：minimum, maximum, exclusiveMinimum, exclusiveMaximum
字符串：minLength, maxLength, pattern
数组：minItems, maxItems, uniqueItems

Phase 2 — 组合 + 条件 + 叶子 P2（🔴 + 🟡）

需要扩展 collectRefs()。

allOf — collectRefs 遍历
if/then/else — collectRefs 遍历
patternProperties — collectRefs 遍历
prefixItems — collectRefs 遍历
multipleOf, minProperties, maxProperties, default

Phase 3 — 低频 + 元数据（🔴 P3 + 🟡 P3）

not, contains, propertyNames
examples, readOnly, writeOnly, deprecated, $comment

Phase 4 — `$ref` / `$defs`（待评估）

引入引用系统，复杂度显著提升，暂不纳入。

原始问题（原 #82）

CLI ucas put @schema 走 ajv 验证 meta-schema，meta-schema property 子项定义为 { type: \"object\", additionalProperties: false } 无 properties 声明，导致子项含任何 key 都被拒。

根因：不是 ajv vs isValidSchema 路径差异，而是 JSON Schema 支持不完整。

小橘 🍊（NEKO Team）

## 问题当前 meta-schema 和 `isValidSchema()` 仅支持 12 个 JSON Schema 关键字，任何使用未支持关键字的 schema 都会被拒绝存入。这限制了用户定义有效数据约束的能力。 ## JSON Schema 关键字完整覆盖表基于 JSON Schema Draft 2020-12 / Draft-07 常用关键字。 ### ✅ 已支持（12 个） | 关键字 | 分类 | `isValidSchema()` | `collectRefs()` | 备注 | |--------|------|:--:|:--:|------| | `type` | 通用 | ✅ | — | 支持 string 和 array | | `properties` | 对象 | ✅ | ✅ | 递归验证 + ref 提取 | | `required` | 对象 | ✅ | — | | | `additionalProperties` | 对象 | ✅ | ✅ | boolean 或 schema | | `anyOf` | 组合 | ✅ | ✅ | | | `oneOf` | 组合 | ✅ | ✅ | | | `items` | 数组 | ✅ | ✅ | | | `format` | 字符串 | ✅ | ✅ | `cas_ref` 自定义格式 | | `title` | 元数据 | ✅ | — | | | `description` | 元数据 | ✅ | — | | | `enum` | 通用 | ✅ | — | | | `const` | 通用 | ✅ | — | | ### 🔴 未支持 — 需要 `collectRefs()` 适配（有 cas_ref 风险） | 关键字 | 分类 | 影响 | 优先级 | |--------|------|------|--------| | `allOf` | 组合 | 子 schema 可含 cas_ref | P1 | | `not` | 组合 | 子 schema 可含 cas_ref（罕见） | P3 | | `if` / `then` / `else` | 条件 | 子 schema 可含 cas_ref | P2 | | `patternProperties` | 对象 | 值是 schema，可含 cas_ref | P2 | | `prefixItems` | 数组 | 元组，每项可含 cas_ref | P2 | | `contains` | 数组 | 子 schema 可含 cas_ref | P3 | | `propertyNames` | 对象 | 约束 key 名，不含值引用 | P3 | | `$ref` / `$defs` | 引用 | 完全不同的复杂度级别 | P4（暂不考虑） | ### 🟡 未支持 — 纯约束/叶子（无 cas_ref 风险，加白名单即可） | 关键字 | 分类 | 优先级 | |--------|------|--------| | `minimum` | 数值 | P1 | | `maximum` | 数值 | P1 | | `exclusiveMinimum` | 数值 | P1 | | `exclusiveMaximum` | 数值 | P1 | | `multipleOf` | 数值 | P2 | | `minLength` | 字符串 | P1 | | `maxLength` | 字符串 | P1 | | `pattern` | 字符串 | P1 | | `minItems` | 数组 | P1 | | `maxItems` | 数组 | P1 | | `uniqueItems` | 数组 | P1 | | `minProperties` | 对象 | P2 | | `maxProperties` | 对象 | P2 | | `default` | 元数据 | P2 | | `examples` | 元数据 | P3 | | `readOnly` | 元数据 | P3 | | `writeOnly` | 元数据 | P3 | | `deprecated` | 元数据 | P3 | | `$comment` | 元数据 | P3 | | `$id` | 标识 | P4 | | `$schema` | 标识 | P4 | ## 实施计划 ### Phase 1 — 叶子约束（🟡 P1）加白名单即可，不需要改 `collectRefs()`。 - 数值：`minimum`, `maximum`, `exclusiveMinimum`, `exclusiveMaximum` - 字符串：`minLength`, `maxLength`, `pattern` - 数组：`minItems`, `maxItems`, `uniqueItems` ### Phase 2 — 组合 + 条件 + 叶子 P2（🔴 + 🟡）需要扩展 `collectRefs()`。 - `allOf` — collectRefs 遍历 - `if/then/else` — collectRefs 遍历 - `patternProperties` — collectRefs 遍历 - `prefixItems` — collectRefs 遍历 - `multipleOf`, `minProperties`, `maxProperties`, `default` ### Phase 3 — 低频 + 元数据（🔴 P3 + 🟡 P3） - `not`, `contains`, `propertyNames` - `examples`, `readOnly`, `writeOnly`, `deprecated`, `$comment` ### Phase 4 — `$ref` / `$defs`（待评估）引入引用系统，复杂度显著提升，暂不纳入。 ## 原始问题（原 #82） CLI `ucas put @schema` 走 ajv 验证 meta-schema，meta-schema property 子项定义为 `{ type: \"object\", additionalProperties: false }` 无 properties 声明，导致子项含任何 key 都被拒。根因：不是 ajv vs isValidSchema 路径差异，而是 JSON Schema 支持不完整。 --- 小橘 🍊（NEKO Team）

xiaoju changed title from ~~bug: meta-schema additionalProperties 阻止 CLI 创建带类型约束的 schema~~ to feat: 扩展 JSON Schema 支持 — 完整关键字覆盖计划

2026-06-01 01:06:58 +00:00

xiaoju referenced this issue from a commit

2026-06-01 01:14:05 +00:00

feat: support P1 leaf JSON Schema constraints (#82)

xiaoju referenced this issue

2026-06-01 01:14:16 +00:00

feat: support P1 leaf JSON Schema constraints (#82) #84

xingyue referenced this issue from a commit

2026-06-01 01:26:52 +00:00

Merge pull request 'feat: support P1 leaf JSON Schema constraints (#82)' (#84) from feat/82-schema-p1-leaf-constraints into main

xiaoju referenced this issue from a commit