fluid-core/schemas/hypothesis.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://fluid.dev/schemas/hypothesis.schema.json",
  "title": "FLUID hypothesis record",
  "description": "Why an interface change should be explored. Observation, explanation, prediction, intervention and result stay separate on purpose (FluidHypothesisRevisionSchema.md section 18).",
  "type": "object",
  "properties": {
    "fluid_hypothesis": {
      "type": "object",
      "properties": {
        "schema_version": { "$ref": "common.schema.json#/$defs/schemaVersion" },
        "id": { "$ref": "common.schema.json#/$defs/hypothesisId" },
        "interface_id": { "$ref": "common.schema.json#/$defs/interfaceId" },
        "state": {
          "enum": ["DRAFT", "READY", "PRIORITIZED", "DESIGNING", "EXPERIMENTING", "EVALUATING", "ACCEPTED", "REJECTED", "SUPERSEDED", "DEFERRED"]
        },
        "created_at": { "$ref": "common.schema.json#/$defs/timestamp" },
        "created_by": { "$ref": "common.schema.json#/$defs/actor" },
        "title": { "type": "string", "minLength": 1 },

        "observation": {
          "type": "object",
          "description": "What was seen. Not what it means.",
          "properties": {
            "summary": { "type": "string", "minLength": 1 },
            "evidence_refs": {
              "type": "array",
              "items": { "$ref": "common.schema.json#/$defs/evidenceRef" },
              "minItems": 1
            },
            "affected_cohorts": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/cohortId" } },
            "observation_window": { "$ref": "common.schema.json#/$defs/observationWindow" }
          },
          "required": ["summary", "evidence_refs"],
          "additionalProperties": false
        },

        "pressure": {
          "type": "object",
          "properties": {
            "classes": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/pressureClass" }, "minItems": 1 },
            "pressure_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/pressureId" } },
            "severity": { "$ref": "common.schema.json#/$defs/unitInterval" },
            "confidence": { "$ref": "common.schema.json#/$defs/unitInterval" }
          },
          "required": ["classes"],
          "additionalProperties": false
        },

        "explanation": {
          "type": "object",
          "description": "What we think explains the observation.",
          "properties": {
            "claim": { "type": "string", "minLength": 1 },
            "reach": {
              "type": "object",
              "description": "Explanatory reach is a prioritization signal, never a correctness claim (FluidAPIStandards.md section 18).",
              "properties": {
                "score": { "type": "number" },
                "explains": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/pressureId" } },
                "notes": { "type": "string" }
              },
              "additionalProperties": false
            }
          },
          "required": ["claim"],
          "additionalProperties": false
        },

        "proposed_adaptation": {
          "type": "object",
          "description": "What we propose to change.",
          "properties": {
            "class": { "$ref": "common.schema.json#/$defs/adaptationClass" },
            "summary": { "type": "string", "minLength": 1 },
            "candidate_contract": {
              "type": "object",
              "description": "Shape is protocol-specific and deliberately unconstrained.",
              "additionalProperties": true
            },
            "implementation_scope": { "enum": ["interface_only", "interface_and_backend", "documentation_only"] }
          },
          "required": ["class", "summary"],
          "additionalProperties": false
        },

        "backend_requirements": {
          "type": "object",
          "properties": {
            "required": { "type": "boolean" },
            "requirement_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/backendRequirementId" } }
          },
          "required": ["required"],
          "additionalProperties": false
        },

        "expected_outcomes": {
          "type": "array",
          "items": { "$ref": "common.schema.json#/$defs/expectedOutcome" },
          "minItems": 1,
          "description": "A hypothesis must be falsifiable (FluidAPIStandards.md section 17)."
        },
        "guardrails": {
          "type": "array",
          "items": { "$ref": "common.schema.json#/$defs/guardrail" }
        },

        "fitness_dimensions": {
          "type": "object",
          "properties": {
            "expected": { "$ref": "common.schema.json#/$defs/fitnessDimensions" }
          },
          "additionalProperties": false
        },

        "complexity": {
          "type": "object",
          "properties": {
            "expected_delta": { "$ref": "common.schema.json#/$defs/complexityDelta" },
            "score": { "type": "number" }
          },
          "required": ["expected_delta"],
          "additionalProperties": false
        },

        "risk": {
          "type": "object",
          "properties": {
            "level": { "enum": ["LOW", "MEDIUM", "HIGH", "CRITICAL"] },
            "reasons": { "type": "array", "items": { "type": "string" } }
          },
          "required": ["level"],
          "additionalProperties": false
        },

        "economics": {
          "type": "object",
          "description": "A hypothesis may be valuable but not yet worth exploring (ArchitectureBlueprint.md section 29).",
          "properties": {
            "estimated_experiment_cost": { "type": "number", "minimum": 0 },
            "estimated_implementation_cost": { "type": "number", "minimum": 0 },
            "currency": { "type": "string" },
            "expected_value_class": { "enum": ["LOW", "MEDIUM", "HIGH"] }
          },
          "additionalProperties": false
        },

        "learning_value": {
          "type": "object",
          "properties": {
            "score": { "type": "number" },
            "notes": { "type": "string" }
          },
          "additionalProperties": false
        },

        "priority": {
          "type": "object",
          "properties": {
            "score": { "type": "number" },
            "decided_by": { "type": "string" }
          },
          "additionalProperties": false
        },

        "competition": {
          "type": "object",
          "description": "Competing hypotheses are legitimate (FluidAPIStandards.md section 19).",
          "properties": {
            "group_id": { "type": "string", "minLength": 1 },
            "alternatives": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/hypothesisId" } }
          },
          "required": ["group_id"],
          "additionalProperties": false
        },

        "success_criteria": {
          "type": "object",
          "properties": { "expression": { "type": "string", "minLength": 1 } },
          "required": ["expression"],
          "additionalProperties": false
        },
        "failure_criteria": {
          "type": "object",
          "properties": { "expression": { "type": "string", "minLength": 1 } },
          "required": ["expression"],
          "additionalProperties": false
        },

        "candidate_revision_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/revisionId" } },
        "experiment_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/experimentId" } },

        "outcome": {
          "type": "object",
          "description": "What happened afterwards. Null until evaluation completes.",
          "properties": {
            "status": {
              "oneOf": [
                { "enum": ["CONFIRMED", "REFUTED", "INCONCLUSIVE"] },
                { "type": "null" }
              ]
            },
            "summary": { "type": ["string", "null"] },
            "evidence_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/evidenceRef" } }
          },
          "additionalProperties": false
        },

        "audit": {
          "type": "object",
          "properties": {
            "decision_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/decisionId" } },
            "immutable_event_refs": { "type": "array", "items": { "$ref": "common.schema.json#/$defs/eventId" } }
          },
          "additionalProperties": false
        }
      },
      "required": [
        "schema_version", "id", "interface_id", "state", "title",
        "observation", "pressure", "explanation", "proposed_adaptation",
        "expected_outcomes", "guardrails", "complexity", "risk", "success_criteria"
      ],
      "additionalProperties": false
    }
  },
  "required": ["fluid_hypothesis"],
  "additionalProperties": false
}