本技能的核心用途是编写能被 z-schema 正确校验的、符合惯用法的 JSON Schema，默认目标草案为 draft-2020-12。
一、基本写法 每个 schema 建议以 $schema 声明和 type 开头，可使用如下模板： { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": {}, "required": [], "additionalProperties": false } 当需要拒绝额外属性时，必须显式设置 additionalProperties: false，因为 z-schema 默认允许额外属性。
二、对象 schema 可定义带必填字段的对象，支持 minLength、format、minimum、maximum 等约束；也可定义嵌套对象。动态属性名可使用 patternProperties 按正则校验属性键，或用 propertyNames（draft-06+）约束所有属性键。
三、数组 schema 统一数组使用 items、minItems、uniqueItems。元组校验（draft-2020-12）使用 prefixItems 指定位置类型，items 表示剩余元素；items: false 会拒绝元组位置之外的额外元素。contains（draft-06+）要求至少一个匹配项；draft-2019-09+ 还可配合 minContains、maxContains 限定数量。
四、字符串与数值 字符串支持 minLength、maxLength、pattern。z-schema 内置 format 校验器，包括 date、date-time、time、email、idn-email、hostname、idn-hostname、ipv4、ipv6、uri、uri-reference、uri-template、iri、iri-reference、json-pointer、relative-json-pointer、regex、duration、uuid。默认始终强制 format 断言（formatAssertions: null）；在 draft-2020-12 中若要使用词汇表感知行为，可在校验器上设置 formatAssertions: true。数值支持 minimum、maximum、multipleOf，严格边界使用 exclusiveMinimum / exclusiveMaximum。
五、组合器 anyOf 表示至少匹配一个；oneOf 表示恰好匹配一个；allOf 表示全部匹配，用于组合基础 schema 与细化；not 表示不得匹配；if / then / else（draft-07+）用于条件校验。当条件是单一判别字段时，建议优先使用 if/then/else 而非 oneOf，因为其错误信息更清晰。选择建议：值可为多种类型用 anyOf；恰好一个变体匹配用 oneOf；组合继承 schema 用 allOf；“若满足条件则要求字段”用 if/then/else；排除特定形状用 not。
六、复用与引用 本地定义使用 $defs，通过 $ref 引用，例如 "#/$defs/address"。跨 schema 引用可编译 schema 数组并按 $id 引用。示例代码： import ZSchema from 'z-schema';
const schemas = [ { $id: 'address', type: 'object', properties: { city: { type: 'string' } }, required: ['city'], }, { $id: 'person', type: 'object', properties: { name: { type: 'string' }, home: { $ref: 'address' }, }, required: ['name'], }, ];
const validator = ZSchema.create(); validator.validateSchema(schemas); validator.validate({ name: 'Alice', home: { city: 'Paris' } }, 'person');
七、严格 schema 用 allOf 组合 schema 时，子 schema 中的 additionalProperties: false 会阻止兄弟 schema 定义的属性。此时应使用 unevaluatedProperties（draft-2019-09+），它会跟踪所有 applicator 中已评估的属性。示例可接受 { "name": "Alice", "age": 30 }，但拒绝 { "name": "Alice", "age": 30, "extra": true }。
八、校验 schema 本身 建议在启动时始终校验 schema： const validator = ZSchema.create(); try { validator.validateSchema(schema); } catch (err) { console.log('Schema errors:', err.details); }
九、常见错误 忘记 additionalProperties：默认允许额外属性，需设置 additionalProperties: false 或 unevaluatedProperties: false 来拒绝。 在 allOf 中使用 additionalProperties: false：会阻止兄弟 schema 的属性，应改用顶层的 unevaluatedProperties: false（draft-2019-09+）。 draft-2020-12 的数组项：元组校验改用 prefixItems，items 现在表示“剩余项的 schema”。 缺少 $schema：z-schema 会使用配置的默认草案，应包含 $schema 以明确目标草案。 definitions 与 $defs：两者均可用，但 draft-2019-09+ 的规范形式是 $defs，建议统一使用。
十、适用场景与限制 适用于需要编写 JSON Schema、为 API 载荷定义 schema 等任务。其他信息（如具体安装配置、平台细节、收费方式等）暂未提供。