44-EFT.WP.Data.ModelCards v1.0 | Chapter 15 Machine-readable Schema & Lint

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

Chapter 15 Machine-readable Schema & Lint

I. Chapter Purpose & Scope

.no Chinese for Model Cards, covering structure/type/regex/dependencies/citation anchors/dimensional checks/frozen splits/leakage prevention/minimal fairness & robustness checks; artifacts are ready for pre-release blocking checks and portal auto-validation. Keys use snake_case; cross-volume citations use “Volume vX.Y:Anchor”; math uses backticks with parentheses and Lint ruleset and normative JSON SchemaProvide the

II. Normative Artifacts (Release-Critical)

artifacts:

- path: "schema/model_card.schema.json"

- path: "schema/lint_rules.yaml"

- path: "schema/examples/minimal.yaml"

- path: "schema/examples/full.yaml"

These artifacts must be listed in export_manifest.artifacts[] with sha256; citation anchors follow this volume’s posture.

III. Normative JSON Schema (Core Excerpt)

JSON json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://eift.org/schema/model_card.schema.json",
  "title": "EFT Model Card",
  "type": "object",
  "required": [
    "model_id",
    "title",
    "version",
    "task",
    "io_schema",
    "architecture",
    "training_data",
    "preprocess",
    "optimization",
    "hyperparams",
    "evaluation",
    "calibration",
    "robustness",
    "fairness",
    "safety",
    "deployment",
    "resources",
    "export_manifest"
  ],
  "properties": {
    "model_id": { "type": "string", "pattern": "^[a-z0-9_\\-\\.]+$" },
    "title": { "type": "string", "minLength": 3 },
    "version": { "type": "string", "pattern": "^v\\d+\\.\\d+(\\.\\d+)?$" },
    "task": { "type": "string" },
    "io_schema": {
      "type": "object",
      "required": [ "inputs", "outputs" ],
      "properties": {
        "inputs": { "type": "array", "items": { "type": "object" } },
        "outputs": { "type": "array", "items": { "type": "object" } },
        "batching": { "type": "object" },
        "streaming": { "type": "object" },
        "constraints": { "type": "array", "items": { "type": "object" } }
      }
    },
    "architecture": { "type": "object", "required": [ "version", "backbone", "topology" ] },
    "training_data": {
      "type": "object",
      "required": [ "refs", "splits_ref" ],
      "properties": {
        "refs": { "type": "array", "items": { "type": "string" } },
        "splits_ref": { "type": "string" }
      }
    },
    "preprocess": {
      "type": "object",
      "required": [ "pipeline_id", "steps", "parameter_lock" ],
      "properties": { "steps": { "type": "array", "items": { "type": "object" } } }
    },
    "optimization": { "type": "object" },
    "hyperparams": { "type": "object" },
    "evaluation": {
      "type": "object",
      "required": [ "protocol", "metrics" ],
      "properties": {
        "protocol": { "type": "object", "properties": { "splits": { "type": "string", "const": "frozen" } } },
        "metrics": { "type": "object" }
      }
    },
    "calibration": { "type": "object" },
    "robustness": { "type": "object" },
    "fairness": { "type": "object" },
    "safety": { "type": "object" },
    "deployment": { "type": "object" },
    "resources": {
      "type": "object",
      "properties": {
        "M_param": { "type": "number" },
        "FLOPs": { "type": "number" },
        "T_inf": { "type": "number" }
      }
    },
    "export_manifest": {
      "type": "object",
      "required": [ "version", "artifacts", "references" ],
      "properties": {
        "version": { "type": "string" },
        "artifacts": { "type": "array", "items": { "type": "object" } },
        "references": {
          "type": "array",
          "minItems": 1,
          "items": { "type": "string", "pattern": "^[^:]+ v\\d+\\.\\d+:[A-Z].+$" }
        }
      }
    },
    "see": { "type": "array", "items": { "type": "string" } }
  },
  "additionalProperties": false
}
The references[] regex enforces “Volume vX.Y:Anchor”; evaluation.protocol.splits is fixed to "frozen"; resources units are validated by the Metrology chapter.

IV. Lint Rules (Normative)

version: "v1.0"

rules:

- id: STRUCT.REQUIRED

when: "$"

assert: "has_keys(model_id,title,version,task,io_schema,architecture,training_data,preprocess,optimization,hyperparams,evaluation,calibration,robustness,fairness,safety,deployment,resources,export_manifest)"

level: error

- id: VERSION.SEMVER

when: "$.version"

assert: "matches('^v\\d+\\.\\d+(\\.\\d+)?$')"

level: error

- id: EVAL.SPLITS_FROZEN

when: "$.evaluation.protocol.splits"

assert: "value == 'frozen'"

level: error

- id: REFERENCES.FORMAT

when: "$.export_manifest.references[*]"

assert: "matches('^[^:]+ v\\d+\\.\\d+:[A-Z].+$')"

level: error

- id: METROLOGY.SI_AND_CHECKDIM

when: "$.resources"

assert: "exists($.metrology) ? ($.metrology.units=='SI' and $.metrology.check_dim==true) : true"

level: error

see: ["EFT.WP.Core.Metrology v1.0:check_dim"]

- id: IO.SOFTMAX_RANGE

when: "$.io_schema.outputs[?(@.semantics=='softmax')]"

assert: "all(_.range == '[0,1]' for _ in items)"

level: error

- id: IO.SHAPE_NONEMPTY

when: "$.io_schema.inputs[*].shape"

assert: "matches('^\\(')"

level: error

- id: TD.REFS_REQUIRED

when: "$.training_data"

assert: "len(refs) > 0 and splits_ref"

level: error

- id: TD.LEAKAGE_GUARDS

when: "$.training_data.leakage_guards"

assert: "contains_any(['per-object','per-timewindow','per-scene'])"

level: warn

- id: FAIRNESS.THRESHOLD

when: "$.fairness.threshold"

assert: "value <= 0.10"

level: warn

- id: ROBUSTNESS.DROP_MAX

when: "$.robustness.thresholds.drop_rel_max"

assert: "value <= 0.20"

level: warn

- id: MATH.NO_CHINESE

when: "$"

assert: "no_chinese_in_math()"

level: warn

- id: SYMBOLS.CONFLICT

when: "$"

assert: "not_mixed(['T_fil','T_trans']) and not_mixed(['n','n_eff'])"

level: error

Blocking rules: STRUCT.REQUIRED, EVAL.SPLITS_FROZEN, REFERENCES.FORMAT, METROLOGY.SI_AND_CHECKDIM, SYMBOLS.CONFLICT.

V. Failure Examples & Diagnostics (Excerpt)

fail_examples:

- case: "invalid reference"

input: {export_manifest:{references:["Core.DataSpec:EXPORT"]}}

expect: {rule:"REFERENCES.FORMAT", level:"error",

fix:"Use 'EFT.WP.Core.DataSpec v1.0:EXPORT'"}

- case: "splits not frozen"

input: {evaluation:{protocol:{splits:"custom"}}}

expect: {rule:"EVAL.SPLITS_FROZEN", level:"error",

fix:"Set evaluation.protocol.splits to 'frozen'"}

- case: "missing metrology check"

input: {resources:{M_param:25.6, FLOPs:4.1e9, T_inf:3.8}}

expect: {rule:"METROLOGY.SI_AND_CHECKDIM", level:"error",

fix:"Add metrology {units:'SI', check_dim:true}"}

.fix hintsLint reports must include rule, path, message, and

VI. Minimal Working Example (Validates)

model_id: "eift.vision.cls.resnet50"

title: "ResNet50 Classifier"

version: "v1.0"

task: "classification"

io_schema:

inputs: [{name:"image", shape:"(H,W,3)", dtype:"uint8", range:"[0,255]"}]

outputs: [{name:"probs", shape:"(K,)", dtype:"float32", range:"[0,1]", semantics:"softmax"}]

batching: {mode:"dynamic", max_batch:128}

architecture: {version:"v1.0", backbone:"resnet50", topology:[{name:"stem", type:"conv"}]}

training_data: {refs:["EFT.WP.Data.DatasetCards v1.0:Ch.11"], splits_ref:"eift.obs.demo@v1.0"}

preprocess: {pipeline_id:"img-prep-v1", steps:[], parameter_lock:true}

optimization: {objective:{name:"cross_entropy"}}

hyperparams: {batch_size:256, epochs:200}

evaluation:

protocol: {splits:"frozen", seeds:[0,1,2,3,4], repeats:5}

metrics: {classification:["f1_macro","roc_auc","ece","brier"]}

calibration: {method:"temperature", params:{t:1.7}}

robustness: {thresholds:{drop_rel_max:0.10}}

fairness: {axes:["class","region"], gap_metric:"abs_diff", threshold:0.05}

safety: {allowed_use:["academic"], prohibited_use:["surveillance"]}

deployment: {forms:["rest"], devices:["A100"], latency_targets_ms:{p50:5}}

resources: {M_param:25.6, FLOPs:4.1e9, T_inf:3.8}

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

export_manifest:

version: "v1.0"

artifacts: [{path:"model_card.yaml", sha256:"..."}]

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

VII. Coupling with Export Manifest (Normative)

export_manifest:

artifacts:

- {path:"schema/model_card.schema.json", sha256:"..."}

- {path:"schema/lint_rules.yaml", sha256:"..."}

- {path:"schema/examples/minimal.yaml", sha256:"..."}

references:

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

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

and must be listed and verifiable; references carry “Volume vX.Y:Anchor”.blocking artifactsSchema and Lint are

VIII. Validation Interfaces (Implementation Binding Ixx-?)

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

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

def check_units(card: dict) -> dict: ... # uses Core.Metrology v1.0:check_dim

def verify_references(card: dict) -> dict: ...# regex + anchor reachability

Returns {"ok": bool, "errors":[...], "warnings":[...], "metrics":{...}} for portal/CI.

IX. Chapter Compliance Checklist

Copyright & License (CC BY 4.0)

Copyright: Unless otherwise noted, the copyright of “Energy Filament Theory” (text, charts, illustrations, symbols, and formulas) belongs to the author “Guanglin Tu”.
License: This work is licensed under the Creative Commons Attribution 4.0 International (CC BY 4.0). You may copy, redistribute, excerpt, adapt, and share for commercial or non‑commercial purposes with proper attribution.
Suggested attribution: Author: “Guanglin Tu”; Work: “Energy Filament Theory”; Source: energyfilament.org; License: CC BY 4.0.

First published： 2025-11-11｜Current version：v5.1
License link：https://creativecommons.org/licenses/by/4.0/