fluid-core/schemas/revision-descriptor.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fluid.dev/schemas/revision-descriptor.schema.json",
  "title": "FLUID revision descriptor",
  "description": "The runtime-facing projection of a revision, deliberately small enough to be consumed deterministically by infrastructure (ArchitectureBlueprint.md section 36). This is a wire artifact: the gateway must be able to read it without any fluid-core library.",
  "type": "object",
  "properties": {
    "revision": {
      "type": "object",
      "properties": {
        "schema_version": { "$ref": "common.schema.json#/$defs/schemaVersion" },
        "id": { "$ref": "common.schema.json#/$defs/revisionId" },
        "interface": { "$ref": "common.schema.json#/$defs/interfaceId" },
        "state": {
          "enum": ["created", "verified", "experiment", "candidate", "stable", "deprecated", "retired"],
          "description": "The router refuses to route to created, failed or retired revisions (ArchitectureBlueprint.md section 5.3)."
        },

        "contract": {
          "type": "object",
          "properties": {
            "type": { "enum": ["openapi", "graphql", "protobuf", "asyncapi", "jsonschema", "custom"] },
            "digest": { "$ref": "common.schema.json#/$defs/digest" },
            "source": { "type": "string", "description": "Where the contract artifact can be fetched." }
          },
          "required": ["type", "digest"],
          "additionalProperties": false
        },

        "runtime": {
          "type": "object",
          "description": "Out-of-process attachment: the adapter is an upstream reached over the network, so it may be implemented in any language.",
          "properties": {
            "upstream": {
              "type": "string",
              "format": "uri",
              "description": "Base URL of the adapter process serving this revision."
            },
            "image": { "type": "string" },
            "digest": { "$ref": "common.schema.json#/$defs/digest" },
            "timeout_ms": { "type": "integer", "exclusiveMinimum": 0, "default": 5000 },
            "retry": {
              "type": "object",
              "properties": {
                "max_attempts": { "type": "integer", "minimum": 1, "default": 1 },
                "backoff_ms": { "type": "integer", "minimum": 0 },
                "retry_on": { "type": "array", "items": { "type": "string" } }
              },
              "additionalProperties": false
            },
            "circuit_breaker": {
              "type": "object",
              "properties": {
                "failure_threshold": { "type": "integer", "minimum": 1 },
                "reset_after_ms": { "type": "integer", "exclusiveMinimum": 0 }
              },
              "additionalProperties": false
            }
          },
          "required": ["upstream"],
          "additionalProperties": false
        },

        "intent": {
          "type": "object",
          "description": "Which interface evolution intent governs this revision. Required: a revision with no governing intent cannot be audited.",
          "properties": {
            "version": { "type": "string", "minLength": 1 },
            "digest": { "$ref": "common.schema.json#/$defs/digest" }
          },
          "required": ["version"],
          "additionalProperties": false
        },

        "routing": {
          "type": "object",
          "properties": {
            "eligible_cohorts": {
              "type": "array",
              "items": { "$ref": "common.schema.json#/$defs/cohortId" },
              "description": "Empty or absent means all cohorts are eligible."
            },
            "max_traffic_share": {
              "$ref": "common.schema.json#/$defs/unitInterval",
              "description": "Ceiling the router enforces regardless of what a routing policy asks for."
            }
          },
          "additionalProperties": false
        },

        "policy": {
          "type": "object",
          "properties": {
            "compatibility": {
              "enum": ["backward_compatible", "forward_compatible", "additive", "behavioral_change", "breaking", "migration_only", "internal_only"]
            },
            "security_check": { "enum": ["pending", "passed", "failed"] },
            "policy_check": { "enum": ["pending", "passed", "failed"] },
            "rollback_to": { "oneOf": [{ "$ref": "common.schema.json#/$defs/revisionId" }, { "type": "null" }] }
          },
          "required": ["compatibility", "security_check"],
          "additionalProperties": false
        },

        "signature": {
          "type": "object",
          "description": "The router accepts only signed published descriptors (ArchitectureBlueprint.md section 35). The signature covers the canonical form of this document with the signature member removed.",
          "properties": {
            "algorithm": { "enum": ["ed25519"] },
            "key_id": { "type": "string", "minLength": 1 },
            "value": { "type": "string", "contentEncoding": "base64" },
            "signed_at": { "$ref": "common.schema.json#/$defs/timestamp" }
          },
          "required": ["algorithm", "key_id", "value"],
          "additionalProperties": false
        }
      },
      "required": ["schema_version", "id", "interface", "state", "contract", "runtime", "intent", "policy"],
      "additionalProperties": false
    }
  },
  "required": ["revision"],
  "additionalProperties": false
}