#moonschema

本项目为 2026 MoonBit 国产基础软件开源大赛 参赛项目。

#为什么是 moonschema

• 两层 API，一个引擎：ajv 的 "编译 JSON Schema 文档 → 复用校验器" 适合前后端契约校验；zod 的 "字段默认必填 + 流式约束" 适合 MoonBit 业务代码内联建模。两者编译到同一份内部表示，语义完全一致。
• 跨字段动态规则 DSL："end > start"、"items[0].price * items[0].qty == total" 这类跨字段约束，表达式在编译期解析（语法错误即刻暴露），弥补声明式 JSON Schema 表达不了的表单级规则。
• 错误看得见、可中文化：每条错误携带 keyword、instance_path（RFC 6901 JSON Pointer）、schema_path 三元组；校验消息内置中英双语（locale=ZH 一行切换）。
• strict 模式（ajv 同款默认行为）：拼错的关键词在编译期报错，而不是被静默忽略。
• 递归 $ref 可用：树/链表等递归模式通过惰性解析 + 编译缓存支持。
• 纯 MoonBit、零第三方依赖：仅依赖标准库 moonbitlang/core，天然跨 WASM-GC / JS / Native。

#安装

moon add QuietlyChan/moonschema

#快速开始

#ajv 风格：编译标准 JSON Schema

// moon.pkg: import "QuietlyChan/moonschema" @moonschema
let schema_text =
  #|{
  #|  "type": "object",
  #|  "required": ["id", "email"],
  #|  "properties": {
  #|    "id": { "type": "integer", "minimum": 1 },
  #|    "email": { "type": "string" }
  #|  },
  #|  "additionalProperties": false
  #|}
let v = @moonschema.compile(@moonschema.parse(schema_text))
let req =
  #|{ "id": -3, "email": 42, "extra": true }
let ok = v.check(@moonschema.parse(req)) // false
println(@moonschema.validate_to_string(v, @moonschema.parse(req)))
// /id: must be >= 1 [minimum @ #/properties/id/minimum]
// /email: must be string [type @ #/properties/email/type]
// (root): must NOT have additional properties ("extra") [additionalProperties @ #/additionalProperties]

#zod 风格：流式构建器

// moon.pkg: import "QuietlyChan/moonschema/builder" @builder
let user = @builder.object({
  "name": @builder.string().min_len(1).max_len(50),   // 默认必填，与 zod 一致
  "age": @builder.integer().min(0).max(150).optional(),
  "email": @builder.string().email(),                 // builder 层默认断言 format
}).strict()                                           // 拒绝未声明字段

let v = user.compile()        // moonschema 校验器
let doc = user.to_schema()    // 标准 JSON Schema 2020-12 文档，可与任何语言互通

#校验结果的三种消费方式

let ok : Bool = v.check(instance)                      // 只要结论
let errors : Array[@moonschema.ValidationError] = v.validate(instance)
for e in errors {
  println("\{e.instance_path}: \{e.message}")          // 结构化消费
}

#在浏览器中使用（Playground）

bash playground/build.sh        # moon build --target js --release --strip + 拷贝产物
cd playground/web && python -m http.server 8080   # 或 npx serve .
# 打开 http://localhost:8080

关于 wasm-gc：引擎已验证可在 wasm-gc 目标编译并导出数值函数（link.wasm-gc.exports，Node 24 WebAssembly.instantiate 实测通过）；但字符串在 wasm-gc 边界是 GC 对象，对 JS 不透明，需 JS-string-builtins 方案——Playground 因此选择字符串原生互通的 JS 后端。

#基准测试（vs ajv / zod）

#性质测试（roundtrip）

#已支持的关键词

#跨字段规则 DSL（x-rules）

// builder 侧
let order = @builder.object({
  "start": @builder.string(),
  "end":   @builder.string(),
  "total": @builder.number(),
  "items": @builder.array(@builder.object({
    "price": @builder.number(), "qty": @builder.number(),
  }).optional()),
}).satisfy("end > start")
  .satisfy("items[0].price * items[0].qty == total")

// JSON Schema 侧等价写法
// { "x-rules": ["end > start", "items[0].price * items[0].qty == total"] }

• 缺失即藐视通过：表达式引用的路径全部存在才参与判定——可选项的成对约束只约束"存在"的场合，是否必填仍由默认必填 / .optional() / required 表达
• 编译期语法检查：规则在 compile() 时解析，拼写错误立刻暴露，而不是等到校验期静默失效
• 错误的 schema_path 精确到 #/x-rules/<序号>

#错误消息 i18n

// JSON Schema 侧
let v = compile(schema, options=CompileOptions::new(locale=ZH))
// builder 侧
let v = user.compile(locale=ZH)

(root): 缺少必需属性 "name" [required @ #/required]
/age: 必须 >= 0 [minimum @ #/properties/age/minimum]
(root): 规则 "age > 0" 未满足 [x-rules @ #/x-rules/1]

#官方一致性测试

groups: 384 (compile-rejected: 133)
pass: 974  fail: 1  skip: 326
pass rate (of judged 975): 99.90%

• skip (326)：模式使用了引擎暂不支持的关键词（unevaluated*、$dynamicRef、远程引用等），strict 模式编译期整组拒绝，透明计入而非伪装成失败
• fail (1)：自定义元场景表（vocabulary）语义——v0 不做元模式感知，属已知边界

#与 ajv / zod 的 API 对应

#关于 WASM 性能

#开发

moon check                  # 静态检查
moon test                   # 运行测试（native）
moon test --target wasm-gc  # 运行测试（WASM-GC）
moon run cmd/demo           # 可运行示例
moon fmt && moon info       # 格式化 + 更新包接口

#路线图

• W1 引擎核心：编译器 + 校验器 + 错误模型 + $ref 惰性解析（双目标测试通过）
• W2 官方 JSON-Schema-Test-Suite 接入与跑分（974/975 判定通过，99.90%）；pattern / patternProperties（基于 core 正则引擎）；整数解析溢出修复（core 上游 bug workaround）
• W3 跨字段动态规则 DSL（x-rules + builder .satisfy()，编译期语法检查）；错误消息 i18n（中/英）；quickcheck 式 roundtrip 性质测试（种子化随机实例 ×1100）
• W4 Node 基准测试报告（vs ajv/zod，编译期快 8×）；浏览器 Playground（JS 后端 ESM 导出，含宿主集成 API）
• 后续 wasm-gc 字符串边界（JS-string-builtins）；校验吞吐优化（错误结构/查找路径）；mooncakes 发布

#License