resource-control/schemas/resource-control-cycle.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://coulomb.social/resource-control/resource-control-cycle.schema.json",
  "title": "Immutable resource forecast or actual observation",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "schema_version",
    "record_id",
    "record_type",
    "resource_id",
    "resource_class",
    "period",
    "created_at",
    "usage_proxies",
    "capacity",
    "costs",
    "allocation",
    "service_constraints",
    "evidence"
  ],
  "properties": {
    "schema_version": {
      "enum": [
        "0.1",
        "0.2"
      ],
      "description": "0.2 permits null cost components for facts the authoritative repository has not supplied. Existing 0.1 records stay valid and are never rewritten; immutability applies to the record, not to the schema."
    },
    "record_id": {
      "type": "string",
      "minLength": 1
    },
    "record_type": {
      "enum": [
        "forecast",
        "actual"
      ]
    },
    "resource_id": {
      "type": "string",
      "pattern": "^resource:"
    },
    "resource_class": {
      "enum": [
        "storage",
        "vm",
        "cluster_compute",
        "shared_platform_service",
        "managed_service",
        "other"
      ]
    },
    "period": {
      "type": "string",
      "pattern": "^[0-9]{4}-(0[1-9]|1[0-2])$"
    },
    "created_at": {
      "type": "string",
      "format": "date-time"
    },
    "scenario": {
      "enum": [
        "low",
        "base",
        "high",
        "observed"
      ]
    },
    "forecast_ref": {
      "type": [
        "string",
        "null"
      ]
    },
    "revision_of": {
      "type": [
        "string",
        "null"
      ]
    },
    "usage_proxies": {
      "type": "object",
      "minProperties": 1,
      "additionalProperties": {
        "$ref": "#/$defs/measurement"
      }
    },
    "capacity": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "model",
        "provisioned",
        "used"
      ],
      "properties": {
        "model": {
          "enum": [
            "fixed",
            "elastic",
            "hybrid"
          ]
        },
        "provisioned": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/measurement"
          }
        },
        "used": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/measurement"
          }
        }
      }
    },
    "costs": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "currency",
        "infrastructure",
        "internal_labor",
        "external_labor",
        "total"
      ],
      "properties": {
        "currency": {
          "const": "EUR"
        },
        "infrastructure": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "EUR, or null when the amount is not yet known. Null is unknown, never zero."
        },
        "internal_labor": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "EUR, or null when the amount is not yet known. Null is unknown, never zero."
        },
        "external_labor": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "EUR, or null when the amount is not yet known. Null is unknown, never zero."
        },
        "total": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "EUR, or null when the amount is not yet known. Null is unknown, never zero."
        },
        "booked_cost_refs": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        }
      },
      "description": "Cost components split so a cheaper unit price that raises operator hours is visible. Any component may be null when the authoritative repository or fin-hub has not supplied it; total must then also be null, and variance for that component is reported as unknown."
    },
    "allocation": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "method",
        "driver",
        "method_version",
        "unattributed_eur"
      ],
      "properties": {
        "method": {
          "type": "string",
          "minLength": 1
        },
        "driver": {
          "type": "string",
          "minLength": 1
        },
        "method_version": {
          "type": "string",
          "minLength": 1
        },
        "unattributed_eur": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "EUR that reaches no consumer under the stated method, or null when the underlying cost itself is unknown. Null is unknown, never zero."
        },
        "unattributed_share": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "maximum": 1,
          "description": "Fraction of the allocation driver that reaches no consumer. Recordable from technical evidence alone, before any EUR amount exists."
        }
      }
    },
    "service_constraints": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/$defs/measurement"
      }
    },
    "uncertainty": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "level",
        "notes"
      ],
      "properties": {
        "level": {
          "enum": [
            "low",
            "medium",
            "high"
          ]
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "variance_attribution": {
      "type": "object",
      "additionalProperties": {
        "enum": [
          "demand",
          "provider_price",
          "allocation",
          "labor",
          "model",
          "data_quality"
        ]
      }
    },
    "evidence": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "string"
      }
    }
  },
  "$defs": {
    "measurement": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "value",
        "unit"
      ],
      "properties": {
        "value": {
          "type": [
            "number",
            "null"
          ],
          "minimum": 0,
          "description": "Null means the quantity is unknown or unbounded, never zero. A declared service constraint with a null value records that no objective exists yet."
        },
        "unit": {
          "type": "string",
          "minLength": 1
        }
      }
    }
  }
}