{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://iqapparatus.com/contract/iq-render-contract.schema.json",
  "title": "IQ Apparatus render contract",
  "version": "2026-09-03",
  "supported_versions": [
    "2026-08-19",
    "2026-08-20",
    "2026-08-21",
    "2026-08-22",
    "2026-08-23",
    "2026-08-24",
    "2026-08-25",
    "2026-08-26",
    "2026-08-27",
    "2026-08-28",
    "2026-08-31",
    "2026-09-02",
    "2026-09-03"
  ],
  "component_types": [
    "content",
    "rich-text",
    "rich_text",
    "html",
    "image",
    "image-hotspot",
    "image_hotspot",
    "audio",
    "video",
    "webinar-embed",
    "webinar_embed",
    "talking-avatar",
    "talking_avatar",
    "ai-video",
    "ai_video",
    "reflection",
    "confidence-check",
    "confidence_check",
    "form-input",
    "form_input",
    "button",
    "choice",
    "question",
    "timed-quiz",
    "timed_quiz",
    "drag-drop-match",
    "drag_drop_match",
    "grouping",
    "card-flip",
    "card_flip",
    "narrative-escape",
    "narrative_escape",
    "evaluation"
  ],
  "phase_types": [
    "introduction",
    "pre-assessment",
    "content",
    "education",
    "assessment",
    "post-assessment",
    "evaluation",
    "payment",
    "certificate"
  ],
  "phase_canonical_order": [
    "introduction",
    "pre-assessment",
    "content",
    "education",
    "assessment",
    "post-assessment",
    "evaluation",
    "payment",
    "certificate"
  ],
  "passthrough_fields": [
    "contract_version",
    "accreditation",
    "credit_designations",
    "available_certificate_types",
    "learning_objectives",
    "activity_details",
    "landing_page",
    "evaluation_questions",
    "confidence_baseline",
    "debrief",
    "references",
    "series",
    "follow_up"
  ],
  "non_gated_overview_fields": [
    "contract_version",
    "format",
    "delivery_style",
    "landing_page",
    "learning_objectives",
    "accreditation",
    "activity_details",
    "references",
    "series"
  ],
  "error_codes": [
    "course_not_found",
    "course_not_published",
    "course_not_owned_by_key",
    "invalid_api_key",
    "insufficient_scope",
    "rate_limited"
  ],
  "media_policy": {
    "ttl_seconds": 21600,
    "refresh_endpoint": "GET /api-course-content?course_id={course_id}",
    "refresh_note": "Refetching the course re-signs every asset in the payload. Do not cache a video_url past its expires_at (or the payload-level media_expires_at)."
  },
  "gating_policy": {
    "anchor_types": [
      "choice",
      "question",
      "timed-quiz"
    ],
    "anchor_field": "reveals_on_answer",
    "gate_field": "reveal_after",
    "rule": "Render components in the returned order. A component whose reveal_after is non-null MUST stay hidden until the referenced component has been answered and its rationale revealed (locally for client_graded decisions, or from POST /api-submit-progress for assessmentMode items). Revealing does not reorder: the block appears in its authored position.",
    "rationale": "On a Bramwell decision phase the outcome video and teach-back debrief state the correct answer. Rendering them before the learner answers spoils the decision."
  },
  "confidence_check_control": {
    "control": "slider",
    "fields": [
      "statement",
      "min",
      "max",
      "minLabel",
      "maxLabel",
      "helperText"
    ],
    "never": [
      "options"
    ],
    "degraded_mode": "Radio scale over the same integer values from min to max."
  },
  "image_policy": {
    "urls_absolute": true,
    "auth_required": false,
    "component_fields": [
      "url",
      "alt",
      "caption",
      "source",
      "alt_is_fallback"
    ],
    "scene_image": {
      "component_type": "image",
      "source": "bramwell_patient_image",
      "position": "first component of the first introduction phase",
      "injected_when": "the activity has a scene illustration and the phase has no authored inline image component",
      "aspect_ratio": "16/9"
    },
    "alt_text": "alt is always a non-empty string. When alt_is_fallback is true the activity carried no authored alt and IQ supplied a generic description — a consumer may substitute its own."
  },
  "screen_policy": {
    "roles": [
      "primary",
      "attached"
    ],
    "display_modes": [
      "sequential",
      "stacked"
    ],
    "component_fields": [
      "screen_index",
      "screen_role",
      "anchor_id"
    ],
    "phase_fields": [
      "display_mode",
      "screen_count"
    ],
    "rule": "Group a phase's components by screen_index and render one group at a time when display_mode is \"sequential\". Continue advances to the next screen_index; on the last screen it advances to the next phase. Never derive screen breaks from reveal_after/reveals_on_answer — those are visibility gates within a screen.",
    "guarantees": [
      "A \"Meet the Patient\" introduction phase is one screen: scene image + hook prose + confidence slider share screen_index 0.",
      "A content/HTML block with no required interaction is its own primary screen, so Continue always has a defined next target.",
      "Interactive blocks authored directly beneath a text block (choice, form-input) are attached to that text block's screen."
    ]
  },
  "definitions": {
    "ApiEnvelope": {
      "type": "object",
      "required": [
        "success",
        "contract_version"
      ],
      "properties": {
        "success": {
          "type": "boolean"
        },
        "contract_version": {
          "type": "string"
        },
        "authenticated_organization_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "The organization the authenticated API key is scoped to. Null only for unscoped platform-wide keys. Emitted on GET /api-courses, GET /api-course-content and GET /api-whoami."
        },
        "data": {},
        "error": {
          "type": "string"
        },
        "error_code": {
          "enum": [
            "course_not_found",
            "course_not_published",
            "course_not_owned_by_key",
            "invalid_api_key",
            "insufficient_scope",
            "rate_limited"
          ],
          "description": "Machine-readable failure reason on a 4xx. Added 2026-08-25. Route on this, not on the prose in `error`."
        },
        "owning_organization_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid",
          "description": "Present when error_code is course_not_owned_by_key: the organization that owns the requested course. Retry with the key bound to it."
        },
        "message": {
          "type": "string"
        },
        "pagination": {
          "type": "object",
          "properties": {
            "page": {
              "type": "integer"
            },
            "limit": {
              "type": "integer"
            },
            "total": {
              "type": "integer"
            },
            "hasMore": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "CreditDesignation": {
      "type": "object",
      "required": [
        "credit_type",
        "credit_hours",
        "profession"
      ],
      "properties": {
        "credit_type": {
          "type": [
            "string",
            "null"
          ]
        },
        "credit_type_slug": {
          "type": [
            "string",
            "null"
          ]
        },
        "credit_hours": {
          "type": [
            "number",
            "null"
          ]
        },
        "profession": {
          "type": [
            "string",
            "null"
          ]
        },
        "source": {
          "enum": [
            "certificate_settings",
            "statement"
          ]
        }
      }
    },
    "CatalogItem": {
      "type": "object",
      "required": [
        "contract_version",
        "id",
        "organization_id",
        "name",
        "status",
        "activity_type",
        "credit_designations",
        "available_certificate_types",
        "accredited_provider_name",
        "activity_details",
        "card_display_config",
        "overview"
      ],
      "properties": {
        "contract_version": {
          "type": "string"
        },
        "overview": {
          "type": "object",
          "required": [
            "about",
            "learning_objectives",
            "references",
            "faculty"
          ],
          "properties": {
            "about": {
              "type": [
                "string",
                "null"
              ]
            },
            "statement_of_need": {
              "type": [
                "string",
                "null"
              ]
            },
            "learning_objectives": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "target_audience": {
              "type": "array",
              "items": {
                "type": "string"
              }
            },
            "accreditation": {
              "type": [
                "object",
                "null"
              ]
            },
            "how_to_earn_credit": {
              "type": [
                "string",
                "null"
              ]
            },
            "estimated_time": {
              "type": [
                "string",
                "null"
              ]
            },
            "release_date": {
              "type": [
                "string",
                "null"
              ]
            },
            "expiration_date": {
              "type": [
                "string",
                "null"
              ]
            },
            "commercial_support": {
              "type": [
                "string",
                "null"
              ]
            },
            "disclosure_summary": {
              "type": [
                "string",
                "null"
              ]
            },
            "hardware_software_requirements": {
              "type": [
                "string",
                "null"
              ]
            },
            "faculty": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "degree": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "title_affiliation": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                }
              }
            },
            "references": {
              "type": "array"
            }
          }
        },
        "id": {
          "type": "string",
          "format": "uuid"
        },
        "organization_id": {
          "type": "string",
          "format": "uuid"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": [
            "string",
            "null"
          ]
        },
        "status": {
          "type": "string"
        },
        "activity_type": {
          "type": "string"
        },
        "accredited_provider_name": {
          "type": [
            "string",
            "null"
          ]
        },
        "credit_designations": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/CreditDesignation"
          }
        },
        "available_certificate_types": {
          "type": "array"
        },
        "activity_details": {
          "type": "object"
        },
        "card_display_config": {
          "type": "object",
          "required": [
            "image",
            "credit_chips",
            "price",
            "cta"
          ],
          "properties": {
            "image": {
              "type": "object",
              "properties": {
                "url": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "alt": {
                  "type": "string"
                },
                "aspect_ratio": {
                  "type": "string"
                }
              }
            },
            "badge": {
              "type": [
                "object",
                "null"
              ]
            },
            "stripe": {
              "type": [
                "object",
                "null"
              ]
            },
            "is_featured": {
              "type": "boolean"
            },
            "credit_chips": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "amount",
                  "labels",
                  "display"
                ],
                "properties": {
                  "amount": {
                    "type": "number"
                  },
                  "labels": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "display": {
                    "type": "string"
                  }
                }
              }
            },
            "hide_credit_chips": {
              "type": "boolean"
            },
            "price": {
              "type": "object",
              "required": [
                "amount",
                "is_free",
                "display"
              ],
              "properties": {
                "amount": {
                  "type": "number"
                },
                "is_free": {
                  "type": "boolean"
                },
                "display": {
                  "type": "string"
                }
              }
            },
            "provider_name": {
              "type": [
                "string",
                "null"
              ]
            },
            "format_line": {
              "type": [
                "string",
                "null"
              ]
            },
            "cta": {
              "type": "object",
              "required": [
                "label",
                "style"
              ],
              "properties": {
                "label": {
                  "type": "string"
                },
                "style": {
                  "enum": [
                    "primary",
                    "outline"
                  ]
                }
              }
            },
            "summary": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "series": {
          "type": [
            "object",
            "null"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "name": {
              "type": [
                "string",
                "null"
              ]
            },
            "position": {
              "type": [
                "number",
                "null"
              ]
            },
            "total": {
              "type": [
                "number",
                "null"
              ]
            },
            "is_series_module": {
              "type": "boolean"
            }
          }
        }
      }
    },
    "CourseContentPayload": {
      "type": "object",
      "required": [
        "contract_version",
        "course_id",
        "organization_id",
        "name",
        "format",
        "total_phases",
        "phases",
        "learning_objectives",
        "accreditation",
        "available_certificate_types",
        "activity_details",
        "references",
        "series"
      ],
      "properties": {
        "contract_version": {
          "type": "string"
        },
        "course_id": {
          "type": "string",
          "format": "uuid"
        },
        "organization_id": {
          "type": "string",
          "format": "uuid"
        },
        "format": {
          "type": [
            "string",
            "null"
          ]
        },
        "delivery_style": {
          "type": [
            "string",
            "null"
          ]
        },
        "total_phases": {
          "type": "integer"
        },
        "phases": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "id",
              "title",
              "type",
              "required",
              "order",
              "components",
              "display_mode",
              "screen_count"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "required": {
                "type": "boolean"
              },
              "order": {
                "type": "integer"
              },
              "display_mode": {
                "enum": [
                  "sequential",
                  "stacked"
                ],
                "description": "Added 2026-09-03. \"sequential\" = one screen at a time with Continue; \"stacked\" = the phase scrolls as one screen."
              },
              "screen_count": {
                "type": "integer",
                "minimum": 1,
                "description": "Added 2026-09-03. Number of distinct screen_index values in this phase."
              },
              "components": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "type",
                    "reveal_after",
                    "screen_index",
                    "screen_role"
                  ],
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "type": {
                      "type": "string"
                    },
                    "reveal_after": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "reveals_on_answer": {
                      "type": "boolean"
                    },
                    "screen_index": {
                      "type": "integer",
                      "minimum": 0,
                      "description": "Added 2026-09-03. 0-based screen within the phase."
                    },
                    "screen_role": {
                      "enum": [
                        "primary",
                        "attached"
                      ],
                      "description": "Added 2026-09-03. \"primary\" starts a screen and is what Continue advances from; \"attached\" shares the preceding primary's screen."
                    },
                    "anchor_id": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        },
        "learning_objectives": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "accreditation": {
          "type": [
            "object",
            "null"
          ]
        },
        "series": {
          "type": [
            "object",
            "null"
          ]
        },
        "follow_up": {
          "$ref": "#/definitions/FollowUp"
        },
        "media_expires_at": {
          "type": "string",
          "format": "date-time"
        }
      }
    },
    "FollowUp": {
      "type": [
        "object",
        "null"
      ],
      "required": [
        "intervals_days",
        "email",
        "landing",
        "commitment",
        "survey"
      ],
      "properties": {
        "intervals_days": {
          "type": "array",
          "items": {
            "type": "integer",
            "minimum": 1
          }
        },
        "email": {
          "type": "object",
          "required": [
            "subject",
            "intro",
            "cta_label"
          ],
          "properties": {
            "subject": {
              "type": "string"
            },
            "intro": {
              "type": "string"
            },
            "cta_label": {
              "type": "string"
            }
          }
        },
        "landing": {
          "type": "object",
          "required": [
            "title",
            "intro",
            "accreditation_note"
          ],
          "properties": {
            "title": {
              "type": "string"
            },
            "intro": {
              "type": "string"
            },
            "accreditation_note": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        },
        "commitment": {
          "type": "object",
          "required": [
            "prompt",
            "options",
            "allow_free_text"
          ],
          "properties": {
            "prompt": {
              "type": "string"
            },
            "options": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/FollowUpOption"
              }
            },
            "allow_free_text": {
              "type": "boolean"
            }
          }
        },
        "survey": {
          "type": "object",
          "required": [
            "items",
            "barriers"
          ],
          "properties": {
            "items": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "id",
                  "prompt",
                  "type"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "prompt": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "single",
                      "multi",
                      "scale",
                      "text"
                    ]
                  },
                  "options": {
                    "type": "array",
                    "items": {
                      "$ref": "#/definitions/FollowUpOption"
                    }
                  },
                  "required": {
                    "type": "boolean"
                  },
                  "min": {
                    "type": "number"
                  },
                  "max": {
                    "type": "number"
                  },
                  "min_label": {
                    "type": "string"
                  },
                  "max_label": {
                    "type": "string"
                  }
                }
              }
            },
            "barriers": {
              "type": "array",
              "items": {
                "$ref": "#/definitions/FollowUpOption"
              }
            }
          }
        },
        "recheck": {
          "type": [
            "object",
            "null"
          ],
          "required": [
            "id",
            "stem",
            "options"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "stem": {
              "type": "string"
            },
            "options": {
              "type": "array",
              "items": {
                "type": "object",
                "required": [
                  "id",
                  "label"
                ],
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "is_correct": {
                    "type": "boolean",
                    "description": "Only emitted for API keys holding the outcomes:read scope."
                  }
                }
              }
            },
            "rationale": {
              "type": [
                "string",
                "null"
              ]
            }
          }
        }
      }
    },
    "WhoAmI": {
      "type": "object",
      "required": [
        "organization_id",
        "name",
        "scopes"
      ],
      "properties": {
        "organization_id": {
          "type": [
            "string",
            "null"
          ],
          "format": "uuid"
        },
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "scopes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    },
    "FollowUpOption": {
      "type": "object",
      "required": [
        "id",
        "label"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "label": {
          "type": "string"
        }
      }
    }
  }
}