canonical_study.schema.json

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "CanonicalStudyDesignSchema",
  "description": "Formal JSON Schema for StitchEDC study definitions, covering protocol description, trial design, data collection structure, logic constraints, rules, roles, and review audit blocks.",
  "type": "object",
  "properties": {
    "protocol": { "$ref": "#/definitions/protocol_identity" },
    "design_descriptors": { "$ref": "#/definitions/design_descriptors" },
    "stages": {
      "type": "array",
      "items": { "$ref": "#/definitions/stage" }
    },
    "arms": {
      "type": "array",
      "items": { "$ref": "#/definitions/arm" }
    },
    "stratification": {
      "type": "array",
      "items": { "$ref": "#/definitions/stratification" }
    },
    "eligibility": { "$ref": "#/definitions/structured_eligibility" },
    "endpoints": {
      "type": "array",
      "items": { "$ref": "#/definitions/endpoint" }
    },
    "estimands": {
      "type": "array",
      "items": { "$ref": "#/definitions/estimand" }
    },
    "epochs": {
      "type": "array",
      "items": { "$ref": "#/definitions/epoch" }
    },
    "events": {
      "type": "array",
      "items": { "$ref": "#/definitions/event" }
    },
    "forms": {
      "type": "array",
      "items": { "$ref": "#/definitions/form" }
    },
    "item_groups": {
      "type": "array",
      "items": { "$ref": "#/definitions/item_group" }
    },
    "fields": {
      "type": "array",
      "items": { "$ref": "#/definitions/field" }
    },
    "code_lists": {
      "type": "array",
      "items": { "$ref": "#/definitions/code_list" }
    },
    "visit_form_matrix": {
      "type": "array",
      "items": { "$ref": "#/definitions/visit_form_link" }
    },
    "edit_checks": {
      "type": "array",
      "items": { "$ref": "#/definitions/edit_check" }
    },
    "derivations": {
      "type": "array",
      "items": { "$ref": "#/definitions/derivation" }
    },
    "roles": {
      "type": "array",
      "items": { "$ref": "#/definitions/role" }
    },
    "door_rankings": {
      "type": "array",
      "items": { "$ref": "#/definitions/door_ranking" }
    },
    "analysis_gates": {
      "type": "array",
      "items": { "$ref": "#/definitions/analysis_gate" }
    },
    "provenance": { "$ref": "#/definitions/provenance" }
  },
  "required": [
    "protocol",
    "design_descriptors",
    "stages",
    "arms",
    "stratification",
    "eligibility",
    "endpoints",
    "estimands",
    "epochs",
    "events",
    "forms",
    "item_groups",
    "fields",
    "code_lists",
    "visit_form_matrix",
    "edit_checks",
    "derivations",
    "roles",
    "door_rankings",
    "analysis_gates"
  ],
  "definitions": {
    "provenance": {
      "type": "object",
      "description": "Review and confidence metadata metadata block for AI tracking and human override tracking.",
      "properties": {
        "confidence_score": {
          "type": "number",
          "minimum": 0.0,
          "maximum": 1.0
        },
        "model_generator": { "type": "string" },
        "timestamp": { "type": "string", "format": "date-time" },
        "reviewed_by": { "type": ["string", "null"] },
        "review_status": {
          "type": "string",
          "enum": ["unreviewed", "partially_reviewed", "approved", "rejected"]
        },
        "comments": { "type": "string" }
      },
      "required": ["confidence_score", "model_generator", "timestamp", "review_status"]
    },
    "protocol_identity": {
      "type": "object",
      "description": "Core identity elements mapping a clinical protocol.",
      "properties": {
        "protocol_id": { "type": "string" },
        "title": { "type": "string" },
        "phase": {
          "type": "string",
          "enum": ["I", "Ib", "II", "IIa", "IIb", "III", "IV", "l", "ll", "lll", "lV"]
        },
        "sponsor": { "type": "string" },
        "therapeutic_area": { "type": "string" },
        "target_enrollment": { "type": "integer", "minimum": 1 },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["protocol_id", "title", "phase", "therapeutic_area", "target_enrollment"]
    },
    "design_descriptors": {
      "type": "object",
      "description": "Comprehensive flags for structural features specifying MAMS, non-inferiority, masking and seamless transitions.",
      "properties": {
        "is_mams": { "type": "boolean", "description": "Is Multi-Arm Multi-Stage design?" },
        "masking": {
          "type": "string",
          "enum": ["open-label", "single-blind", "double-blind", "triple-blind"]
        },
        "is_non_inferiority": { "type": "boolean" },
        "non_inferiority_margin": {
          "type": ["number", "null"],
          "description": "Defined noninferiority boundary percentage or limit if applicable."
        },
        "is_seamless": { "type": "boolean", "description": "Is a seamless Phase II/III adaptive design transition?" },
        "randomization_style": { "type": "string" },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["is_mams", "masking", "is_non_inferiority", "is_seamless", "randomization_style"]
    },
    "stage": {
      "type": "object",
      "description": "Trial Adaptive Stage mapping rules, endpoints, or timing blocks.",
      "properties": {
        "stage_id": { "type": "string" },
        "name": { "type": "string" },
        "seq_number": { "type": "integer" },
        "gate_oids": {
          "type": "array",
          "items": { "type": "string" },
          "description": "References to analysis_gates ruling transitions out of this stage."
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["stage_id", "name", "seq_number"]
    },
    "arm": {
      "type": "object",
      "description": "Subject treatment pathways linked cleanly to trial stages.",
      "properties": {
        "arm_id": { "type": "string" },
        "name": { "type": "string" },
        "code": { "type": "string" },
        "stage_ids": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Wired stages that this study arm lives in."
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["arm_id", "name", "code", "stage_ids"]
    },
    "stratification": {
      "type": "object",
      "description": "Details key variables guiding randomization stratification.",
      "properties": {
        "stratum_id": { "type": "string" },
        "name": { "type": "string" },
        "factor_field_id": { "type": "string", "description": "Field ID that forms the stratification source" },
        "levels": {
          "type": "array",
          "items": { "type": "string" }
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["stratum_id", "name", "factor_field_id", "levels"]
    },
    "structured_eligibility": {
      "type": "object",
      "description": "Formalizing Inclusion and Exclusion protocols.",
      "properties": {
        "inclusion_rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "criterion": { "type": "string" },
              "field_id": { "type": "string", "description": "The target field which must resolve to validating value" }
            },
            "required": ["id", "criterion", "field_id"]
          }
        },
        "exclusion_rules": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": { "type": "string" },
              "criterion": { "type": "string" },
              "field_id": { "type": "string" }
            },
            "required": ["id", "criterion", "field_id"]
          }
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["inclusion_rules", "exclusion_rules"]
    },
    "endpoint": {
      "type": "object",
      "description": "Formal trial endpoints, either standard clinical read or multi-criteria structures like DOOR.",
      "properties": {
        "endpoint_id": { "type": "string" },
        "type": {
          "type": "string",
          "enum": ["primary", "secondary", "exploratory"]
        },
         "description": { "type": "string" },
         "is_door": { "type": "boolean", "description": "Is this a Desirability of Outcome Ranking endpoint?" },
         "door_ranking_oid": {
           "type": ["string", "null"],
           "description": "Reference OID key to formal DOOR rank tables."
         },
         "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["endpoint_id", "type", "description", "is_door"]
    },
    "estimand": {
      "type": "object",
      "description": "The precise scientific formulation of the trial question.",
      "properties": {
        "estimand_id": { "type": "string" },
        "population": { "type": "string" },
        "treatment_variable": { "type": "string" },
        "endpoint_id": { "type": "string", "description": "Points to endpoint OID" },
        "intercurrent_handling": { "type": "string" },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["estimand_id", "population", "treatment_variable", "endpoint_id", "intercurrent_handling"]
    },
    "epoch": {
      "type": "object",
      "description": "Grouping timeline bounds, e.g. Screening/Enrichment, Active, Safety Washout.",
      "properties": {
        "epoch_id": { "type": "string" },
        "name": { "type": "string" },
        "sequence": { "type": "integer" },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["epoch_id", "name", "sequence"]
    },
    "event": {
      "type": "object",
      "description": "Encounter visit structures mapping target timeline moments.",
      "properties": {
        "event_id": { "type": "string" },
        "name": { "type": "string" },
        "epoch_id": { "type": "string", "description": "The epoch that bounds this event" },
        "window": { "type": "string" },
        "day_offset": { "type": "integer" },
        "type": {
          "type": "string",
          "enum": ["Screening", "Baseline", "Treatment", "FollowUp", "EndOfStudy"]
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["event_id", "name", "epoch_id", "window", "day_offset", "type"]
    },
    "form": {
      "type": "object",
      "description": "Case Report Form template grouping logical attributes.",
      "properties": {
        "form_id": { "type": "string" },
        "name": { "type": "string" },
        "cdisc_domain": { "type": "string" },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["form_id", "name", "cdisc_domain"]
    },
    "item_group": {
      "type": "object",
      "description": "Sub-structural block layout inside forms.",
      "properties": {
        "item_group_id": { "type": "string" },
        "form_id": { "type": "string", "description": "Form ID scoping this group" },
        "name": { "type": "string" },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["item_group_id", "form_id", "name"]
    },
    "field": {
      "type": "object",
      "description": "Individual variable definition with formal typing attributes.",
      "properties": {
        "field_id": { "type": "string" },
        "form_id": { "type": "string" },
        "item_group_id": { "type": "string", "description": "The inner group wrapping the field" },
        "name": { "type": "string" },
        "data_type": {
          "type": "string",
          "enum": ["Date", "Integer", "Float", "Text", "Boolean", "Coded"]
        },
        "unit": { "type": ["string", "null"] },
        "required": { "type": "boolean" },
        "code_list_id": {
          "type": ["string", "null"],
          "description": "Refers to formal code_lists definition OID if coded"
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["field_id", "form_id", "item_group_id", "name", "data_type", "required"]
    },
    "code_list": {
      "type": "object",
      "description": "Durable schema vocabulary codelists containing key decode pairs.",
      "properties": {
        "code_list_id": { "type": "string" },
        "name": { "type": "string" },
        "items": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "code": { "type": "string" },
              "decode": { "type": "string" }
            },
            "required": ["code", "decode"]
          }
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["code_list_id", "name", "items"]
    },
    "visit_form_link": {
      "type": "object",
      "description": "Binds a visit event to a form, creating the schedule of collection matrix.",
      "properties": {
        "event_id": { "type": "string" },
        "form_id": { "type": "string" },
        "mandatory": { "type": "boolean" },
        "order": { "type": "integer" },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["event_id", "form_id", "mandatory", "order"]
    },
    "edit_check": {
      "type": "object",
      "description": "Logic checks to safeguard data entry sanity including cross-form parameters.",
      "properties": {
        "check_id": { "type": "string" },
        "trigger_field_id": { "type": "string", "description": "Target field starting evaluation" },
        "rule_expression": { "type": "string" },
        "error_message": { "type": "string" },
        "severity": {
          "type": "string",
          "enum": ["ERROR", "WARNING", "INFO"]
        },
        "dependent_field_ids": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Other fields involved facilitating cross-form edit checks."
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["check_id", "trigger_field_id", "rule_expression", "error_message", "severity", "dependent_field_ids"]
    },
    "derivation": {
      "type": "object",
      "description": "Calculated entries based on other field calculations, e.g. BMI.",
      "properties": {
        "derivation_id": { "type": "string" },
        "target_field_id": { "type": "string" },
        "formula": { "type": "string" },
        "source_field_ids": {
          "type": "array",
          "items": { "type": "string" }
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["derivation_id", "target_field_id", "formula", "source_field_ids"]
    },
    "role": {
      "type": "object",
      "description": "Clinical investigator/manager workspace permission sets.",
      "properties": {
        "role_id": { "type": "string" },
        "name": { "type": "string" },
        "permissions": {
          "type": "array",
          "items": { "type": "string" }
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["role_id", "name", "permissions"]
    },
    "door_ranking": {
      "type": "object",
      "description": "Desirability of Outcome Ranking (DOOR) scale levels ordered by severity/clinical desirability (lowest index is best outcome, highest index is worst outcome, e.g., death).",
      "properties": {
        "door_id": { "type": "string" },
        "name": { "type": "string" },
        "levels": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "rank_order": { "type": "integer", "minimum": 1 },
              "label": { "type": "string" },
              "clinical_state": { "type": "string" }
            },
            "required": ["rank_order", "label", "clinical_state"]
          }
        },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["door_id", "name", "levels"]
    },
    "analysis_gate": {
      "type": "object",
      "description": "Safety interim review parameters, e.g. DSMB adaptive gates.",
      "properties": {
        "gate_id": { "type": "string" },
        "name": { "type": "string" },
        "sample_size_trigger": { "type": "integer" },
        "futility_rule": { "type": "string" },
        "efficacy_rule": { "type": "string" },
        "provenance": { "$ref": "#/definitions/provenance" }
      },
      "required": ["gate_id", "name", "sample_size_trigger"]
    }
  }
}