atlas-iac/services/hermes/contracts/hux/identity.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://hermes.bstein.dev/contracts/hux/v1/identity.schema.json",
  "title": "HUX identity, capability negotiation and data manifest",
  "description": "HUX-11 foundation records. capabilities is the first call every client makes: it learns the contract version, which cards are on for this tenant (a card is on only when its whole dependency chain is on), and the server build. manifest is stored on the tenant PVC and tells a rolled-back reader whether it can read the data.",
  "$defs": {
    "capabilities": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "contract_version",
        "identity",
        "cards",
        "server"
      ],
      "properties": {
        "schema": {
          "const": "hux.capabilities.v1"
        },
        "contract_version": {
          "$ref": "common.schema.json#/$defs/contract_version"
        },
        "identity": {
          "$ref": "common.schema.json#/$defs/identity"
        },
        "cards": {
          "type": "array",
          "items": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "card",
              "flag",
              "enabled",
              "routes"
            ],
            "properties": {
              "card": {
                "type": "string",
                "pattern": "^HUX-[0-9]{2}$"
              },
              "flag": {
                "type": "string",
                "pattern": "^hux\\.[a-z_]+$"
              },
              "enabled": {
                "type": "boolean"
              },
              "routes": {
                "type": "array",
                "items": {
                  "type": "string",
                  "pattern": "^/hux/v1/"
                }
              }
            }
          }
        },
        "server": {
          "$ref": "common.schema.json#/$defs/build"
        }
      }
    },
    "manifest": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "contract_version",
        "data_layout_version",
        "min_reader_contract_version",
        "created_at",
        "updated_at"
      ],
      "properties": {
        "schema": {
          "const": "hux.manifest.v1"
        },
        "contract_version": {
          "$ref": "common.schema.json#/$defs/contract_version"
        },
        "data_layout_version": {
          "type": "integer",
          "minimum": 1
        },
        "min_reader_contract_version": {
          "$ref": "common.schema.json#/$defs/contract_version"
        },
        "created_at": {
          "$ref": "common.schema.json#/$defs/timestamp"
        },
        "updated_at": {
          "$ref": "common.schema.json#/$defs/timestamp"
        }
      }
    },
    "context_bootstrap": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "contract_version",
        "identity",
        "session_id",
        "conversation_id",
        "project_id",
        "created",
        "revisions"
      ],
      "properties": {
        "schema": {
          "const": "hux.context_bootstrap.v1"
        },
        "contract_version": {
          "$ref": "common.schema.json#/$defs/contract_version"
        },
        "identity": {
          "$ref": "common.schema.json#/$defs/identity"
        },
        "session_id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "conversation_id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "project_id": {
          "$ref": "common.schema.json#/$defs/id"
        },
        "created": {
          "type": "object",
          "additionalProperties": false,
          "required": ["project", "conversation"],
          "properties": {
            "project": {"type": "boolean"},
            "conversation": {"type": "boolean"}
          }
        },
        "revisions": {
          "type": "object",
          "additionalProperties": false,
          "required": ["project", "conversation"],
          "properties": {
            "project": {"$ref": "common.schema.json#/$defs/revision"},
            "conversation": {"$ref": "common.schema.json#/$defs/revision"}
          }
        }
      }
    },
    "error": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "schema",
        "status",
        "code",
        "message"
      ],
      "properties": {
        "schema": {
          "const": "hux.error.v1"
        },
        "status": {
          "type": "integer",
          "minimum": 400,
          "maximum": 599
        },
        "code": {
          "type": "string",
          "enum": [
            "unauthorized",
            "forbidden",
            "not_found",
            "conflict",
            "flag_off",
            "invalid",
            "too_large",
            "rate_limited",
            "approval_required",
            "budget_exhausted",
            "unprocessable"
          ]
        },
        "message": {
          "type": "string",
          "maxLength": 280
        },
        "details": {
          "type": "array",
          "maxItems": 32,
          "items": {
            "type": "string",
            "maxLength": 280
          }
        }
      }
    }
  },
  "oneOf": [
    {
      "$ref": "#/$defs/capabilities"
    },
    {
      "$ref": "#/$defs/manifest"
    },
    {
      "$ref": "#/$defs/context_bootstrap"
    },
    {
      "$ref": "#/$defs/error"
    }
  ]
}