告别200行JSON Schema：他们重新发明了数据校验

凌晨两点，你盯着屏幕上那条报错信息——#/properties/items/allOf/0/then/Then。它指向的字段，和你脑子里想的那个字段，根本对不上号。这是JSON Schema的老毛病：写的时候痛苦，报错的时候更痛苦。

一支团队决定从头来过。他们没有修补旧工具，而是造了个新东西：Okyline。核心思路很直白——用同事能听懂的方式描述数据，让机器自己去推规则。

从"写合同"到"举例子"

传统JSON Schema的问题，用过的人都知道。条件逻辑一多，交叉字段规则一杂，200行代码就这么堆出来了。团队最后往往放弃手写，改成代码生成——结果还是200行，只是现在没人看得懂。

Okyline的解法：别写Schema了，直接包一个JSON示例。

{"$oky": {"orderId": "ORD-20250107","customer": {"id": 42,"email": "alice@example.com"},"items": ["sku": "PRD-00123","quantity": 2,"unitPrice": 79.99,"lineTotal": 159.98],"total": 170.36}

包裹在$oky里的就是完整契约。引擎从值本身推断类型：id是整数，email是字符串，items是特定形状的对象数组。零语法学习成本，结构校验和类型检查已经生效。

注解写在字段名上，值保持干净

需要加约束？注解跟在字段名后面，示例值不动。

{"$oky": {"orderId|@ ~$OrderId~|Order identifier": "ORD-20250107","customer|@": {"id|@ # (>0)": 42,"email|@ ~$Email~": "alice@example.com"},"items|@ [1,50] -> !": ["sku|@ # ~$Sku~": "PRD-00123","quantity|@ (1..999)": 2,"unitPrice|@ (>0)": 79.99,"lineTotal|(>0)": 159.98],"total|@ (>0)": 170.36},"$format": {"OrderId": "^ORD-[0-9]{8}$","Sku": "^[A-Z]{3}-[0-9]{5}$"}

逐字段拆解这套语法：

orderId|@ ~$OrderId~|Order identifier：必填（@），必须匹配底部$format定义的$OrderId正则，标签为"Order identifier"。

items|@ [1,50] -> !：必填，数组长度1到50。->运算符引入元素级约束，!表示按关键字段（#）去重。

这个去重设计直击JSON Schema的盲区。JSON Schema的uniqueItems: true比较整个对象——同一SKU不同数量，它认为是两个不同项，放行。库存被扣两次，发票出错，Schema却一声不吭。Okyline的按字段去重：同一SKU出现两次，直接报校验错误。

渐进式采用的实战路径

团队用电商订单做了完整演示。第一步只包$oky，拿基础类型检查。第二步字段级注解，加业务规则。第三步提取复合格式到$format，避免重复。

关键设计决策：注解和值分离。读代码的人看到干净示例，维护的人看到完整约束，两不耽误。错误信息指向的是orderId、items[0].sku这种人类能理解的字段名，不是机器生成的路径片段。

为什么这事值得关注

数据校验工具的竞争，本质是人机接口的竞争。JSON Schema赢了标准化，却在开发者体验上输了——写起来累，读起来懵，报错时抓狂。

Okyline的赌注是：大多数场景下，"举个好例子"比"写份完整规范"更可持续。团队不需要Schema专家，需要的是能看懂自己数据结构的普通开发者。

如果你现在正维护着一份200行、没人敢动的JSON Schema，或者每次调试报错都在玩"路径猜谜游戏"——这是值得盯一盯的方向。工具链的迭代周期正在缩短，谁先把"写契约"的心智负担打下来，谁就能吃掉下一波API标准化红利。