yovision/contracts/runtime-status/v1/runtime-status.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://yovision.local/contracts/runtime-status/v1/runtime-status.schema.json",
  "title": "YoVision Brain runtime status v1",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "status_id",
    "brain_instance_ref",
    "sequence",
    "observed_at",
    "runtime",
    "model",
    "configurations",
    "health",
    "inputs"
  ],
  "properties": {
    "schema_version": { "const": "yovision.runtime-status/v1" },
    "status_id": {
      "type": "string",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
    },
    "brain_instance_ref": { "$ref": "#/$defs/logicalRef" },
    "sequence": { "type": "integer", "minimum": 0 },
    "observed_at": { "type": "string", "format": "date-time" },
    "runtime": {
      "type": "object",
      "additionalProperties": false,
      "required": ["state", "version"],
      "properties": {
        "state": { "$ref": "#/$defs/runtimeState" },
        "version": { "$ref": "#/$defs/version" },
        "started_at": { "type": ["string", "null"], "format": "date-time" }
      }
    },
    "model": {
      "type": "object",
      "additionalProperties": false,
      "required": ["model_ref", "version"],
      "properties": {
        "model_ref": { "$ref": "#/$defs/logicalRef" },
        "version": { "$ref": "#/$defs/version" }
      }
    },
    "configurations": {
      "type": "array",
      "maxItems": 4096,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["config_id", "apply_state", "applied_revision", "error_code"],
        "properties": {
          "config_id": { "$ref": "#/$defs/configId" },
          "apply_state": {
            "type": "string",
            "enum": ["not_configured", "applying", "applied", "rejected"]
          },
          "applied_revision": {
            "type": ["integer", "null"],
            "minimum": 1
          },
          "error_code": { "$ref": "#/$defs/nullableErrorCode" }
        },
        "allOf": [
          {
            "if": {
              "required": ["apply_state"],
              "properties": { "apply_state": { "const": "not_configured" } }
            },
            "then": { "properties": { "applied_revision": { "type": "null" } } }
          },
          {
            "if": {
              "required": ["apply_state"],
              "properties": { "apply_state": { "const": "applied" } }
            },
            "then": { "properties": { "applied_revision": { "type": "integer", "minimum": 1 } } }
          },
          {
            "if": {
              "required": ["apply_state"],
              "properties": { "apply_state": { "const": "rejected" } }
            },
            "then": { "properties": { "error_code": { "$ref": "#/$defs/errorCode" } } }
          }
        ]
      }
    },
    "health": {
      "type": "object",
      "additionalProperties": false,
      "required": ["overall", "error_codes", "metrics"],
      "properties": {
        "overall": {
          "type": "string",
          "enum": ["healthy", "degraded", "unhealthy"]
        },
        "error_codes": {
          "type": "array",
          "uniqueItems": true,
          "maxItems": 32,
          "items": { "$ref": "#/$defs/errorCode" }
        },
        "metrics": { "$ref": "#/$defs/metrics" }
      }
    },
    "inputs": {
      "type": "array",
      "maxItems": 4096,
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["input_ref", "state", "error_codes", "metrics"],
        "properties": {
          "input_ref": { "$ref": "#/$defs/logicalRef" },
          "state": { "$ref": "#/$defs/runtimeState" },
          "error_codes": {
            "type": "array",
            "uniqueItems": true,
            "maxItems": 16,
            "items": { "$ref": "#/$defs/errorCode" }
          },
          "metrics": { "$ref": "#/$defs/metrics" }
        }
      }
    }
  },
  "$defs": {
    "configId": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._~-]*$"
    },
    "logicalRef": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
    },
    "version": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$"
    },
    "runtimeState": {
      "type": "string",
      "enum": ["unconfigured", "starting", "running", "degraded", "failed", "stopped"]
    },
    "errorCode": {
      "type": "string",
      "pattern": "^[A-Z][A-Z0-9_]{2,63}$"
    },
    "nullableErrorCode": {
      "type": ["string", "null"],
      "pattern": "^[A-Z][A-Z0-9_]{2,63}$"
    },
    "metrics": {
      "type": "object",
      "additionalProperties": false,
      "required": ["load_percent", "queue_depth", "latency_ms"],
      "properties": {
        "load_percent": { "type": "number", "minimum": 0, "maximum": 100 },
        "queue_depth": { "type": "integer", "minimum": 0 },
        "latency_ms": { "type": "number", "minimum": 0 }
      }
    }
  }
}