本技能用于使用 z-schema 库按 JSON Schema 校验 JSON 数据。
用途：当需要校验 JSON、根据 Schema 检查数据或处理校验错误时使用。
支持的草案与默认值：z-schema 支持 JSON Schema 的 draft-04、draft-06、draft-07、draft-2019-09、draft-2020-12，默认草案为 draft-2020-12。安装命令为 npm install z-schema。
快速开始： import ZSchema from 'z-schema'; const validator = ZSchema.create(); const schema = { type: 'object', properties: { name: { type: 'string' }, age: { type: 'integer', minimum: 0 }, }, required: ['name'], }; // Throws on invalid data validator.validate({ name: 'Alice', age: 30 }, schema);
主要能力与校验模式：z-schema 基于 async 和 safe 两个开关提供四种模式。同步抛错（ZSchema.create()）返回 true 或抛出 ValidateError，适用于默认的简单脚本和中间件；同步安全（ZSchema.create({ safe: true })）返回 { valid, err? }，适用于不想用 try/catch 检查错误的场景；异步抛错（ZSchema.create({ async: true })）返回 Promise<true> 或拒绝，适用于使用异步格式校验器；异步安全（ZSchema.create({ async: true, safe: true })）返回 Promise<{ valid, err? }>，适用于异步且不抛错。也可在普通（抛错）校验器上调用 .validateSafe() 获得相同结果结构。
错误检查：ValidateError 的 .details 是 SchemaErrorDetail 数组，字段包括 message、code、params、path、keyword、inner、schemaPath、schemaId。组合器（anyOf、oneOf、not）会产生嵌套的 inner 错误，可遍历输出。可通过第三个参数 ValidateOptions 传入 includeErrors 或 excludeErrors 来包含或排除特定错误码，例如仅报告类型错误或屏蔽字符串长度错误。完整错误码列表见 references/error-codes.md。
Schema 预编译与引用：可在启动时编译 schema 以提升运行时性能并解析交叉引用，使用 validator.validateSchema(schemas) 编译并注册引用，随后用编译后的 schema ID 校验数据（如 validator.validate(data, 'person')）。远程引用可手动注册（ZSchema.setRemoteReference(uri, schema) 或实例方法），也可通过 ZSchema.setSchemaReader 自动加载。缺失引用可用 validator.getMissingReferences(err) 和 getMissingRemoteReferences(err) 诊断。
自定义格式校验器：可全局注册（ZSchema.registerFormat）、实例级注册（validator.registerFormat）或在创建时通过 customFormats 选项传入。异步格式校验器返回 Promise<boolean>，需配合 { async: true }。可用 ZSchema.getRegisteredFormats() 列出已注册格式。
草案版本与常用选项：可通过 ZSchema.create({ version: 'draft-07' }) 显式指定草案，有效值为 'draft-04'、'draft-06'、'draft-07'、'draft2019-09'、'draft2020-12'（默认）、'none'。常用选项包括 breakOnFirstError（默认 false）、noEmptyStrings（默认 false）、noEmptyArrays（默认 false）、strictMode（默认 false）、ignoreUnknownFormats（默认 false）、formatAssertions（默认 null）、reportPathAsArray（默认 false）。完整选项见 references/options.md。
子 Schema 校验：可通过 options.schemaPath 定位 schema 内的特定路径，例如 validator.validate(carData, fullSchema, { schemaPath: 'definitions.car' })。
浏览器使用（UMD）：引入 node_modules/z-schema/umd/ZSchema.min.js，使用 ZSchema.create() 创建校验器并调用 validate。
TypeScript 类型：包内导出 JsonSchema、ZSchemaOptions、ValidateOptions、ValidateResponse、SchemaErrorDetail、ErrorCode、FormatValidatorFn、SchemaReader 等类型，以及 ValidateError 值。
重要约定：始终使用 ZSchema.create(options?)，不要使用 new ZSchema()；错误详情在 .details（而非 .errors）；类型用 import type { ... } 导入，值用 import { ValidateError } 导入；默认草案为 draft2020-12，若面向更早草案需显式指定。
适用场景：需要在 JavaScript/TypeScript 项目中对 JSON 数据进行 schema 校验、错误处理、引用解析或自定义格式校验的开发场景。
限制：资料未提供性能基准、与其他校验库的对比、浏览器兼容范围、授权或收费信息，暂未提供。