@ appport/ schema

Schema适配器和JSON Schema生成,用于AppPort能力.

AppPort在电线上发布 JSON Schema , 从而可以从 TypeScript, Rust, Go, Python 或 Swift (英语). 在 TypeScript 中,您可以编写三套方案 方法,和所有三个发布 同样的事情.

import { s, fromJSONSchema, fromStandardSchema, toSchema } from "@appport/schema";

// 1. the built-in builder: validation and JSON Schema from one definition
const input = s.object({ documentId: s.string(), title: s.optional(s.string()) });

// 2. any Standard Schema library (Zod, Valibot, ArkType)
const zodInput = fromStandardSchema(zodSchema, { jsonSchema: z.toJSONSchema(zodSchema) });

// 3. a raw JSON Schema document, validated at runtime
const published = fromJSONSchema({ type: "object", required: ["documentId"] });

fromJSONSchema 是让生成的客户端对已发布的进行校验的内容 与原始定义相同的能力a 第三方执行已经.

构建者覆盖了字符串,数字,整数,布尔斯,虚数,字形,enums, 数组、对象、记录、结合、可选、可失效、时间戳和二进制 参考文献,并附有全部类型推论:

type Input = Infer<typeof input>; // { documentId: string; title?: string }

语义说明

JSON Schema说价值的形状是什么,而不是它的含义: 90 是有效的数字 无论是分钟还是小时. annotate 发表 x-appport-* 关键词 说一个字段是什么,而不改变它是如何验证的:

import { annotate, s, semantic } from "@appport/schema";

const estimatedHours = annotate(
  s.number({ minimum: 0 }),
  semantic({ concept: "https://vocab.example.org/work-order#effort", unit: "h" })
);
const priority = annotate(s.enum(["low", "urgent"]), semantic({
  enumConcepts: { low: "https://vocab.example.org/urgency#low", urgent: "https://vocab.example.org/urgency#high" }
}));

仅 x- 键被接受, x-appport-* 立即检查值(概念是 绝对IRI,单位没有空白, enumConcepts 名称已声明enum值, encoding 实值 iso8601, (中文(简体) ), epoch-seconds 或者说 epoch-milliseconds),可选性是 保留了下来 见 spec/appport-1.0.md 第15.3.节.