fluid-core/schemas/revision.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fluid.dev/schemas/revision.schema.json",
  "title": "FLUID revision record",
  "description": "What deterministic interface state was built, verified, exposed and measured. Published revisions should be immutable; corrections create successors (FluidAPIStandards.md section 8).",
  "type": "object",
  "properties": {
    "fluid_revision": {
      "type": "object",
      "properties": {
        "schema_version": { "$ref": "common.schema.json#/$defs/schemaVersion" },
        "id": { "$ref": "common.schema.json#/$defs/revisionId" },
        "interface_id": { "$ref": "common.schema.json#/$defs/interfaceId" },
        "revision_number": { "type": "integer", "minimum": 0 },
        "parent_revision": {
          "oneOf": [
            { "$ref": "common.schema.json#/$defs/revisionId" },
            { "type": "null" }
          ],
          "description": "Null marks genesis."
        },
        "state": {
          "enum": ["CREATED", "VERIFIED", "EXPERIMENT", "CANDIDATE", "STABLE", "DEPRECATED", "RETIRED"]
        },
        "created_at": { "$ref": "common.schema.json#/$defs/timestamp" },
        "created_by": { "$ref": "common.schema.json#/$defs/actor" },

        "contract": {
          "type": "object",
          "properties": {
            "type": { "enum": ["openapi", "graphql", "protobuf", "asyncapi", "jsonschema", "custom"] },
            "version": { "type": "string" },
            "artifact_ref": { "$ref": "common.schema.json#/$defs/artifactRef" },
            "digest": { "$ref": "common.schema.json#/$defs/digest" }
          },
          "required": ["type", "artifact_ref", "digest"],
          "additionalProperties": false
        },

        "implementation": {
          "type": "object",
          "properties": {
            "artifact_ref": { "$ref": "common.schema.json#/$defs/artifactRef" },
            "source_ref": { "type": "string" },
            "build_ref": { "type": "string" },
            "digest": { "$ref": "common.schema.json#/$defs/digest" }
          },
          "required": ["artifact_ref", "digest"],
          "additionalProperties": false
        },

        "interface_evolution_intent": {
          "type": "object",
          "description": "Every revision is governed by a specific intent version, so audit can ask whether the change was valid under the intent that existed at the time (ArchitectureBlueprint.md section 27).",
          "properties": {
            "version": { "type": "string", "minLength": 1 },
            "artifact_ref": { "$ref": "common.schema.json#/$defs/artifactRef" }
          },
          "required": ["version"],
          "additionalProperties": false
        },

        "originating_hypotheses": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/hypothesisId" } },
        "backend_requirements": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/backendRequirementId" } },

        "compatibility": {
          "type": "object",
          "properties": {
            "class": {
              "enum": ["BACKWARD_COMPATIBLE", "FORWARD_COMPATIBLE", "ADDITIVE", "BEHAVIORAL_CHANGE", "BREAKING", "MIGRATION_ONLY", "INTERNAL_ONLY"]
            },
            "breaking_changes": { "type": "array", "items": { "type": "string" } },
            "deprecations": { "type": "array", "items": { "type": "string" } },
            "supersedes": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/revisionId" } },
            "compatibility_evidence_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/evidenceRef" } }
          },
          "required": ["class"],
          "additionalProperties": false
        },

        "adaptation_classes": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/adaptationClass" } },

        "verification": {
          "type": "object",
          "description": "The primary safety barrier between adaptive generation and deterministic runtime (ArchitectureBlueprint.md section 15).",
          "properties": {
            "status": { "enum": ["PENDING", "PASSED", "FAILED"] },
            "test_refs": { "type": "array", "items": { "type": "string" } },
            "security_check": { "enum": ["PENDING", "PASSED", "FAILED"] },
            "policy_check": { "enum": ["PENDING", "PASSED", "FAILED"] }
          },
          "required": ["status"],
          "additionalProperties": false
        },

        "complexity": {
          "type": "object",
          "properties": {
            "before": { "$ref": "common.schema.json#/$defs/complexityDelta" },
            "after": { "$ref": "common.schema.json#/$defs/complexityDelta" },
            "delta_score": { "type": "number" },
            "budget_status": { "enum": ["WITHIN_BUDGET", "AT_BUDGET", "OVER_BUDGET"] }
          },
          "additionalProperties": false
        },

        "deployment": {
          "type": "object",
          "properties": {
            "environments": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "name": { "type": "string" },
                  "started_at": { "$ref": "common.schema.json#/$defs/timestamp" },
                  "routing_policy_ref": { "type": "string" }
                },
                "required": ["name"],
                "additionalProperties": false
              }
            },
            "current_exposure": {
              "type": "object",
              "properties": {
                "traffic_share": { "$ref": "common.schema.json#/$defs/unitInterval" },
                "cohorts": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/cohortId" } }
              },
              "additionalProperties": false
            }
          },
          "additionalProperties": false
        },

        "fitness": {
          "type": "object",
          "properties": {
            "baseline_revision": { "oneOf": [{ "$ref": "common.schema.json#/$defs/revisionId" }, { "type": "null" }] },
            "measurement_window": { "$ref": "common.schema.json#/$defs/observationWindow" },
            "metrics": {
              "type": "object",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "baseline": { "type": ["number", "null"] },
                  "current": { "type": ["number", "null"] },
                  "target": { "type": ["number", "null"] },
                  "guardrail": { "type": ["number", "null"] }
                },
                "additionalProperties": false
              }
            }
          },
          "additionalProperties": false
        },

        "adoption": {
          "type": "object",
          "description": "Adoption is evidence, not proof of quality (FluidAPIStandards.md section 32).",
          "properties": {
            "eligible_consumers": { "type": ["integer", "null"], "minimum": 0 },
            "active_consumers": { "type": ["integer", "null"], "minimum": 0 },
            "adoption_rate": { "oneOf": [{ "$ref": "common.schema.json#/$defs/unitInterval" }, { "type": "null" }] },
            "retained_adoption_rate": { "oneOf": [{ "$ref": "common.schema.json#/$defs/unitInterval" }, { "type": "null" }] }
          },
          "additionalProperties": false
        },

        "economics": {
          "type": "object",
          "properties": {
            "build_cost": { "type": "number", "minimum": 0 },
            "experiment_cost_to_date": { "type": "number", "minimum": 0 },
            "currency": { "type": "string" }
          },
          "additionalProperties": false
        },

        "promotion": {
          "type": "object",
          "properties": {
            "eligible": { "type": "boolean" },
            "recommended_state": {
              "oneOf": [
                { "enum": ["CREATED", "VERIFIED", "EXPERIMENT", "CANDIDATE", "STABLE", "DEPRECATED", "RETIRED"] },
                { "type": "null" }
              ]
            },
            "recommendation_reason": { "type": ["string", "null"] },
            "authorized_by": { "oneOf": [{ "$ref": "common.schema.json#/$defs/actor" }, { "type": "null" }] },
            "authorized_at": { "oneOf": [{ "$ref": "common.schema.json#/$defs/timestamp" }, { "type": "null" }] }
          },
          "additionalProperties": false
        },

        "rollback": {
          "type": "object",
          "properties": {
            "supported": { "type": "boolean" },
            "target_revision": { "oneOf": [{ "$ref": "common.schema.json#/$defs/revisionId" }, { "type": "null" }] },
            "procedure_ref": { "type": "string" }
          },
          "required": ["supported"],
          "additionalProperties": false
        },

        "provenance": {
          "type": "object",
          "properties": {
            "decision_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/decisionId" } },
            "experiment_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/experimentId" } },
            "telemetry_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/evidenceRef" } }
          },
          "additionalProperties": false
        },

        "audit": {
          "type": "object",
          "properties": {
            "immutable_event_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/eventId" } }
          },
          "additionalProperties": false
        }
      },
      "required": [
        "schema_version", "id", "interface_id", "revision_number", "parent_revision",
        "state", "contract", "implementation", "interface_evolution_intent",
        "compatibility", "verification", "rollback", "provenance"
      ],
      "additionalProperties": false
    }
  },
  "required": ["fluid_revision"],
  "additionalProperties": false
}