fluid-core/schemas/common.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fluid.dev/schemas/common.schema.json",
  "title": "FLUID common definitions",
  "description": "Shared identifier, reference and measurement types. Identifier prefixes follow FluidHypothesisRevisionSchema.md section 16.",
  "$defs": {
    "schemaVersion": {
      "type": "string",
      "const": "0.1"
    },
    "interfaceId": {
      "type": "string",
      "minLength": 1,
      "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
      "description": "Stable identifier of the owning interface."
    },
    "hypothesisId": { "type": "string", "pattern": "^H-[0-9A-Za-z_-]+$" },
    "revisionId":   { "type": "string", "pattern": "^R-[0-9A-Za-z_-]+$" },
    "experimentId": { "type": "string", "pattern": "^E-[0-9A-Za-z_-]+$" },
    "pressureId":   { "type": "string", "pattern": "^P-[0-9A-Za-z_-]+$" },
    "backendRequirementId": { "type": "string", "pattern": "^BR-[0-9A-Za-z_-]+$" },
    "decisionId":   { "type": "string", "pattern": "^D-[0-9A-Za-z_-]+$" },
    "eventId":      { "type": "string", "pattern": "^EV-[0-9A-Za-z_-]+$" },
    "feedbackId":   { "type": "string", "pattern": "^F-[0-9A-Za-z_-]+$" },
    "cohortId":     { "type": "string", "minLength": 1 },

    "timestamp": { "type": "string", "format": "date-time" },

    "evidenceRef": {
      "type": "string",
      "minLength": 1,
      "description": "Opaque reference into the evidence store, conventionally '<kind>:<locator>' such as 'telemetry:invoice-pattern-2026w36'."
    },
    "artifactRef": {
      "type": "string",
      "minLength": 1,
      "description": "Opaque reference into the artifact store."
    },
    "digest": {
      "type": "string",
      "pattern": "^sha256:[a-f0-9]{64}$",
      "description": "Content address of an artifact."
    },

    "actor": {
      "type": "object",
      "description": "Who or what performed an action. FLUID distinguishes these because trust levels differ (ArchitectureBlueprint.md section 47).",
      "properties": {
        "type": { "enum": ["human", "daimon", "policy", "system", "consumer"] },
        "id": { "type": "string", "minLength": 1 },
        "model_or_agent": { "type": "string" }
      },
      "required": ["type", "id"],
      "additionalProperties": false
    },

    "observationWindow": {
      "type": "object",
      "properties": {
        "start": { "$ref": "common.schema.json#/$defs/timestamp" },
        "end": {
          "oneOf": [
            { "$ref": "common.schema.json#/$defs/timestamp" },
            { "type": "null" }
          ],
          "description": "Null while the window is still open."
        }
      },
      "required": ["start"],
      "additionalProperties": false
    },

    "unitInterval": { "type": "number", "minimum": 0, "maximum": 1 },

    "pressureClass": {
      "enum": [
        "natural_usage",
        "successful_but_inefficient_usage",
        "recoverable_misunderstanding",
        "repeated_expectation_mismatch",
        "poor_discoverability",
        "missing_interface_capability",
        "missing_backend_capability",
        "out_of_scope_demand",
        "prohibited_demand",
        "implementation_failure"
      ],
      "description": "FluidAPIStandards.md section 13."
    },

    "adaptationClass": {
      "enum": ["presentation", "contract", "composition", "implementation", "requirement_escalation"],
      "description": "FluidAPIStandards.md section 16."
    },

    "guardrail": {
      "type": "object",
      "description": "A constraint that must not regress beyond threshold. Guardrails are evaluated deterministically.",
      "properties": {
        "metric": { "type": "string", "minLength": 1 },
        "operator": { "enum": ["<", "<=", "==", "!=", ">=", ">"] },
        "threshold": { "type": ["number", "boolean", "string"] }
      },
      "required": ["metric", "operator", "threshold"],
      "additionalProperties": false
    },

    "expectedOutcome": {
      "type": "object",
      "properties": {
        "metric": { "type": "string", "minLength": 1 },
        "cohort": { "type": "string" },
        "baseline": { "type": "number" },
        "target": { "type": "number" },
        "direction": { "enum": ["lower", "higher", "unchanged"] }
      },
      "required": ["metric", "target", "direction"],
      "additionalProperties": false
    },

    "complexityDelta": {
      "type": "object",
      "description": "Standard dimensions, implementation-defined scoring (FluidAPIStandards.md section 22).",
      "properties": {
        "surface_area": { "type": "number" },
        "concept_count": { "type": "number" },
        "operation_count": { "type": "number" },
        "parameter_dimensionality": { "type": "number" },
        "semantic_overlap": { "type": "number" },
        "alternative_path_count": { "type": "number" },
        "dependency_count": { "type": "number" },
        "backend_composition_count": { "type": "number" },
        "exception_count": { "type": "number" },
        "active_revision_count": { "type": "number" },
        "cognitive_load": { "type": "number" }
      },
      "additionalProperties": false
    },

    "fitnessDimensions": {
      "type": "object",
      "description": "FluidAPIStandards.md section 20. No universal scalar is defined on purpose.",
      "properties": {
        "client_utility": { "type": "number" },
        "correctness": { "type": "number" },
        "reliability": { "type": "number" },
        "availability": { "type": "number" },
        "performance": { "type": "number" },
        "discoverability": { "type": "number" },
        "simplicity": { "type": "number" },
        "compatibility": { "type": "number" },
        "security": { "type": "number" },
        "maintainability": { "type": "number" },
        "operational_cost": { "type": "number" },
        "implementation_cost": { "type": "number" },
        "resource_consumption": { "type": "number" }
      },
      "additionalProperties": false
    }
  }
}