50-参数注册卡 Template v1.0 | 第9章 数据契约与接口（Schema 与 API）

目录 ／ 文档-技术白皮书 ／ 50-参数注册卡 Template v1.0

第9章 数据契约与接口（Schema 与 API）

I. 目的与范围（Purpose & Scope）

• 定义参数注册卡的**数据契约（Schema）与服务接口（API）**统一规范，覆盖字段模式、序列化格式、校验规则、查询/解析/导出与版本锁定，确保跨链路集成与发布合规。
• 涉及路径量（到达时/相位）时，正文显式 gamma(ell) 与测度 d ell，并在卡片数据侧记录 delta_form ∈ {general, factored}；对外发布要求 p_dim = 1.0。

II. 前置条件与输入（Prerequisites & Inputs）

• 控制式与引用：参与该参数的目标量与控制式已在卡中以“卷名 + 版本 + 锚点（P/S/M/I）”明确引用。
• 量纲与新鲜度：I70-dim_check 通过并生成 check_dim_report.json；freshness{valid_from,valid_to,policy} 完整。
• 协方差与覆盖：如参与不确定度传播，uncertainty{type, estimate, distribution, coverage} 与 cov_group 已登记。

III. 数据契约（核心 Schema）

• 文件形态：param_card.yaml/json（单卡），param_registry.csv（注册表），params_schema.json（模式）。
• 卡片最小字段：
  param_id, name, symbol, domain{type,unit,range/default,precision,shape?}, lineage{…}, freshness{…}, uncertainty{…}, cov_group, constraints{depends_on,derived,…}, status, see[], references[], version。
• 路径型附加块：
  path{ gamma: "gamma(ell)", measure: "d ell", delta_form: "general|factored" }（与 domain.shape 对齐）。

params_schema.json（节选）

{

"$schema": "https://json-schema.org/draft/2020-12/schema",

"title": "param_card v1.0.0",

"type": "object",

"required": ["param_id","symbol","domain","status","version","see"],

"properties": {

"param_id": {"type":"string","pattern":"^[A-Z]{3}-\\d{2}(-[A-Za-z_]{1,16})?$"},

"symbol": {"type":"string"},

"domain": {

"type":"object",

"required":["type","unit"],

"properties":{

"type":{"enum":["real","integer","enum","array","tensor","boolean"]},

"unit":{"type":"string"},

"range":{"type":"array","items":{"type":"number"},"minItems":2,"maxItems":2},

"values":{"type":"array","items":{"type":["string","number","boolean"]}},

"default":{},

"precision":{"type":"string"},

"shape":{"type":"array","items":{"type":["integer","string"]}}

}

},

"lineage":{"type":"object"},

"freshness":{"type":"object"},

"uncertainty":{"type":"object"},

"cov_group":{"type":"string"},

"constraints":{"type":"object"},

"path":{"type":"object"},

"status":{"enum":["draft","stable","deprecated"]},

"see":{"type":"array","items":{"type":"string"},"minItems":1},

"version":{"type":"string"}

}

}

IV. API 契约（OpenAPI 片段，REST）

• 基址：/api/v1/params；内容类型 application/json。
• 鉴权：Bearer 或 mTLS；只读端点可匿名（可选），写入端点需审计。

openapi: 3.0.3

info: { title: "Param Registry API", version: "1.0.0" }

servers: [{ url: "https://registry.example.com/api/v1" }]

paths:

/params:

get:

summary: "List parameter cards"

parameters:

- { in: query, name: cat, schema: { type: string, enum: [PHY,CAL,ALG,ENV,GEO,TIM,IO,SEC] } }

- { in: query, name: status, schema: { type: string, enum: [draft,stable,deprecated] } }

- { in: query, name: cov_group, schema: { type: string } }

responses:

"200": { description: OK }

/params/{param_id}:

get:

summary: "Get parameter card"

parameters: [{ in: path, name: param_id, required: true, schema: { type: string } }]

responses:

"200": { description: OK }

"404": { description: Not Found }

/params:

post:

summary: "Register/Update parameter card"

requestBody: { required: true, content: { application/json: { schema: { $ref: "#/components/schemas/ParamCard" } } } }

responses:

"201": { description: Created }

/params/{param_id}/validate:

post:

summary: "Validate against gates & schema"

requestBody: { required: true, content: { application/json: { schema: { type: object, properties: { gates: { type: array, items: { type: string } } } } } } }

responses: { "200": { description: "Validation report" } }

/params/{param_id}/lock:

post:

summary: "Lock version (immutable tag)"

responses: { "200": { description: "Locked" } }

components:

schemas:

ParamCard:

type: object

required: ["param_id","symbol","domain","status","version","see"]

properties:

param_id: { type: string }

symbol: { type: string }

domain: { $ref: "#/components/schemas/Domain" }

lineage: { type: object }

freshness:{ type: object }

uncertainty:{ type: object }

cov_group:{ type: string }

constraints:{ type: object }

path: { type: object }

status: { type: string }

see: { type: array, items: { type: string } }

references: { type: array, items: { type: string } }

version: { type: string }

Domain:

type: object

properties:

type: { type: string }

unit: { type: string }

range: { type: array, items: { type: number } }

default: {}

precision: { type: string }

shape: { type: array, items: { type: string } }

V. 典型端点与语义（Endpoints & Semantics）

• 查询（GET /params）：按 cat/status/cov_group 过滤；返回分页与摘要字段。
• 获取（GET /params/{param_id}）：返回完整卡片与 check_dim_report.json 的引用。
• 注册/更新（POST /params）：写入前执行模式校验与 I70-dim_check；失败返回具体字段错误。
• 校验（POST /params/{param_id}/validate）：执行 G1–G8 与 S1–S5 映射，返回合规报告（JSON）。
• 锁定（POST /params/{param_id}/lock）：生成不可变标签（回滚锚点）；写入 audit.jsonl。

VI. 合规与质量门（Compliance & Gates）

• G4｜量纲闭合：新/改卡在持久化前必须附 check_dim_report.json 且 p_dim = 1.0。
• G2｜引用合规：see[]/references[] 使用“卷名+版本+锚点”，锚点直指率 ≥ 90%，无外链/别名。
• G8｜唯一性：param_id 唯一；注册表 checksum 不重复；血缘图无环。
• G5｜新鲜度：valid_to 未过期且 clock_state="locked"；超期拒绝写入或强制再标定。

VII. 数据示例与失败样例（Normative / Anti-Patterns）

# 正例：含路径块且量纲闭合

param_id: "PHY-03-n_eff_profile"

symbol: "n_eff(ell)"

domain: { type: "array", unit: "1", shape: ["N"], range: [0.8, 2.5], precision: "float64" }

path: { gamma: "gamma(ell)", measure: "d ell", delta_form: "general" }

uncertainty: { type: "A/B", estimate: 3.0e-3, distribution: "gaussian", coverage: { k: 2 } }

cov_group: "medium"

see: ["EFT.WP.Core.Equations v1.1:S20-1","EFT.WP.Core.Metrology v1.0:check_dim"]

# 反例：缺少测度与 delta_form（应拒绝）

param_id: "PHY-XX-bad"

symbol: "n_eff(ell)"

domain: { type: "array", unit: "1" }

path: { gamma: "gamma(ell)" } # 缺 measure / delta_form

VIII. 事件与审计（Events & Audit）

• 事件模型：created|updated|validated|locked|deprecated|rolled_back；每次事件写入 audit.jsonl（时间戳、操作者、输入哈希、签名、说明）。
• 签名与校验：响应载荷携带 checksum（sha256）；发布包包含 SIGNATURE.asc。

IX. 导出与发布（Exports & Release）

• 导出清单：report_manifest.yaml 列出 cards/graphs/reports/configs 与文件哈希。
• 目录结构：与 PTN_EXPORT/ 对齐；卡片、模式、报告、图谱与签名分目录管理；禁止裸散文件。

X. 交叉引用（Cross-References）

• 分类与命名：见第3章；域与单位：见第4章；血缘：见第5章；版本与新鲜度：见第6章；约束与派生：见第7章；不确定度与协方差：见第8章。
• 误差预算卡：协方差与传播（Ch.5/Ch.6）、阈值映射（Ch.9）。
• 数据规范：EFT.WP.Core.DataSpec v1.0:TARR；结果页与发布：PTN Template 第5/11章。

XI. 执行勾选清单（Checklist）

• params_schema.json 与 openapi 片段一致；必填字段完整。
• 路径量显式 gamma(ell)、d ell，并记录 delta_form；len(path) ≥ 2、Δell 合规。
• I70-dim_check 通过并附 check_dim_report.json；p_dim = 1.0。
• 端点 /validate 返回 G1–G8/S1–S5 判定；/lock 已可用并记入审计。
• see[]/references[]/version 合规（锚点直指率 ≥ 90%）；注册表唯一性通过、血缘无环。
• 发布包包含 param_card.yaml/json、params_schema.json、report_manifest.yaml、audit.jsonl 与签名。