44-EFT.WP.Data.ModelCards v1.0 | Chapter 16 Implementation Binding & Validation API

Home ／ Docs-Technical WhitePaper ／ 44-EFT.WP.Data.ModelCards v1.0

Chapter 16 Implementation Binding & Validation API

I. Chapter Purpose & Scope

II. Service Surface (Normative)

services:

modelcards.v1:

- POST /api/v1/validate_model_card

- POST /api/v1/lint_model_card

- POST /api/v1/check_units

- POST /api/v1/verify_references

- POST /api/v1/split_freeze_check

- POST /api/v1/leakage_audit

- POST /api/v1/eval_run

- POST /api/v1/eval_significance

- POST /api/v1/calibration_eval

- POST /api/v1/robustness_eval

- POST /api/v1/fairness_eval

- POST /api/v1/score

- POST /api/v1/calibrate

- POST /api/v1/explain

- POST /api/v1/hash_artifact

- POST /api/v1/sign_artifact

- POST /api/v1/publish_release

- POST /api/v1/revoke_release

III. Common Request/Response & Auth

request_envelope:

headers:

Authorization: "Bearer <oidc-token> | HMAC <key>:<sig>"

x-eift-idempotency: "<uuid>"

content-type: "application/json"

body:

card: { ... }

artifacts?: [{path, bytes_b64?, sha256?}]

options?: {dry_run?: true, strict?: true}

response_envelope:

status: "ok" | "warn" | "error"

errors: [{code, message, path?, see?}]

warnings:[{code, message, path?, see?}]

metrics: { ... }

version: "modelcards.v1"

security:

auth: "OIDC bearer | HMAC"

tls: "TLS1.2+"

scope: ["validate","evaluate","publish","admin"]

rate_limits:

per_key_per_minute: 120

burst: 60

IV. Normative OpenAPI Excerpt

openapi: 3.0.3

info: {title: "EFT ModelCards API", version: "v1"}

paths:

/api/v1/validate_model_card:

post:

summary: Validate Model Card against schema & cross-volume constraints

requestBody:

required: true

content: {"application/json": {schema: {$ref: "#/components/schemas/CardEnvelope"}}}

responses:

"200": {description: "Result", content: {"application/json": {schema: {$ref: "#/components/schemas/Result"}}}}

/api/v1/check_units:

post:

summary: Dimensional/unit consistency check (Metrology v1.0)

responses: {"200": {content: {"application/json": {schema: {$ref: "#/components/schemas/Result"}}}}}

/api/v1/score:

post:

summary: Bind model scoring I/O with io_schema (Chapter 6)

responses: {"200": {content: {"application/json": {schema: {$ref: "#/components/schemas/ScoreResult"}}}}}

components:

schemas:

CardEnvelope: {type: object, required: [card], properties: {card: {}}}

Result:

type: object

properties:

status: {type: string, enum: [ok, warn, error]}

errors: {type: array, items: {$ref: "#/components/schemas/Issue"}}

warnings:{type: array,items: {$ref: "#/components/schemas/Issue"}}

metrics: {type: object}

ScoreResult:

type: object

properties: {outputs: {type: object}, latency_ms: {type: number}}

Issue:

type: object

properties:

code: {type: string}

message: {type: string}

path: {type: string}

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

V. Endpoint Semantics (Essentials)

• /validate_model_card (blocking): structure, type/regex, export_manifest.references[] format, minimal metrology set, frozen-split flag; returns status="error" on blockers.
• /lint_model_card: run Chapter 15 rules—ratios/leakage, symbol conflict, no-Chinese-in-math, softmax range, etc.
• /check_units: enforce units="SI", check_dim=true, and vector/tensor unit coherence.
• /verify_references: validate "^[^:]+ v\\d+\\.\\d+:[A-Z].+$" and optional anchor reachability (catalog/index).
• /split_freeze_check: ratios sum to 1±1e-6, indices are frozen, consistent with training_data.splits_ref.
• /leakage_audit: de-duplicate by object/timewindow/scene; cross-split leakage is blocking.
• /eval_run & /eval_significance: execute per Chapter 11 and return CIs and significance (permutation/bootstrap).
• /calibration_eval: return ECE/Brier/curve and coverage; align with Chapter 12.
• /robustness_eval//fairness_eval: run shift/adversarial/fairness items against thresholds.
• /score//calibrate//explain: keep I/O aligned with Chapter 6 io_schema and Chapter 7 architecture; /explain may return heatmaps/importances.
• /hash_artifact//sign_artifact: compute sha256 and sign/verify; cross-check with export manifest.
• /publish_release//revoke_release: follow Chapter 14 versioning & tombstoning.

VI. Error Codes (Normative)

errors:

- {code:"ESCHEMA001", message:"missing required field", path:"$.title"}

- {code:"EREF001", message:"invalid reference format", path:"$.export_manifest.references[2]"}

- {code:"EMETR001", message:"units must be SI and check_dim=true", path:"$.metrology"}

- {code:"ESPLIT001", message:"ratios must sum to 1±1e-6", path:"$.evaluation.protocol"}

- {code:"ELEAK000", message:"cross-split leakage detected", path:"$.training_data.leakage_guards"}

- {code:"EIO001", message:"io_schema mismatch with deployment I/O", path:"$.io_schema"}

- {code:"EFAIR010", message:"fairness gap exceeds threshold", path:"$.fairness"}

- {code:"EROB010", message:"robustness drop exceeds threshold", path:"$.robustness"}

- {code:"ESIGN001", message:"artifact signature mismatch", path:"$.export_manifest.artifacts[0]"}

VII. Idempotency, Versioning & Compatibility

idempotency:

header: "x-eift-idempotency"

window_hours: 24

versioning:

api: "modelcards.v1" # breaking change → bump MAJOR

minor: "backward-compatible additions"

compatibility:

request_backward: "minor+patch"

response_fields: "additive only; no removals"

VIII. Security, Audit & Compliance

• Auth: OIDC/HMAC; Transport: TLS1.2+; Least privilege by scope.
• Audit: Log request_id, idempotency_key, caller, timestamps, summary; logs become compliance artifacts and appear in the export manifest.
• Compliance: Regional limits and data-subject rights map to Chapter 14; release/revoke maps to Chapter 14 policy.

IX. Machine-Readable Implementation Snippets (Ixx-?)

def validate_model_card(card: dict) -> dict: ...

def lint_model_card(card: dict, rules: dict) -> dict: ...

def check_units(card: dict) -> dict: ...

def verify_references(card: dict) -> dict: ...

def split_freeze_check(card: dict) -> dict: ...

def leakage_audit(card: dict) -> dict: ...

def eval_run(card: dict, seeds: list[int], repeats: int) -> dict: ...

def eval_significance(baseline: dict, contender: dict) -> dict: ...

def calibration_eval(card: dict) -> dict: ...

def robustness_eval(card: dict) -> dict: ...

def fairness_eval(card: dict) -> dict: ...

def score(inputs: dict) -> dict: ...

def calibrate(probs: list[float], method: str="temperature") -> dict: ...

def explain(inputs: dict, method: str="grad") -> dict: ...

def hash_artifact(path: str|bytes) -> dict: ...

def sign_artifact(path: str|bytes, key_id: str) -> dict: ...

def publish_release(card: dict, channel="stable") -> dict: ...

def revoke_release(tag: str, reason: str) -> dict: ...

X. Example Invocation (Ready-to-use)

curl -s -X POST https://api.eift.org/api/v1/validate_model_card \

-H "Authorization: Bearer <token>" \

-H "x-eift-idempotency: 7b7a0b1e-0a21-4f3f-9d0b-3b1e9b1f3c22" \

-H "Content-Type: application/json" \

-d '{"card": { "model_id":"eift.vision.cls.resnet50", "version":"v1.0",

"metrology":{"units":"SI","check_dim":true},

"evaluation":{"protocol":{"splits":"frozen"},"metrics":{}},

"export_manifest":{"version":"v1.0","artifacts":[],

"references":["EFT.WP.Core.DataSpec v1.0:EXPORT",

"EFT.WP.Core.Metrology v1.0:check_dim"]}}}'

XI. Coupling with Export Manifest (Normative)

export_manifest:

artifacts:

- {path:"api/openapi.yaml", sha256:"..."}

- {path:"api/clients/python.tar.gz", sha256:"..."}

references:

- "EFT.WP.Core.DataSpec v1.0:EXPORT"

- "EFT.WP.Core.Metrology v1.0:check_dim"