229 lines
8.7 KiB
JSON
229 lines
8.7 KiB
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
|
||
|
|
}
|