akcli

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://github.com/tipoLi5890/akcli/schemas/sim.schema.json",
  "title": "AkcliSimSpec",
  "description": "sim.json: stimuli/analyses for akcli sim, plus .meas-backed pass/fail assertions. Mirrors validation in akcli.sim.assertions.load().",
  "type": "object",
  "required": ["protocol_version"],
  "additionalProperties": false,
  "properties": {
    "protocol_version": { "type": "integer", "const": 1 },
    "stimuli": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["name"],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[A-Za-z][A-Za-z0-9_]*$",
            "description": "Stimulus identifier; becomes the SPICE element name, so it must be a bare identifier and unique across stimuli."
          }
        }
      },
      "default": []
    },
    "analyses": {
      "type": "object",
      "description": "ngspice analysis name (tran|ac|dc|op|...) -> its argument text, e.g. {\"tran\": \"5u 100m\", \"ac\": \"dec 40 10 100k\"}. An 'op' analysis runs but can carry NO assertions (ngspice cannot '.meas' an operating point); measure an operating point with a single-point 'dc' sweep instead, e.g. {\"dc\": \"Vsupply 3.3 3.3 1\"}.",
      "additionalProperties": { "type": "string" },
      "default": {}
    },
    "models": {
      "type": "object",
      "default": {}
    },
    "assert": {
      "type": "array",
      "items": { "$ref": "#/$defs/assert" },
      "default": []
    },
    "options": {
      "type": "object",
      "description": "Deck/engine tuning. Open-ended; 'rshunt' is validated by akcli.sim.assertions.load().",
      "properties": {
        "rshunt": {
          "description": "Floating-node fix. Absent or 'auto': add '.option rshunt=1e12' only when a floating node is detected. false: never. A number or non-'auto' string (e.g. '1e12', '1G'): always emit that value.",
          "oneOf": [
            { "type": "boolean" },
            { "type": "number" },
            { "type": "string" }
          ]
        }
      },
      "default": {}
    },
    "acknowledged_unmodeled": {
      "type": "array",
      "items": { "type": "string", "minLength": 1 },
      "description": "Designators the author explicitly accepts as absent from the deck (e.g. an IC with no vendor SPICE model). Downgrades that part's in-series SIM_PART_SKIPPED escalation from ERROR to WARNING — visible but non-blocking; unlisted parts keep the full ERROR. A stale entry (part modeled or gone) raises SIM_UNMODELED_ACK_UNUSED (NOTE).",
      "default": []
    }
  },
  "$defs": {
    "numOrEng": {
      "description": "A number, or an engineering-notation string (4.7k, 100n, 2M2, 25m, 1e-7, ...).",
      "oneOf": [
        { "type": "number" },
        { "type": "string" }
      ]
    },
    "assert": {
      "type": "object",
      "additionalProperties": false,
      "required": ["name"],
      "description": "One .meas-backed pass/fail check. Carries at least one bound: either a single 'approx', or a window — up to one lower (gt|ge) AND up to one upper (lt|le) bound.",
      "properties": {
        "name": { "type": "string", "minLength": 1 },
        "meas": {
          "type": "string",
          "description": "Verbatim text after 'meas <analysis> <name>', e.g. 'MAX v(peak) from=20m to=60m'."
        },
        "when": {
          "type": "string",
          "description": "Shorthand for a WHEN measurement, e.g. 'v(peak)=0.297 RISE=1' (emitted as 'meas <analysis> <name> WHEN <when>')."
        },
        "analysis": {
          "type": "string",
          "description": "Overrides the inferred analysis; must be a key of 'analyses', and must not be 'op' (rejected with SIM_OP_ASSERT_UNSUPPORTED — use a single-point 'dc' sweep or 'tran')."
        },
        "gt": { "$ref": "#/$defs/numOrEng", "description": "Lower bound: value must be strictly greater." },
        "lt": { "$ref": "#/$defs/numOrEng", "description": "Upper bound: value must be strictly less." },
        "ge": { "$ref": "#/$defs/numOrEng", "description": "Lower bound: value must be >=." },
        "le": { "$ref": "#/$defs/numOrEng", "description": "Upper bound: value must be <=." },
        "approx": { "$ref": "#/$defs/numOrEng", "description": "Two-sided ~equality; cannot be combined with gt/ge/lt/le." },
        "tol": {
          "$ref": "#/$defs/numOrEng",
          "description": "Relative tolerance for 'approx' (default 0.05 = 5%). Only valid together with 'approx'."
        }
      },
      "allOf": [
        {
          "anyOf": [
            { "required": ["gt"] }, { "required": ["ge"] },
            { "required": ["lt"] }, { "required": ["le"] },
            { "required": ["approx"] }
          ]
        },
        { "not": { "required": ["gt", "ge"] } },
        { "not": { "required": ["lt", "le"] } },
        {
          "if": { "required": ["approx"] },
          "then": {
            "not": {
              "anyOf": [
                { "required": ["gt"] }, { "required": ["ge"] },
                { "required": ["lt"] }, { "required": ["le"] }
              ]
            }
          }
        },
        { "if": { "required": ["tol"] }, "then": { "required": ["approx"] } }
      ]
    }
  }
}