{
  "openapi": "3.1.1",
  "info": {
    "title": "Lissa Health Public Partner API",
    "version": "1.0.0-draft.3",
    "summary": "Public API for file processing, document extraction, audio transcription, and job management.",
    "description": "Partner API for uploading files, extracting structured data from documents, transcribing audio, and managing processing jobs. Authenticate with a partner API key using HTTP Bearer authentication. The API is not yet available for integration.",
    "contact": {
      "name": "Lissa Health",
      "url": "https://lissa.health"
    }
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://lissa.health/api/v1",
      "description": "PROPOSED production base path. NOT RUNNING. Exact host/path and all wire details are draft and unapproved."
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "Anonymous public gateway liveness only; does NOT assert compute readiness."
    },
    {
      "name": "Files",
      "description": "Host-owned secure transient file intake and lifecycle (R1)."
    },
    {
      "name": "Documents",
      "description": "Durable paid document operations: one document in, one JSON result out (R1)."
    },
    {
      "name": "Transcription",
      "description": "Audio transcription with diarization (R1, durable paid operation)."
    },
    {
      "name": "Jobs",
      "description": "Public durable job status, typed result, cooperative cancel and result deletion (R1)."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "operationId": "getHealth",
        "summary": "Anonymous public gateway liveness",
        "description": "Minimal anonymous liveness of the public gateway only. It does NOT confirm clinical-engine health, queue depth, balances or full compute readiness, and exposes no dependency details. No authentication.",
        "security": [],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [],
        "responses": {
          "200": {
            "description": "Gateway is alive.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "required": [
                    "status"
                  ],
                  "properties": {
                    "status": {
                      "type": "string",
                      "enum": [
                        "ok"
                      ]
                    }
                  }
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          }
        }
      }
    },
    "/files": {
      "post": {
        "tags": [
          "Files"
        ],
        "operationId": "createFile",
        "summary": "Create an immutable file snapshot (binary upload or remote URL intake)",
        "description": "Accepts either multipart/form-data with one binary file part and an optional JSON request metadata part, or application/json with a remote HTTPS source. Put idempotency_key in the JSON body or multipart request part; it is required for remote URL intake and optional for binary upload. Repeating the same key and input returns the same immutable file ID; changing the input with the same key returns 409 idempotency_conflict. A retry while intake is in progress returns 503 idempotency_in_progress with Retry-After. The key is scoped to the authenticated account and operation. Remote URL intake is limited to HTTPS and protected against requests to private or link-local addresses. File type is determined from the uploaded content. Base64 and chunked upload are not supported.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "files:write"
        ],
        "x-lissa-idempotency-required": false,
        "x-lissa-idempotency-policy": "`idempotency_key` in the request body is required for JSON URL intake and optional for binary upload. Namespace: authenticated account + environment + createFile + key. Fingerprint binds the URL or uploaded-bytes digest + canonical metadata + content type; excludes multipart boundary and key. Same key/input replays the same immutable file ID; changed input is 409 idempotency_conflict. In-flight retry is 503 idempotency_in_progress with Retry-After; retry with the same key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FileUploadUrlRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "file"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "Exactly one binary file — the only source."
                  },
                  "request": {
                    "$ref": "#/components/schemas/FileUploadMetadata"
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream",
                  "x-description": "Raw uploaded bytes; the declared part Content-Type is not trusted. The actual media type is determined by a magic-byte probe against the draft MIME allowlist."
                },
                "request": {
                  "contentType": "application/json",
                  "x-description": "Single JSON metadata part. No ambiguous string-to-boolean/array form coercion."
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Immutable file snapshot created or replayed. Both first creation and replay return 201 with the same immutable file ID; Location identifies `/v1/files/{file_id}`. Idempotency-Replayed is true on replay; initial response may be false or absent.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/File"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/ProblemBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "409": {
            "$ref": "#/components/responses/ProblemConflict"
          },
          "413": {
            "$ref": "#/components/responses/ProblemPayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/ProblemUnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ProblemUnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ProblemInternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/ProblemGatewayTimeout"
          }
        }
      }
    },
    "/files/{file_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FilePathId"
        }
      ],
      "get": {
        "tags": [
          "Files"
        ],
        "operationId": "getFile",
        "summary": "Get file metadata/status",
        "description": "Returns metadata and lifecycle status (`ready|rejected|deleted|expired`), media type, actual bytes and retention. A foreign or non-existent id resolves to 404.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "files:read"
        ],
        "responses": {
          "200": {
            "description": "File metadata.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/File"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "410": {
            "$ref": "#/components/responses/ProblemGone"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Files"
        ],
        "operationId": "deleteFile",
        "summary": "Delete a file",
        "description": "Returns 204. If active jobs still reference the file, returns 409 `file_in_use` — cancel/wait for terminal first.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "files:write"
        ],
        "responses": {
          "204": {
            "description": "File deleted (idempotent for repeated deletes).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ProblemConflict"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          }
        }
      }
    },
    "/documents": {
      "post": {
        "tags": [
          "Documents"
        ],
        "operationId": "createDocument",
        "summary": "Submit a document (durable paid operation)",
        "description": "Submit one PDF, scan, or image for structured extraction. The service selects how to read the document. Choose application/json with an existing file_id or HTTPS url, or upload the binary document and processing options together in one multipart/form-data request (file part plus JSON request part). idempotency_key is required in the request body. Set wait_seconds from 1 to 10 to wait for a completed result; if processing takes longer, the response contains the accepted job. The default is 0, which returns the job immediately. Requested features return their typed object; unrequested features are absent. classification controls whether document_info.detected_type may be returned; document_type_hint is only a hint. This service returns extracted information and is not a medical diagnosis.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "documents:process",
          "files:read"
        ],
        "x-lissa-conditional-scopes": [
          {
            "when": "source is a remote url",
            "scopes": [
              "files:write"
            ]
          },
          {
            "when": "the request is multipart/form-data with a binary file part (new upload)",
            "scopes": [
              "files:write"
            ]
          }
        ],
        "x-lissa-idempotency-required": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DocumentRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "file",
                  "request"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "request": {
                    "$ref": "#/components/schemas/MultipartDocumentRequest"
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream",
                  "x-description": "Raw uploaded bytes; the declared part Content-Type is not trusted. Actual media type is determined by a magic-byte probe against the draft MIME allowlist."
                },
                "request": {
                  "contentType": "application/json",
                  "x-description": "Single JSON part. No ambiguous string-to-boolean/array form coercion."
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation completed within wait_seconds; identical schema to GET /jobs/{job_id}/result.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "X-Lissa-Job-Id": {
                "$ref": "#/components/headers/XLissaJobId"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DocumentResult"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/JobAccepted"
          },
          "400": {
            "$ref": "#/components/responses/ProblemBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/ProblemPaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ProblemConflict"
          },
          "413": {
            "$ref": "#/components/responses/ProblemPayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/ProblemUnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ProblemUnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ProblemInternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/ProblemGatewayTimeout"
          }
        }
      }
    },
    "/transcriptions": {
      "post": {
        "tags": [
          "Transcription"
        ],
        "operationId": "createTranscription",
        "summary": "Submit an audio transcription (durable paid operation)",
        "description": "Submit one audio file for transcription. Choose application/json with an existing file_id or HTTPS url, or upload the audio and transcription options together in one multipart/form-data request (file part plus JSON request part). idempotency_key is required in the request body. Set wait_seconds from 1 to 10 to wait for a completed result; if processing takes longer, the response contains the accepted job. The default is 0, which returns the job immediately. Results include recognized text and timed segments; speaker labels distinguish voices and do not identify people or clinical roles.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "transcriptions:create",
          "files:read"
        ],
        "x-lissa-conditional-scopes": [
          {
            "when": "source is a remote url",
            "scopes": [
              "files:write"
            ]
          },
          {
            "when": "the request is multipart/form-data with a binary file part (new upload)",
            "scopes": [
              "files:write"
            ]
          }
        ],
        "x-lissa-idempotency-required": true,
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TranscriptionRequest"
              }
            },
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "file",
                  "request"
                ],
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "request": {
                    "$ref": "#/components/schemas/MultipartTranscriptionRequest"
                  }
                }
              },
              "encoding": {
                "file": {
                  "contentType": "application/octet-stream",
                  "x-description": "Raw uploaded bytes; the declared part Content-Type is not trusted. Actual media type is determined by a magic-byte probe against the draft MIME allowlist."
                },
                "request": {
                  "contentType": "application/json",
                  "x-description": "Single JSON part. No ambiguous string-to-boolean/array form coercion."
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Operation completed within wait_seconds; same schema as GET /jobs/{job_id}/result.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "X-Lissa-Job-Id": {
                "$ref": "#/components/headers/XLissaJobId"
              },
              "Idempotency-Replayed": {
                "$ref": "#/components/headers/IdempotencyReplayed"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TranscriptionResult"
                }
              }
            }
          },
          "202": {
            "$ref": "#/components/responses/JobAccepted"
          },
          "400": {
            "$ref": "#/components/responses/ProblemBadRequest"
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "402": {
            "$ref": "#/components/responses/ProblemPaymentRequired"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ProblemConflict"
          },
          "413": {
            "$ref": "#/components/responses/ProblemPayloadTooLarge"
          },
          "415": {
            "$ref": "#/components/responses/ProblemUnsupportedMediaType"
          },
          "422": {
            "$ref": "#/components/responses/ProblemUnprocessableEntity"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "500": {
            "$ref": "#/components/responses/ProblemInternalServerError"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          },
          "504": {
            "$ref": "#/components/responses/ProblemGatewayTimeout"
          }
        }
      }
    },
    "/jobs/{job_id}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobIdPath"
        }
      ],
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "getJob",
        "summary": "Get job status/metadata",
        "description": "Returns metadata/status, usage, safe error and result URL WITHOUT an embedded medical payload. A failed job still returns 200 because the status query succeeded. Execution status is exactly `queued|processing|cancel_requested|completed|failed|cancelled`; `result_availability` is a separate axis. Progress/ETA are advisory and nullable. A purged operational tombstone resolves to 404.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "jobs:read"
        ],
        "responses": {
          "200": {
            "description": "Job metadata/status.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          }
        }
      }
    },
    "/jobs/{job_id}/result": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobIdPath"
        }
      ],
      "get": {
        "tags": [
          "Jobs"
        ],
        "operationId": "getJobResult",
        "summary": "Get the typed final result",
        "description": "Returns the final product payload; the same result schema as a short sync response. `type` discriminates (`document|transcription`). 200 only when completed and the payload is available; 409 `result_not_ready` for an active job and `job_not_completed` for failed/cancelled; 410 `result_expired|result_deleted` after purge. The product scope is determined by the job type. A failed/cancelled job never exposes a partial payload.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "jobs:read"
        ],
        "x-lissa-conditional-scopes": [
          {
            "when": "job.type == document",
            "scopes": [
              "documents:process"
            ]
          },
          {
            "when": "job.type == transcription",
            "scopes": [
              "transcriptions:create"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Available final result.",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobResult"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ProblemConflict"
          },
          "410": {
            "$ref": "#/components/responses/ProblemGone"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          }
        }
      },
      "delete": {
        "tags": [
          "Jobs"
        ],
        "operationId": "deleteJobResult",
        "summary": "Delete a terminal result early",
        "description": "Returns 204 (also for repeated deletes). Requests deletion of the terminal payload and all its temporary copies (scrub/purge). Audit/ledger metadata is not deleted. An active job returns 409 `job_not_terminal`. Requires the product scope of the job plus `results:delete`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "results:delete"
        ],
        "x-lissa-conditional-scopes": [
          {
            "when": "job.type == document",
            "scopes": [
              "documents:process"
            ]
          },
          {
            "when": "job.type == transcription",
            "scopes": [
              "transcriptions:create"
            ]
          }
        ],
        "responses": {
          "204": {
            "description": "Result deleted (idempotent).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ProblemConflict"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          }
        }
      }
    },
    "/jobs/{job_id}/cancel": {
      "parameters": [
        {
          "$ref": "#/components/parameters/JobIdPath"
        }
      ],
      "post": {
        "tags": [
          "Jobs"
        ],
        "operationId": "cancelJob",
        "summary": "Request cooperative cancellation (idempotent)",
        "description": "Returns 202 + updated job when the cancellation request is accepted; 200 for an already `cancel_requested`/`cancelled` job; 409 `job_already_terminal` for completed/failed. Cancellation is cooperative: after `cancel_requested` a terminal `completed`/`failed` is still allowed. On terminal `cancelled` no partial clinical payload is published (`result_availability: unavailable`); any charge covers only explicitly defined started units listed in `Usage`, never future stages or a cancel penalty. Repeated cancel never double-refunds. Requires the product scope of the job plus `jobs:cancel`.",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "x-lissa-release": "R1",
        "x-lissa-availability": "draft",
        "x-lissa-required-scopes": [
          "jobs:cancel"
        ],
        "x-lissa-conditional-scopes": [
          {
            "when": "job.type == document",
            "scopes": [
              "documents:process"
            ]
          },
          {
            "when": "job.type == transcription",
            "scopes": [
              "transcriptions:create"
            ]
          }
        ],
        "responses": {
          "200": {
            "description": "Already cancel_requested/cancelled (idempotent).",
            "headers": {
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "202": {
            "description": "Cancellation accepted; cooperative cancellation in progress.",
            "headers": {
              "Location": {
                "$ref": "#/components/headers/Location"
              },
              "X-Lissa-Job-Id": {
                "$ref": "#/components/headers/XLissaJobId"
              },
              "Retry-After": {
                "$ref": "#/components/headers/RetryAfter"
              },
              "X-Request-Id": {
                "$ref": "#/components/headers/XRequestId"
              },
              "Cache-Control": {
                "$ref": "#/components/headers/CacheControlNoStore"
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Job"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/ProblemUnauthorized"
          },
          "403": {
            "$ref": "#/components/responses/ProblemForbidden"
          },
          "404": {
            "$ref": "#/components/responses/ProblemNotFound"
          },
          "409": {
            "$ref": "#/components/responses/ProblemConflict"
          },
          "429": {
            "$ref": "#/components/responses/ProblemTooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/ProblemServiceUnavailable"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "lhp_live_... | lhp_test_...",
        "description": "Partner API key. The prefix is a hint only; the server verifies the actual environment permission and key status on every request. Scopes are NOT modelled here (empty scopes array); required permissions are declared per operation via x-lissa-required-scopes / x-lissa-conditional-scopes."
      }
    },
    "headers": {
      "XRequestId": {
        "description": "Safe request correlation id; echoed in Problem.request_id.",
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "CacheControlNoStore": {
        "description": "PHI responses must not be cached.",
        "schema": {
          "type": "string",
          "enum": [
            "no-store"
          ]
        }
      },
      "Location": {
        "description": "Resource URL, e.g. /v1/jobs/{job_id}.",
        "schema": {
          "type": "string",
          "format": "uri-reference"
        }
      },
      "XLissaJobId": {
        "description": "Public job id.",
        "schema": {
          "$ref": "#/components/schemas/OpaqueId"
        }
      },
      "IdempotencyReplayed": {
        "description": "True when this response replays an existing paid job OR file-intake result for the same idempotency key and fingerprint. Initial creation may be false or omit the header.",
        "schema": {
          "type": "boolean"
        }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying; present on 202 submit, 429 and 503.",
        "schema": {
          "type": "integer",
          "minimum": 0
        }
      }
    },
    "parameters": {
      "FilePathId": {
        "name": "file_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      },
      "JobIdPath": {
        "name": "job_id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        }
      }
    },
    "responses": {
      "JobAccepted": {
        "description": "The job has been durably accepted. Returned immediately when wait_seconds is 0 or when processing does not finish within the requested wait.",
        "headers": {
          "Location": {
            "$ref": "#/components/headers/Location"
          },
          "X-Lissa-Job-Id": {
            "$ref": "#/components/headers/XLissaJobId"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "Idempotency-Replayed": {
            "$ref": "#/components/headers/IdempotencyReplayed"
          },
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Job"
            }
          }
        }
      },
      "ProblemBadRequest": {
        "description": "400 — malformed request or missing/invalid idempotency_key (required for URL intake and compute operations; optional for binary file upload). code: invalid_request.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemUnauthorized": {
        "description": "401 — invalid/expired/revoked key. code: invalid_key.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemPaymentRequired": {
        "description": "402 — insufficient balance or spend cap exceeded; the computation is not accepted. codes: insufficient_balance, spend_cap_exceeded.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemForbidden": {
        "description": "403 — the key lacks a required scope for its own resource. code: insufficient_scope.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemNotFound": {
        "description": "404 — not found or foreign resource (also a purged tombstone). An opaque id does not replace authorization. code: resource_not_found.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemConflict": {
        "description": "409 — changed idempotency fingerprint, resource not ready/in use, or terminal cancel. codes: idempotency_conflict, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, file_in_use. A transient same-key intake already in progress uses 503 idempotency_in_progress with Retry-After, not an ambiguous conflict.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemGone": {
        "description": "410 — payload expired/deleted. codes: result_expired, result_deleted.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemPayloadTooLarge": {
        "description": "413 — byte limit exceeded. code: payload_too_large.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemUnsupportedMediaType": {
        "description": "415 — unsupported media type (allowlist is explicit; probe-based). code: unsupported_media_type.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemUnprocessableEntity": {
        "description": "422 — schema/page/duration/context validation failed; request well-formed but not acceptable. code: validation_failed.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemTooManyRequests": {
        "description": "429 — rate/concurrency/quota limit. code: rate_limit_exceeded. Retry-After present.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemInternalServerError": {
        "description": "500 — internal error; a commit may still have happened. code: internal_error. Retry only with the same `idempotency_key` in the request body.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemServiceUnavailable": {
        "description": "503 — billing/admission/engine temporarily unavailable or same-key file intake is still in progress. codes: admission_unavailable, billing_unavailable, engine_unavailable, idempotency_in_progress. For idempotency_in_progress, Retry-After is present and the client safely retries the same key. Retry compute requests with the same `idempotency_key` in the request body; compute is not started when billing/DB is unavailable (fail-closed). Retry-After present.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          },
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      },
      "ProblemGatewayTimeout": {
        "description": "504 — intake/transport timeout; a commit may still have happened. code: intake_timeout. Retry only with the same `idempotency_key` in the request body.",
        "headers": {
          "X-Request-Id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlNoStore"
          }
        },
        "content": {
          "application/problem+json": {
            "schema": {
              "$ref": "#/components/schemas/Problem"
            }
          }
        }
      }
    },
    "schemas": {
      "Problem": {
        "title": "Problem",
        "description": "RFC 9457 problem details document returned for typed errors (media type application/problem+json). `code` is a safe, machine-readable, PHI-free error code; known codes include invalid_request, insufficient_scope, invalid_key, insufficient_balance, spend_cap_exceeded, resource_not_found, idempotency_conflict, file_in_use, result_not_ready, job_not_completed, job_already_terminal, job_not_terminal, result_expired, result_deleted, payload_too_large, unsupported_media_type, validation_failed, rate_limit_exceeded, admission_unavailable, billing_unavailable, engine_unavailable, intake_timeout, document_unreadable, job_deadline_exceeded, internal_error. The code set is additive; it is not a closed enum. RFC 9457 extension members are permitted.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "title",
          "status",
          "code",
          "request_id",
          "retryable"
        ],
        "properties": {
          "type": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048,
            "description": "Problem type URI; draft base https://lissa.health/problems/... is not a running service."
          },
          "title": {
            "type": "string",
            "minLength": 1,
            "maxLength": 200
          },
          "status": {
            "type": "integer",
            "minimum": 400,
            "maximum": 599
          },
          "detail": {
            "type": "string",
            "maxLength": 2000,
            "description": "Human-readable, PHI-free. Never quotes a rejected value or medical content."
          },
          "code": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9_]*$",
            "description": "Safe machine code (additive set, see description)."
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200,
            "description": "Optional offending parameter name, e.g. `idempotency_key`."
          },
          "request_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Safe request correlation id (also returned in X-Request-Id)."
          },
          "retryable": {
            "type": "boolean"
          }
        }
      },
      "IdempotencyKey": {
        "title": "IdempotencyKey",
        "description": "Client-generated key for safely retrying the same request. Use a unique value for each distinct operation; do not include personal or medical information.",
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "pattern": "^[\\x20-\\x7E]+$"
      },
      "FileUploadUrlRequest": {
        "title": "FileUploadUrlRequest",
        "description": "JSON body for POST /files remote-URL intake. The downloaded object becomes an immutable file snapshot after validation.",
        "type": "object",
        "additionalProperties": false,
        "required": [
          "source",
          "idempotency_key"
        ],
        "properties": {
          "idempotency_key": {
            "$ref": "#/components/schemas/IdempotencyKey"
          },
          "source": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "pattern": "^https://",
                "maxLength": 2048
              }
            }
          }
        }
      },
      "FileUploadMetadata": {
        "title": "FileUploadMetadata",
        "description": "Optional JSON metadata part accompanying a multipart POST /files. It never carries a second binary source and never carries account/environment/patient/user ownership. Fields here are intentionally minimal pending the final intake contract.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "filename": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "idempotency_key": {
            "$ref": "#/components/schemas/IdempotencyKey"
          }
        }
      },
      "Timestamp": {
        "title": "Timestamp",
        "description": "RFC 3339 date-time normalized to UTC with a trailing 'Z'. Operation created/completed/expiry timestamps are UTC instants; medical dates may be partial and are modelled separately, never coerced into a fabricated instant.",
        "type": "string",
        "format": "date-time",
        "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}:[0-9]{2}:[0-9]{2}(\\.[0-9]+)?Z$"
      },
      "OpaqueId": {
        "title": "OpaqueId",
        "description": "Opaque, account/environment-scoped identifier supplied by Lissa. It is a non-empty string, NOT forced to UUID; clients must treat it as opaque and never parse meaning or reuse it across accounts/environments. Authorization is checked independently of the identifier value (an opaque id does not replace authorization).",
        "type": "string",
        "minLength": 1,
        "maxLength": 128
      },
      "NullableTimestamp": {
        "title": "NullableTimestamp",
        "description": "A Timestamp that may be null (e.g. not yet terminal). The nullable union preserves the full UTC date-time shape; a null is a real 'no instant yet' and is never a fabricated time.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/Timestamp"
          },
          {
            "type": "null"
          }
        ]
      },
      "JobError": {
        "title": "JobError",
        "description": "Safe terminal job error. Never a raw provider exception or medical payload. A failed/cancelled job exposes no partial result payload.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code",
          "retryable",
          "request_id"
        ],
        "properties": {
          "code": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "retryable": {
            "type": "boolean"
          },
          "request_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          }
        }
      },
      "File": {
        "title": "File",
        "description": "Immutable public file resource metadata. Lifecycle status: ready | rejected | deleted | expired. Media type is determined by probe/magic bytes, not by filename/Content-Type alone. Retention is a draft policy subject to load/legal confirmation.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "status",
          "media_type",
          "byte_size",
          "created_at"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "status": {
            "type": "string",
            "enum": [
              "ready",
              "rejected",
              "deleted",
              "expired"
            ]
          },
          "media_type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 255
          },
          "byte_size": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2000000000
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "expires_at": {
            "$ref": "#/components/schemas/NullableTimestamp"
          },
          "source": {
            "type": "string",
            "enum": [
              "upload",
              "url"
            ]
          },
          "page_count": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "maximum": 100000
          },
          "rejection": {
            "$ref": "#/components/schemas/JobError"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "const": "ready"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "required": [
                "expires_at"
              ],
              "properties": {
                "expires_at": {
                  "$ref": "#/components/schemas/Timestamp"
                }
              }
            }
          }
        ]
      },
      "DocumentOptions": {
        "title": "DocumentOptions",
        "description": "Document-processing options. Defaults match RFC v6 01 §1.1. `split_oversized` is an internal step after the page threshold, not a separate public product. `max_pages_per_part` never increases the billable page count. Unknown/non-convertible units remain raw with a warning, never a fabricated conversion. How a document is read (text layer vs. image recognition) is NOT a client option: the service decides internally.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "split_oversized": {
            "type": "boolean",
            "default": true
          },
          "max_pages_per_part": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20,
            "default": 20
          },
          "standardize_units": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "Billing": {
        "title": "Billing",
        "description": "Optional per-request cost ceiling supplied by the caller. The server always additionally applies its own bounded estimate and account/key spend caps; the effective ceiling is the minimum of all of them and can never be raised without a new authorized request.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "max_charge_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "Optional caller cost ceiling in integer minor units (gross, before refund). Absent means the caller supplies no cap; an explicit `null` is rejected in this draft (use absence). No concrete product/GA money maximum is approved: any technical safety scalar added later is a draft candidate, not a published product limit."
          }
        }
      },
      "DocumentRequestFields": {
        "title": "DocumentRequestFields",
        "description": "Non-file fields of POST /documents. Reused verbatim as the JSON `request` part of a multipart upload, so the file and processing options can be submitted in one request. `idempotency_key` is required. `wait_seconds` requests a bounded synchronous wait; if the result is not ready by then, the response contains the accepted job. Requested features return their typed object; unrequested features are absent. `classification` alone controls whether `document_info.detected_type` may be emitted; an unrequested classification means that field is absent, and `document_type_hint` never requests or forces classification. The public request never chooses text-vs-image processing — the service decides that internally. A request is never silently downgraded to another product/tariff. `languages` cannot mix `auto` with explicit languages.",
        "type": "object",
        "required": [
          "idempotency_key"
        ],
        "properties": {
          "idempotency_key": {
            "$ref": "#/components/schemas/IdempotencyKey"
          },
          "wait_seconds": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10,
            "default": 0,
            "description": "Maximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned."
          },
          "features": {
            "type": "array",
            "minItems": 1,
            "maxItems": 5,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "enum": [
                "classification",
                "text",
                "layout",
                "biomarkers",
                "entities"
              ]
            },
            "default": [
              "classification",
              "text",
              "biomarkers",
              "entities"
            ],
            "description": "Non-empty unique feature set. Fixed default does not mean 'all future features'. Requesting `classification` permits a measured `document_info.detected_type`; without it that field is absent. `document_type_hint` is only a hint and never enables classification. The runtime mapper must enforce this request/response relationship; the schema does not infer it from a separate request."
          },
          "document_type_hint": {
            "type": "string",
            "enum": [
              "lab",
              "discharge",
              "prescription",
              "ultrasound",
              "ct",
              "mri",
              "xray",
              "other",
              "auto"
            ],
            "default": "auto",
            "description": "Optional hint; never substitutes for the actual detected classification."
          },
          "languages": {
            "oneOf": [
              {
                "type": "array",
                "items": {
                  "const": "auto"
                },
                "minItems": 1,
                "maxItems": 1
              },
              {
                "type": "array",
                "minItems": 1,
                "maxItems": 8,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "enum": [
                    "ru",
                    "en"
                  ]
                }
              }
            ],
            "default": [
              "auto"
            ],
            "description": "`auto` must not be mixed with explicit languages. Explicit support is ru/en in the draft."
          },
          "options": {
            "$ref": "#/components/schemas/DocumentOptions"
          },
          "billing": {
            "$ref": "#/components/schemas/Billing"
          }
        }
      },
      "FileSource": {
        "title": "FileSource",
        "description": "Exactly one input source for a compute operation: an immutable host `file_id` (preferred for sequential operations) or a bounded HTTPS `url` intake. `oneOf` forbids supplying both or neither. Base64, provider selection and caller-supplied account/environment/patient/user fields are NOT supported in R1. Remote URL intake additionally requires the `files:write` scope and a required `idempotency_key` in the request body; URL fetch is SSRF-guarded (HTTPS only, no private/loopback/link-local/metadata targets, bounded redirects/bytes/time).",
        "oneOf": [
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "file_id"
            ],
            "properties": {
              "file_id": {
                "$ref": "#/components/schemas/OpaqueId"
              }
            }
          },
          {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "url"
            ],
            "properties": {
              "url": {
                "type": "string",
                "format": "uri",
                "pattern": "^https://",
                "maxLength": 2048,
                "description": "Bounded HTTPS source URL. Credentials in the URL and arbitrary outbound headers are forbidden. A changed URL string under the same `idempotency_key` is a conflict."
              }
            }
          }
        ]
      },
      "DocumentRequest": {
        "title": "DocumentRequest",
        "description": "JSON body of POST /documents: exactly one FileSource plus the shared non-file fields. Unknown fields are rejected. One document in; the service decides how to read it.",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/DocumentRequestFields"
          },
          {
            "type": "object",
            "required": [
              "file"
            ],
            "properties": {
              "file": {
                "$ref": "#/components/schemas/FileSource"
              }
            }
          }
        ],
        "unevaluatedProperties": false
      },
      "MultipartDocumentRequest": {
        "title": "MultipartDocumentRequest",
        "description": "The single JSON `request` part of POST /documents multipart upload. It carries the same non-file fields as the JSON request, including `idempotency_key` and `wait_seconds`, and MUST NOT contain `file` (the binary `file` part is the only source). Validated by the same JSON Schema; no ambiguous string-to-boolean/array form coercion.",
        "type": "object",
        "$ref": "#/components/schemas/DocumentRequestFields",
        "unevaluatedProperties": false
      },
      "DocumentInfo": {
        "title": "DocumentInfo",
        "description": "Measured document-level facts. `page_count` and `languages` are measured metadata and remain required. `detected_type` is optional and is present only when the `classification` feature was requested and classification was measured; when that feature is not requested it is absent. A `document_type_hint` neither requests classification nor creates this field. Runtime mapper logic must align response feature presence with the request; JSON Schema validates shape only.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "page_count",
          "languages"
        ],
        "properties": {
          "detected_type": {
            "type": "string",
            "enum": [
              "lab",
              "discharge",
              "prescription",
              "ultrasound",
              "ct",
              "mri",
              "xray",
              "other",
              "unknown"
            ]
          },
          "page_count": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "languages": {
            "type": "array",
            "maxItems": 32,
            "uniqueItems": true,
            "items": {
              "type": "string",
              "maxLength": 16
            }
          }
        }
      },
      "TextFragment": {
        "title": "TextFragment",
        "description": "Contiguous text unit from the source text layer. `page_number` is 1-based and preserved across internal split. Locators are emitted only when actually available; a bbox/offset is never fabricated for text-only extraction.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "page_number",
          "text"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "page_number": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "text": {
            "type": "string",
            "maxLength": 2000000
          },
          "source_text": {
            "type": "string",
            "maxLength": 2000000
          },
          "locator": {
            "description": "Typed locator. `text_quote` requires `exact`; `page_bbox` requires `bbox` [x0, y0, x1, y1] normalized 0..1 from top-left after rotation. Unknown additive metadata is tolerated, while known locator keys from the incompatible variant are explicitly rejected. Emitted only when actually available; ordering/consistency is a runtime check, not schema-proven.",
            "oneOf": [
              {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "type",
                  "exact"
                ],
                "properties": {
                  "type": {
                    "const": "text_quote"
                  },
                  "exact": {
                    "type": "string",
                    "maxLength": 20000
                  },
                  "bbox": false,
                  "start": false,
                  "end": false
                }
              },
              {
                "type": "object",
                "additionalProperties": true,
                "required": [
                  "type",
                  "bbox"
                ],
                "properties": {
                  "type": {
                    "const": "page_bbox"
                  },
                  "exact": false,
                  "start": false,
                  "end": false,
                  "bbox": {
                    "type": "array",
                    "minItems": 4,
                    "maxItems": 4,
                    "items": {
                      "type": "number",
                      "minimum": 0,
                      "maximum": 1
                    },
                    "description": "[x0, y0, x1, y1] normalized 0..1 from top-left, after rotation. Emitted only when coordinates are actually available."
                  }
                }
              }
            ]
          }
        }
      },
      "Text": {
        "title": "Text",
        "description": "Extracted document text. Only requested/available representations are populated.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "plain",
          "fragments"
        ],
        "properties": {
          "plain": {
            "type": "string",
            "maxLength": 10000000
          },
          "markdown": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 10000000
          },
          "fragments": {
            "type": "array",
            "maxItems": 100000,
            "items": {
              "$ref": "#/components/schemas/TextFragment"
            }
          }
        }
      },
      "Origin": {
        "type": "string",
        "enum": [
          "source",
          "inferred",
          "generated"
        ],
        "description": "Provenance of a fact: extracted from a source, inferred by a rule/model, or generated (e.g. synthesized text)."
      },
      "CodingProvenance": {
        "type": "object",
        "additionalProperties": true,
        "minProperties": 1,
        "description": "Where a coding/candidate came from. For a verified Coding at least one non-empty source_id/source_ref/pipeline_version/profile_ref is required (enforced by Coding.verified).",
        "properties": {
          "origin": {
            "$ref": "#/components/schemas/Origin"
          },
          "source_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "source_ref": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512,
            "description": "Explicit typed reference to the release/rule record backing the claim."
          },
          "pipeline_version": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "profile_ref": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          }
        }
      },
      "CodingContext": {
        "type": "object",
        "additionalProperties": true,
        "description": "Terminology context needed to judge a mapping (LOINC-style axes plus lab-specific context). At least one axis must carry an ACTUAL non-empty value, or an explicit typed reference must be supplied; a context whose axes are all null is rejected. Absence of a needed axis is expressed through Mapping.missing_context, not invented here. Context lookup is a runtime/dictionary concern; this schema only records what was actually known.",
        "properties": {
          "component": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "property": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "time_aspect": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "specimen": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "scale": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "method": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "measurement_standard": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "reference": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512,
            "description": "Explicit typed reference to a terminology context record; resolved by the runtime dictionary gate."
          }
        },
        "anyOf": [
          {
            "required": [
              "component"
            ],
            "properties": {
              "component": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "property"
            ],
            "properties": {
              "property": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "time_aspect"
            ],
            "properties": {
              "time_aspect": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "specimen"
            ],
            "properties": {
              "specimen": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "scale"
            ],
            "properties": {
              "scale": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "method"
            ],
            "properties": {
              "method": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "measurement_standard"
            ],
            "properties": {
              "measurement_standard": {
                "type": "string",
                "minLength": 1
              }
            }
          },
          {
            "required": [
              "reference"
            ],
            "properties": {
              "reference": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        ]
      },
      "Coding": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "system",
          "code",
          "mapping_status"
        ],
        "description": "A selected terminology code (or a mapping candidate). Codes are STRINGS even for numeric-looking terminologies such as SNOMED. mapping_status=verified requires a non-empty version, a curated (non-LLM) mapping source from the curated enum, a non-empty recorded context axis (or typed reference) and provenance carrying a non-empty source/profile/pipeline identifier; this rejects the LLM-suggestion/null/unavailable-as-verified and all-null-context shapes at schema level, while full dictionary membership/equivalence validation remains a runtime gate. Candidates (mapping_status=candidate) may legitimately carry an llm_suggestion source. source and standardized values carry separate codings because a converted value (e.g. different property/mass-vs-molar) does not keep the original code automatically.",
        "properties": {
          "system": {
            "type": "string",
            "minLength": 1,
            "maxLength": 2048,
            "format": "uri",
            "description": "Terminology system URI, e.g. http://loinc.org. The normative format:uri keyword is declared here and planned for enforcement by the approved Ajv validation gate; system-domain resolution/lookup (which release a code belongs to) remains a runtime/dictionary gate."
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "display": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "version": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "mapping_status": {
            "enum": [
              "verified",
              "candidate",
              "ambiguous",
              "unmapped"
            ]
          },
          "mapping_source": {
            "enum": [
              "curated_dictionary",
              "curated_release",
              "rule_engine",
              "external_authority",
              "manual_review",
              "llm_suggestion",
              null
            ]
          },
          "relationship": {
            "enum": [
              "equivalent",
              "wider",
              "narrower",
              "inexact",
              "related_to",
              "unmapped",
              null
            ]
          },
          "provenance": {
            "$ref": "#/components/schemas/CodingProvenance"
          },
          "context": {
            "$ref": "#/components/schemas/CodingContext"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "mapping_status": {
                  "const": "verified"
                }
              },
              "required": [
                "mapping_status"
              ]
            },
            "then": {
              "required": [
                "version",
                "mapping_source",
                "context",
                "provenance",
                "relationship"
              ],
              "properties": {
                "version": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "context": true,
                "mapping_source": {
                  "enum": [
                    "curated_dictionary",
                    "curated_release",
                    "rule_engine",
                    "external_authority",
                    "manual_review"
                  ]
                },
                "relationship": {
                  "type": "string",
                  "minLength": 1
                },
                "provenance": {
                  "anyOf": [
                    {
                      "type": "object",
                      "required": [
                        "source_id"
                      ],
                      "properties": {
                        "source_id": {
                          "type": "string",
                          "minLength": 1
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "source_ref"
                      ],
                      "properties": {
                        "source_ref": {
                          "type": "string",
                          "minLength": 1
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "pipeline_version"
                      ],
                      "properties": {
                        "pipeline_version": {
                          "type": "string",
                          "minLength": 1
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": [
                        "profile_ref"
                      ],
                      "properties": {
                        "profile_ref": {
                          "type": "string",
                          "minLength": 1
                        }
                      }
                    }
                  ]
                }
              }
            }
          }
        ]
      },
      "MedicalOpaqueId": {
        "type": "string",
        "minLength": 1,
        "maxLength": 128,
        "description": "Opaque identifier. Clients must not parse structure out of it."
      },
      "RawObservation": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "name",
          "value",
          "unit",
          "reference_range"
        ],
        "description": "Raw, unmodified source fields. The original name/value/unit/reference_range keys are ALWAYS present even when a standardized form exists; an individually unknown field is carried as null, never dropped or fabricated. notes is optional.",
        "properties": {
          "name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "value": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20000
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "reference_range": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000
          }
        }
      },
      "QuantityValue": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "value",
          "comparator"
        ],
        "description": "Numeric quantity. comparator=null means equality; '<' means the measured value is strictly below 'value' (censored/limit-of-detection style). unit is null when unknown; ucum_code is optional/nullable and must not be invented.",
        "properties": {
          "type": {
            "const": "quantity"
          },
          "value": {
            "type": "number"
          },
          "comparator": {
            "enum": [
              null,
              "<",
              "<=",
              ">",
              ">="
            ]
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "ucum_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64
          }
        }
      },
      "CodedValue": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "code"
        ],
        "description": "Coded qualitative result (e.g. 'not detected'). code is a STRING; a negative finding is never represented as numeric zero.",
        "properties": {
          "type": {
            "const": "coded"
          },
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "display": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "coding": {
            "$ref": "#/components/schemas/Coding"
          }
        }
      },
      "TextValue": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "text"
        ],
        "description": "Original qualitative text result preserved as-is.",
        "properties": {
          "type": {
            "const": "text"
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000
          }
        }
      },
      "RangeValue": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type"
        ],
        "description": "Interval result. At least one NUMERIC bound is required (a present-but-null bound does not count). Inclusive flags describe whether a bound is included; null means unknown.",
        "properties": {
          "type": {
            "const": "range"
          },
          "low": {
            "type": [
              "number",
              "null"
            ]
          },
          "high": {
            "type": [
              "number",
              "null"
            ]
          },
          "low_inclusive": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "high_inclusive": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "ucum_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64
          }
        },
        "anyOf": [
          {
            "required": [
              "low"
            ],
            "properties": {
              "low": {
                "type": "number"
              }
            }
          },
          {
            "required": [
              "high"
            ],
            "properties": {
              "high": {
                "type": "number"
              }
            }
          }
        ]
      },
      "RatioValue": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "numerator",
          "denominator"
        ],
        "description": "Ratio such as a titre (1:160). The denominator must be non-zero.",
        "properties": {
          "type": {
            "const": "ratio"
          },
          "numerator": {
            "type": "number"
          },
          "denominator": {
            "type": "number",
            "not": {
              "const": 0
            }
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "ucum_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64
          }
        }
      },
      "AbsentValue": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "reason"
        ],
        "description": "Explicitly absent value with a typed reason, instead of a fabricated zero or empty success.",
        "properties": {
          "type": {
            "const": "absent"
          },
          "reason": {
            "enum": [
              "not_reported",
              "unreadable",
              "not_applicable",
              "not_performed",
              "missing",
              "unavailable",
              "redacted",
              "unknown"
            ]
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          }
        }
      },
      "ComponentValue": {
        "description": "Value of one composite component. Composite is deliberately excluded to keep the schema bounded (no recursive self-reference).",
        "oneOf": [
          {
            "$ref": "#/components/schemas/QuantityValue"
          },
          {
            "$ref": "#/components/schemas/CodedValue"
          },
          {
            "$ref": "#/components/schemas/TextValue"
          },
          {
            "$ref": "#/components/schemas/RangeValue"
          },
          {
            "$ref": "#/components/schemas/RatioValue"
          },
          {
            "$ref": "#/components/schemas/AbsentValue"
          }
        ]
      },
      "Component": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "name",
          "value"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "value": {
            "$ref": "#/components/schemas/ComponentValue"
          }
        }
      },
      "CompositeValue": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "components"
        ],
        "description": "Typed, bounded components (e.g. systolic/diastolic). Bounded by maxItems; no unbounded recursion.",
        "properties": {
          "type": {
            "const": "composite"
          },
          "components": {
            "type": "array",
            "minItems": 1,
            "maxItems": 16,
            "items": {
              "$ref": "#/components/schemas/Component"
            }
          }
        }
      },
      "Value": {
        "description": "Tagged union of observation value types. Every variant requires an explicit type tag; an unknown/absent value is absent, not numeric zero.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/QuantityValue"
          },
          {
            "$ref": "#/components/schemas/CodedValue"
          },
          {
            "$ref": "#/components/schemas/TextValue"
          },
          {
            "$ref": "#/components/schemas/RangeValue"
          },
          {
            "$ref": "#/components/schemas/RatioValue"
          },
          {
            "$ref": "#/components/schemas/CompositeValue"
          },
          {
            "$ref": "#/components/schemas/AbsentValue"
          }
        ]
      },
      "Standardized": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "value"
        ],
        "description": "Normalized form of the same observation. Uses the SAME tagged Value union as value; codings are separate from the source codings because a converted value may change property/meaning.",
        "properties": {
          "value": {
            "$ref": "#/components/schemas/Value"
          },
          "codings": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/Coding"
            }
          }
        }
      },
      "Normalization": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "status"
        ],
        "description": "Unit/value normalization outcome. A normalized or partially_normalized status requires a non-empty rule_id and rule_version; absence of data or an unsupported conversion must be reported as not_normalized/unsupported instead of a fabricated success.",
        "properties": {
          "status": {
            "enum": [
              "normalized",
              "partially_normalized",
              "not_normalized",
              "unsupported",
              "failed",
              "ambiguous"
            ]
          },
          "rule_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "rule_version": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "source_value_type": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "target_value_type": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "enum": [
                    "normalized",
                    "partially_normalized"
                  ]
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "required": [
                "rule_id",
                "rule_version"
              ],
              "properties": {
                "rule_id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "rule_version": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                }
              }
            }
          }
        ]
      },
      "Mapping": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "status"
        ],
        "description": "Mapping outcome for one fact. status=ambiguous requires an explicit missing_context list; the list MAY be empty when ambiguity comes from competing candidates despite a complete context, and missing axes must not be invented just to fill it. status=verified requires a dictionary version and a curated mapping source from the same curated enum as Coding, and the containing Observation/Entity must include at least one verified source-fact Coding in codings[]. Alternative options live in candidates[] and must not be silently promoted to codings[]: every candidate entry must have mapping_status candidate or ambiguous, never verified. Source-fact codings belong in codings[]; standardized.codings[] alone does not satisfy this shape rule. Dictionary membership, matching coding status, and source correspondence remain runtime mapper checks.",
        "properties": {
          "status": {
            "enum": [
              "verified",
              "candidate",
              "ambiguous",
              "unmapped"
            ]
          },
          "missing_context": {
            "type": "array",
            "uniqueItems": true,
            "maxItems": 8,
            "items": {
              "enum": [
                "specimen",
                "method",
                "property",
                "time_aspect",
                "scale",
                "component",
                "measurement_standard",
                "unit"
              ]
            }
          },
          "candidates": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Coding"
                },
                {
                  "type": "object",
                  "required": [
                    "mapping_status"
                  ],
                  "properties": {
                    "mapping_status": {
                      "enum": [
                        "candidate",
                        "ambiguous"
                      ]
                    }
                  }
                }
              ]
            }
          },
          "dictionary_version": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "mapping_source": {
            "enum": [
              "curated_dictionary",
              "curated_release",
              "rule_engine",
              "external_authority",
              "manual_review",
              "llm_suggestion",
              null
            ]
          },
          "notes": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "const": "ambiguous"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "required": [
                "missing_context"
              ],
              "properties": {
                "missing_context": true
              }
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "verified"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "required": [
                "dictionary_version",
                "mapping_source"
              ],
              "properties": {
                "dictionary_version": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "mapping_source": {
                  "enum": [
                    "curated_dictionary",
                    "curated_release",
                    "rule_engine",
                    "external_authority",
                    "manual_review"
                  ]
                }
              }
            }
          }
        ]
      },
      "Population": {
        "type": "object",
        "additionalProperties": true,
        "description": "Population applicability for a reference interval or threshold. Absence of patient context does not authorize applying a population range to the patient.",
        "properties": {
          "age_min": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "age_max": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "age_unit": {
            "enum": [
              "years",
              "months",
              "days",
              "weeks",
              null
            ]
          },
          "sex": {
            "enum": [
              "male",
              "female",
              "all",
              "unknown",
              null
            ]
          },
          "pregnancy": {
            "type": [
              "boolean",
              "null"
            ]
          }
        }
      },
      "MedicalDate": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "kind",
          "value"
        ],
        "description": "A medical date/time that preserves the precision actually observed. There is no default widening to a full instant. kind=datetime is a UTC instant (RFC 3339 with trailing Z); date/year_month/year are partial dates and must not be normalized to a fabricated timestamp. observed_at and reported_at are distinct concepts and either may be null. The source contract declares normative format keywords: date-time for datetime, date for calendar dates, plus bounded patterns. The approved Ajv validation gate is planned to enforce the declared formats; this draft edit does not establish CI integration, runtime, or clinical readiness. A pattern match alone is not semantic proof of calendar validity or UTC semantics.",
        "properties": {
          "kind": {
            "enum": [
              "datetime",
              "date",
              "year_month",
              "year"
            ]
          },
          "value": {
            "type": "string",
            "minLength": 1,
            "maxLength": 64
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "datetime"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "value": {
                  "type": "string",
                  "format": "date-time",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?Z$"
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "date"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "value": {
                  "type": "string",
                  "format": "date",
                  "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "year_month"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "value": {
                  "type": "string",
                  "pattern": "^\\d{4}-(0[1-9]|1[0-2])$"
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "year"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "properties": {
                "value": {
                  "type": "string",
                  "pattern": "^\\d{4}$"
                }
              }
            }
          }
        ]
      },
      "MedicalDateNullable": {
        "oneOf": [
          {
            "type": "null"
          },
          {
            "$ref": "#/components/schemas/MedicalDate"
          }
        ],
        "description": "A medical date/time that may be explicitly null when unknown or not provided. Null must not be filled with a fabricated timestamp; precision stays as observed."
      },
      "ReferenceRange": {
        "type": "object",
        "additionalProperties": true,
        "description": "A laboratory or reference interval actually attached to a source. It is NOT a universal normal: applicability is REQUIRED and may be not_verified. A reference range must carry a meaningful value (at least one numeric bound or non-empty raw_text) and a non-empty source or source_id. A decision threshold is a separate object (DecisionThreshold).",
        "required": [
          "applicability"
        ],
        "properties": {
          "low": {
            "type": [
              "number",
              "null"
            ]
          },
          "high": {
            "type": [
              "number",
              "null"
            ]
          },
          "low_inclusive": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "high_inclusive": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "ucum_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64
          },
          "raw_text": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "source": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 512
          },
          "source_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128
          },
          "context": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "applicability": {
            "enum": [
              "not_verified",
              "verified",
              "unknown"
            ]
          },
          "population": {
            "$ref": "#/components/schemas/Population"
          },
          "observed_at": {
            "$ref": "#/components/schemas/MedicalDateNullable"
          },
          "time_aspect": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          }
        },
        "allOf": [
          {
            "anyOf": [
              {
                "required": [
                  "source"
                ],
                "properties": {
                  "source": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              },
              {
                "required": [
                  "source_id"
                ],
                "properties": {
                  "source_id": {
                    "type": "string",
                    "minLength": 1
                  }
                }
              }
            ]
          }
        ],
        "anyOf": [
          {
            "required": [
              "low"
            ],
            "properties": {
              "low": {
                "type": "number"
              }
            }
          },
          {
            "required": [
              "high"
            ],
            "properties": {
              "high": {
                "type": "number"
              }
            }
          },
          {
            "required": [
              "raw_text"
            ],
            "properties": {
              "raw_text": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        ]
      },
      "DecisionThreshold": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "source",
          "version"
        ],
        "description": "A guideline/decision threshold, kept separate from laboratory reference intervals. Requires an explicit source and version; jurisdiction is optional. Never used as a universal lab range.",
        "properties": {
          "low": {
            "type": [
              "number",
              "null"
            ]
          },
          "high": {
            "type": [
              "number",
              "null"
            ]
          },
          "unit": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "ucum_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000
          },
          "source": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          },
          "version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "jurisdiction": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 64
          },
          "applicability": {
            "enum": [
              "not_verified",
              "verified",
              "unknown"
            ]
          },
          "population": {
            "$ref": "#/components/schemas/Population"
          }
        }
      },
      "Interpretation": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code",
          "basis",
          "applicability"
        ],
        "description": "Interpretation is a comparison against a stated basis, never an automatic clinical statement that the patient is healthy. applicability is REQUIRED. basis=document_reference_range means only that the value fell within/outside the range printed on the source document. There is no universal clinical normal: a laboratory comparison must point at reference_ranges[reference_range_index] and a threshold comparison must point at decision_thresholds[threshold_index].",
        "properties": {
          "code": {
            "enum": [
              "within_reference_range",
              "below_reference_range",
              "above_reference_range",
              "indeterminate"
            ]
          },
          "basis": {
            "enum": [
              "document_reference_range",
              "laboratory_reference_range",
              "dictionary_reference_range",
              "decision_threshold",
              "not_applicable"
            ]
          },
          "applicability": {
            "enum": [
              "not_verified",
              "verified",
              "unknown"
            ]
          },
          "reference_range_index": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          },
          "threshold_index": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "basis": {
                  "enum": [
                    "laboratory_reference_range",
                    "dictionary_reference_range"
                  ]
                }
              },
              "required": [
                "basis"
              ]
            },
            "then": {
              "required": [
                "reference_range_index"
              ],
              "properties": {
                "reference_range_index": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "not": {
                "required": [
                  "threshold_index"
                ],
                "properties": {
                  "threshold_index": {
                    "type": "integer"
                  }
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "basis": {
                  "const": "decision_threshold"
                }
              },
              "required": [
                "basis"
              ]
            },
            "then": {
              "required": [
                "threshold_index"
              ],
              "properties": {
                "threshold_index": {
                  "type": "integer",
                  "minimum": 0
                }
              },
              "not": {
                "required": [
                  "reference_range_index"
                ],
                "properties": {
                  "reference_range_index": {
                    "type": "integer"
                  }
                }
              }
            }
          }
        ]
      },
      "Age": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "value",
          "unit"
        ],
        "properties": {
          "value": {
            "type": "integer",
            "minimum": 0
          },
          "unit": {
            "enum": [
              "years",
              "months",
              "days",
              "weeks"
            ]
          }
        }
      },
      "PatientContext": {
        "type": "object",
        "additionalProperties": true,
        "description": "Minimal, optional patient context, used only when a specific rule needs it. No patientId, name, caller identity or inferred sex. Gender identity is not mixed with laboratory context.",
        "properties": {
          "age_at_observation": {
            "$ref": "#/components/schemas/Age"
          },
          "sex_related_context": {
            "enum": [
              "male",
              "female",
              "unknown",
              "not_applicable",
              null
            ]
          },
          "pregnancy": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "note": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          }
        }
      },
      "TextQuoteLocator": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "exact"
        ],
        "description": "Verifiable fallback when coordinates are not available: an exact quote that must be unambiguous within the referenced fragment/source. Schema records the shape only; quote uniqueness and referential integrity are enforced at runtime.",
        "properties": {
          "type": {
            "const": "text_quote"
          },
          "exact": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000
          },
          "start": false,
          "end": false,
          "x": false,
          "y": false,
          "width": false,
          "height": false,
          "rotation": false,
          "start_seconds": false,
          "end_seconds": false
        }
      },
      "UnicodeOffsetLocator": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "start",
          "end"
        ],
        "description": "Unicode code point offsets into the referenced text fragment. end is exclusive and must be >= start.",
        "properties": {
          "type": {
            "const": "unicode_offsets"
          },
          "start": {
            "type": "integer",
            "minimum": 0
          },
          "end": {
            "type": "integer",
            "minimum": 0
          },
          "exact": false,
          "x": false,
          "y": false,
          "width": false,
          "height": false,
          "rotation": false,
          "start_seconds": false,
          "end_seconds": false
        },
        "x-note": "start<=end is validated at runtime; JSON Schema cannot express a cross-field numeric comparison portably without $data."
      },
      "PageBBoxLocator": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "x",
          "y",
          "width",
          "height"
        ],
        "description": "Normalized bounding box 0..1 relative to the top-left of the original page after rotation. page_number (1-based) and rotation metadata live on Evidence. Bbox is emitted only when coordinates are actually available; never invented for text-only extraction.",
        "properties": {
          "type": {
            "const": "page_bbox"
          },
          "x": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "y": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "width": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "height": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "rotation": {
            "type": [
              "number",
              "null"
            ],
            "description": "Optional page rotation metadata, degrees clockwise."
          },
          "exact": false,
          "start": false,
          "end": false,
          "start_seconds": false,
          "end_seconds": false
        }
      },
      "AudioSegmentLocator": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "start_seconds",
          "end_seconds"
        ],
        "description": "Audio locator expressed in seconds from the start of the original recording. end_seconds must be >= start_seconds (validated at runtime).",
        "properties": {
          "type": {
            "const": "audio_segment"
          },
          "start_seconds": {
            "type": "number",
            "minimum": 0
          },
          "end_seconds": {
            "type": "number",
            "minimum": 0
          },
          "exact": false,
          "start": false,
          "end": false,
          "x": false,
          "y": false,
          "width": false,
          "height": false,
          "rotation": false
        }
      },
      "EvidenceLocator": {
        "description": "Discriminated locator. Each variant carries the identifiers appropriate to its medium; the Evidence-level conditionals require fragment_id for text/page and segment_id for audio.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/TextQuoteLocator"
          },
          {
            "$ref": "#/components/schemas/UnicodeOffsetLocator"
          },
          {
            "$ref": "#/components/schemas/PageBBoxLocator"
          },
          {
            "$ref": "#/components/schemas/AudioSegmentLocator"
          }
        ]
      },
      "Confidence": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "kind",
          "score",
          "methodology"
        ],
        "description": "A numeric estimate is representable ONLY together with an explicit kind and a described methodology. There is no implicit or default value such as 0.99. An uncalibrated score must not be presented as the probability of being correct. kind=calibrated_probability additionally requires a non-empty measurement_ref: no calibration evidence may be imagined.",
        "properties": {
          "kind": {
            "enum": [
              "calibrated_probability",
              "uncalibrated_score",
              "heuristic_score"
            ]
          },
          "score": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "methodology": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024
          },
          "measurement_ref": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "profile_ref": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "calibrated_probability"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "required": [
                "measurement_ref"
              ],
              "properties": {
                "measurement_ref": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          }
        ]
      },
      "Evidence": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "origin",
          "source_id",
          "locator"
        ],
        "description": "Evidence for an extracted fact. Every evidence item carries a non-empty source_id. Text quote/offset/page bbox facts also require a non-empty fragment_id; audio facts require a non-empty segment_id; page bbox requires a 1-based page_number. Coordinates/offsets are never fabricated for text-only extraction.",
        "properties": {
          "origin": {
            "$ref": "#/components/schemas/Origin"
          },
          "source_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "source_type": {
            "enum": [
              "file",
              "text",
              "audio",
              "dictionary",
              "manual",
              null
            ]
          },
          "fragment_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128
          },
          "segment_id": {
            "type": [
              "string",
              "null"
            ],
            "minLength": 1,
            "maxLength": 128
          },
          "page_number": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 1,
            "description": "1-based original page number; preserved across split."
          },
          "source_text": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20000
          },
          "locator": {
            "$ref": "#/components/schemas/EvidenceLocator"
          },
          "confidence": {
            "$ref": "#/components/schemas/Confidence"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "locator": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "const": "text_quote"
                    }
                  },
                  "required": [
                    "type"
                  ]
                }
              },
              "required": [
                "locator"
              ]
            },
            "then": {
              "required": [
                "fragment_id"
              ],
              "properties": {
                "fragment_id": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "locator": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "const": "unicode_offsets"
                    }
                  },
                  "required": [
                    "type"
                  ]
                }
              },
              "required": [
                "locator"
              ]
            },
            "then": {
              "required": [
                "fragment_id"
              ],
              "properties": {
                "fragment_id": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "locator": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "const": "page_bbox"
                    }
                  },
                  "required": [
                    "type"
                  ]
                }
              },
              "required": [
                "locator"
              ]
            },
            "then": {
              "required": [
                "page_number",
                "fragment_id"
              ],
              "properties": {
                "page_number": {
                  "type": "integer",
                  "minimum": 1
                },
                "fragment_id": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "locator": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "const": "audio_segment"
                    }
                  },
                  "required": [
                    "type"
                  ]
                }
              },
              "required": [
                "locator"
              ]
            },
            "then": {
              "required": [
                "segment_id"
              ],
              "properties": {
                "segment_id": {
                  "type": "string",
                  "minLength": 1
                }
              }
            }
          }
        ]
      },
      "Warning": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 2000
          },
          "severity": {
            "enum": [
              "info",
              "warning",
              "error",
              null
            ]
          },
          "observation_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "entity_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          }
        }
      },
      "Extensions": {
        "type": "object",
        "maxProperties": 32,
        "propertyNames": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128
        },
        "additionalProperties": {
          "oneOf": [
            {
              "type": "string",
              "maxLength": 512
            },
            {
              "type": "number"
            },
            {
              "type": "boolean"
            },
            {
              "type": "null"
            }
          ]
        },
        "description": "Bounded scalar-only metadata for non-clinical extensions. Clinical meaning must use the typed fields above; arbitrary objects/arrays are rejected."
      },
      "Observation": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "factor_code",
          "raw",
          "value",
          "standardized",
          "normalization",
          "codings",
          "mapping",
          "reference_ranges",
          "decision_thresholds",
          "interpretation",
          "origin",
          "review_required"
        ],
        "description": "One reusable Observation document for document analysis (release 1) and reference normalize (release 2). factor_code is nullable and must stay null for genuinely unknown analytes (no invented canonical factor). raw is always preserved; standardized is null unless a real normalization succeeded. If mapping.status is verified, codings[] must include a verified Coding for the source fact; candidates or standardized-only codings do not satisfy this structural requirement. Dictionary membership, matching coding status, source correspondence, and clinical safety remain runtime mapper/golden-corpus checks. observed_at/reported_at preserve partial-date precision; they are distinct from operation created_at. Unknown additive response metadata is tolerated, but is not itself a clinical fact.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/MedicalOpaqueId"
          },
          "factor_code": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "display_name": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 512
          },
          "raw": {
            "$ref": "#/components/schemas/RawObservation"
          },
          "value": {
            "$ref": "#/components/schemas/Value"
          },
          "standardized": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Standardized"
              }
            ]
          },
          "normalization": {
            "$ref": "#/components/schemas/Normalization"
          },
          "codings": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/Coding"
            }
          },
          "mapping": {
            "$ref": "#/components/schemas/Mapping"
          },
          "reference_ranges": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/ReferenceRange"
            }
          },
          "decision_thresholds": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/DecisionThreshold"
            }
          },
          "interpretation": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Interpretation"
              }
            ]
          },
          "observed_at": {
            "$ref": "#/components/schemas/MedicalDateNullable"
          },
          "reported_at": {
            "$ref": "#/components/schemas/MedicalDateNullable"
          },
          "patient_context": {
            "$ref": "#/components/schemas/PatientContext"
          },
          "origin": {
            "$ref": "#/components/schemas/Origin"
          },
          "evidence": {
            "type": "array",
            "maxItems": 64,
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "review_required": {
            "type": "boolean"
          },
          "warnings": {
            "type": "array",
            "maxItems": 64,
            "items": {
              "$ref": "#/components/schemas/Warning"
            }
          },
          "confidence": {
            "$ref": "#/components/schemas/Confidence"
          },
          "extensions": {
            "$ref": "#/components/schemas/Extensions"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "origin": {
                  "const": "source"
                }
              },
              "required": [
                "origin"
              ]
            },
            "then": {
              "required": [
                "evidence"
              ],
              "properties": {
                "evidence": {
                  "type": "array",
                  "minItems": 1
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "origin": {
                  "enum": [
                    "inferred",
                    "generated"
                  ]
                }
              },
              "required": [
                "origin"
              ]
            },
            "then": {
              "properties": {
                "review_required": {
                  "const": true
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "mapping": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "enum": [
                        "candidate",
                        "ambiguous",
                        "unmapped"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              },
              "required": [
                "mapping"
              ]
            },
            "then": {
              "properties": {
                "review_required": {
                  "const": true
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "mapping": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "verified"
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              },
              "required": [
                "mapping"
              ]
            },
            "then": {
              "properties": {
                "codings": {
                  "type": "array",
                  "minItems": 1,
                  "contains": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Coding"
                      },
                      {
                        "type": "object",
                        "required": [
                          "mapping_status"
                        ],
                        "properties": {
                          "mapping_status": {
                            "const": "verified"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "normalization": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "enum": [
                        "normalized",
                        "partially_normalized"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              },
              "required": [
                "normalization"
              ]
            },
            "then": {
              "properties": {
                "standardized": {
                  "type": "object"
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "normalization": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "enum": [
                        "not_normalized",
                        "unsupported",
                        "failed",
                        "ambiguous"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              },
              "required": [
                "normalization"
              ]
            },
            "then": {
              "properties": {
                "standardized": {
                  "type": "null"
                }
              }
            }
          }
        ]
      },
      "EntityAssertion": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "polarity",
          "certainty",
          "temporality",
          "experiencer"
        ],
        "description": "Assertion metadata. A negated or family-history finding must never be surfaced as a patient-confirmed diagnosis; experiencer is explicit and the Entity rules keep family content out of the diagnosis category.",
        "properties": {
          "polarity": {
            "enum": [
              "affirmed",
              "negated",
              "uncertain",
              "hypothetical"
            ]
          },
          "certainty": {
            "enum": [
              "confirmed",
              "probable",
              "possible",
              "unconfirmed",
              "unknown"
            ]
          },
          "temporality": {
            "enum": [
              "current",
              "historical",
              "future",
              "unknown"
            ]
          },
          "experiencer": {
            "enum": [
              "patient",
              "family",
              "other",
              "unknown"
            ]
          }
        }
      },
      "Entity": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "category",
          "text",
          "assertion",
          "origin",
          "codings",
          "mapping",
          "evidence",
          "review_required"
        ],
        "description": "An extracted clinical entity. category=diagnosis is reserved for the patient; family-history content must use category=family_history. This prevents a negated family finding from becoming a patient-confirmed diagnosis. When mapping.status is verified, codings[] must include a verified source-fact Coding; candidates or standardized-only codings do not satisfy this structural rule. Dictionary membership, source correspondence, and clinical safety still require mapper/golden-corpus gates. Unknown additive response metadata is tolerated, but is not itself a clinical fact.",
        "properties": {
          "id": {
            "$ref": "#/components/schemas/MedicalOpaqueId"
          },
          "category": {
            "enum": [
              "diagnosis",
              "symptom",
              "finding",
              "lab_result",
              "vital_sign",
              "medication",
              "procedure",
              "allergy",
              "social_history",
              "family_history",
              "other"
            ]
          },
          "text": {
            "type": "string",
            "minLength": 1,
            "maxLength": 20000
          },
          "normalized_text": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 20000
          },
          "assertion": {
            "$ref": "#/components/schemas/EntityAssertion"
          },
          "codings": {
            "type": "array",
            "maxItems": 32,
            "items": {
              "$ref": "#/components/schemas/Coding"
            }
          },
          "mapping": {
            "$ref": "#/components/schemas/Mapping"
          },
          "origin": {
            "$ref": "#/components/schemas/Origin"
          },
          "evidence": {
            "type": "array",
            "maxItems": 64,
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "review_required": {
            "type": "boolean"
          },
          "confidence": {
            "$ref": "#/components/schemas/Confidence"
          },
          "observed_at": {
            "$ref": "#/components/schemas/MedicalDateNullable"
          },
          "extensions": {
            "$ref": "#/components/schemas/Extensions"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "category": {
                  "const": "diagnosis"
                }
              },
              "required": [
                "category"
              ]
            },
            "then": {
              "properties": {
                "assertion": {
                  "type": "object",
                  "properties": {
                    "experiencer": {
                      "const": "patient"
                    }
                  }
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "assertion": {
                  "type": "object",
                  "properties": {
                    "experiencer": {
                      "const": "family"
                    }
                  },
                  "required": [
                    "experiencer"
                  ]
                }
              },
              "required": [
                "assertion"
              ]
            },
            "then": {
              "properties": {
                "category": {
                  "not": {
                    "const": "diagnosis"
                  }
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "origin": {
                  "const": "source"
                }
              },
              "required": [
                "origin"
              ]
            },
            "then": {
              "required": [
                "evidence"
              ],
              "properties": {
                "evidence": {
                  "type": "array",
                  "minItems": 1
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "origin": {
                  "enum": [
                    "inferred",
                    "generated"
                  ]
                }
              },
              "required": [
                "origin"
              ]
            },
            "then": {
              "properties": {
                "review_required": {
                  "const": true
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "mapping": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "enum": [
                        "candidate",
                        "ambiguous",
                        "unmapped"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              },
              "required": [
                "mapping"
              ]
            },
            "then": {
              "properties": {
                "review_required": {
                  "const": true
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "mapping": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "verified"
                    }
                  },
                  "required": [
                    "status"
                  ]
                }
              },
              "required": [
                "mapping"
              ]
            },
            "then": {
              "properties": {
                "codings": {
                  "type": "array",
                  "minItems": 1,
                  "contains": {
                    "allOf": [
                      {
                        "$ref": "#/components/schemas/Coding"
                      },
                      {
                        "type": "object",
                        "required": [
                          "mapping_status"
                        ],
                        "properties": {
                          "mapping_status": {
                            "const": "verified"
                          }
                        }
                      }
                    ]
                  }
                }
              }
            }
          }
        ]
      },
      "LayoutBlock": {
        "title": "LayoutBlock",
        "description": "Layout block, present only when `layout` is requested and actually measured. Coordinates are normalized 0..1 after rotation; they are never fabricated.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "type"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "type": {
            "type": "string",
            "maxLength": 64
          },
          "text": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 200000
          },
          "bbox": {
            "type": "array",
            "minItems": 4,
            "maxItems": 4,
            "items": {
              "type": "number",
              "minimum": 0,
              "maximum": 1
            }
          }
        }
      },
      "LayoutPage": {
        "title": "LayoutPage",
        "description": "Per-page layout metadata. Page numbering is the original 1-based page (preserved across internal split).",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "page_number",
          "blocks"
        ],
        "properties": {
          "page_number": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "width": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "height": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0
          },
          "rotation": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": -360,
            "maximum": 360
          },
          "blocks": {
            "type": "array",
            "maxItems": 100000,
            "items": {
              "$ref": "#/components/schemas/LayoutBlock"
            }
          }
        }
      },
      "QualityWarning": {
        "title": "QualityWarning",
        "description": "Safe, machine-readable quality warning. Optional locators point at the affected observation/fragment/page/segment. Warnings never fabricate confidence or a normalized value.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "code"
        ],
        "properties": {
          "code": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9_]*$"
          },
          "observation_id": {
            "type": "string",
            "maxLength": 128
          },
          "fragment_id": {
            "type": "string",
            "maxLength": 128
          },
          "segment_id": {
            "type": "string",
            "maxLength": 128
          },
          "page_number": {
            "type": "integer",
            "minimum": 1
          },
          "message": {
            "type": "string",
            "maxLength": 500
          }
        }
      },
      "Quality": {
        "title": "Quality",
        "description": "Honest quality/coverage envelope for a result. complete | partial | failed. Coverage reports every missed page; warnings explain gaps. An empty result array means 'not found' only when coverage is sufficient. Confidence is never emitted without a described measurement method; a partial result is not a complete processing claim.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "status",
          "warnings"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "complete",
              "partial",
              "failed"
            ]
          },
          "coverage": {
            "type": [
              "object",
              "null"
            ],
            "additionalProperties": true,
            "properties": {
              "input_pages": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0
              },
              "processed_pages": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0
              },
              "failed_pages": {
                "type": "array",
                "maxItems": 100000,
                "items": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/QualityWarning"
            }
          }
        }
      },
      "DocumentPart": {
        "title": "DocumentPart",
        "description": "Bounded part manifest for an oversized-document split (RFC 01). Page ranges use ORIGINAL 1-based page numbers; evidence and warnings still reference original page IDs. `status` describes only this part, not the whole operation. Unknown additive response metadata is tolerated. Consistency with coverage/quality is a runtime check, not schema-proven, and no pipeline build is claimed.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "part_id",
          "page_start",
          "page_end",
          "status"
        ],
        "properties": {
          "part_id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "page_start": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "page_end": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "status": {
            "type": "string",
            "enum": [
              "complete",
              "failed"
            ]
          },
          "quality": {
            "$ref": "#/components/schemas/Quality"
          }
        }
      },
      "BillableUnit": {
        "title": "BillableUnit",
        "description": "One chargeable unit recorded against a Usage entry. `type` is the unit kind, `quantity` its amount (may be fractional for audio per the published rounding rule), `stage` the internal product stage that the public operation may map to. Internal retries never increase the charged quantity.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "quantity",
          "stage"
        ],
        "properties": {
          "type": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9_]*$",
            "description": "Unit kind, e.g. pages, audio_seconds. Extensible by additive values; not a closed enum."
          },
          "quantity": {
            "type": "number",
            "minimum": 0,
            "description": "Billable quantity. Fractional only where the product tariff explicitly publishes rounding (e.g. audio_seconds). No GA monetary/unit maximum is approved; any technical safety scalar is a draft candidate only."
          },
          "stage": {
            "type": "string",
            "maxLength": 64,
            "pattern": "^[a-z][a-z0-9_]*$",
            "description": "Product stage, e.g. document, transcription."
          }
        }
      },
      "Usage": {
        "title": "Usage",
        "description": "Unified prepaid usage ledger for every product. `status` is reserved | settled | released. Reserved: the full hold exists and charge_minor is null. Settled: a final gross charge is known (may be 0 for a partial/started-unit settlement) and it is the ONLY status where refund_minor may appear. Released: the hold is fully released, charge_minor is exactly 0 and there are no charged units (a hold release is not a refund). `simulation:true` never permits real money: reserved_minor and refund_minor are 0 and charge_minor is null or 0. reserved_minor is the held amount; net = charge_minor - refund_minor.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "status",
          "reserved_minor",
          "charge_minor",
          "currency",
          "pricing_version"
        ],
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "reserved",
              "settled",
              "released"
            ]
          },
          "reserved_minor": {
            "type": "integer",
            "minimum": 0
          },
          "charge_minor": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "description": "Final gross charge in integer minor units. Null only while status=reserved; 0 when released or when a settled run had no started units."
          },
          "currency": {
            "type": "string",
            "enum": [
              "RUB"
            ],
            "description": "Draft: RUB only in R1; other ISO-4217 currencies require a new authorized contract."
          },
          "pricing_version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Pinned tariff/pricing version used for this operation. Draft placeholder values are illustrative, not published tariffs."
          },
          "billable_units": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/BillableUnit"
            },
            "description": "Chronological billable units. Required for settled usage; a settled cancellation lists only started units and their stage. Released usage has no charged units (absent or empty)."
          },
          "refund_minor": {
            "type": "integer",
            "minimum": 0,
            "description": "Optional gross refund amount. Permitted only for settled usage; a hold release (released) is not a refund and must not carry this member."
          },
          "simulation": {
            "type": "boolean",
            "description": "Indicates that this usage record reflects simulated processing. Simulated usage does not create a real charge."
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "const": "reserved"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "charge_minor": {
                  "type": "null"
                },
                "refund_minor": false
              }
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "settled"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "charge_minor": {
                  "type": "integer",
                  "minimum": 0
                },
                "refund_minor": {
                  "type": "integer",
                  "minimum": 0
                },
                "billable_units": true
              },
              "required": [
                "billable_units"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "released"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "charge_minor": {
                  "const": 0
                },
                "billable_units": {
                  "type": "array",
                  "maxItems": 0
                },
                "refund_minor": false
              }
            }
          },
          {
            "if": {
              "properties": {
                "simulation": {
                  "const": true
                }
              },
              "required": [
                "simulation"
              ]
            },
            "then": {
              "properties": {
                "reserved_minor": {
                  "const": 0
                },
                "charge_minor": {
                  "enum": [
                    null,
                    0
                  ]
                },
                "refund_minor": {
                  "const": 0
                }
              }
            }
          }
        ]
      },
      "DocumentResult": {
        "title": "DocumentResult",
        "description": "Final document payload, identical for the short sync response and GET /jobs/{job_id}/result. One document in, one JSON result out: the service decides internally whether the text came from a text layer or image recognition, and the public result never exposes that distinction. Only requested features are present: `text` exists only when the `text` feature was requested and produced, `layout` only when `layout` was requested and measured. `document_info.page_count` and `languages` are unconditional measured metadata; `detected_type` is present only when `classification` was requested and measured, otherwise absent. `document_type_hint` never forces classification. Runtime mapper tests must enforce feature/output consistency; this result schema cannot compare with the separate request and makes no cross-request guarantee. Each substantive fact carries origin/evidence (medical lane); extraction never invents a verified international code. A completed product always carries settled usage; `quality.status` here is complete|partial only (a failed result is never published as completed). Type discriminates the result union. Unknown additive response fields are tolerated, but host emitters remain bound by a privacy-safe allowlist and clients must not process unknown clinical metadata.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "id",
          "job_id",
          "status",
          "created_at",
          "completed_at",
          "expires_at",
          "document_info",
          "quality",
          "pipeline_version",
          "usage"
        ],
        "properties": {
          "type": {
            "const": "document"
          },
          "id": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "job_id": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "status": {
            "const": "completed"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "completed_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "expires_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "document_info": {
            "$ref": "#/components/schemas/DocumentInfo"
          },
          "text": {
            "$ref": "#/components/schemas/Text"
          },
          "biomarkers": {
            "type": "array",
            "maxItems": 100000,
            "items": {
              "$ref": "#/components/schemas/Observation"
            }
          },
          "entities": {
            "type": "array",
            "maxItems": 100000,
            "items": {
              "$ref": "#/components/schemas/Entity"
            }
          },
          "layout": {
            "type": "array",
            "maxItems": 100000,
            "items": {
              "$ref": "#/components/schemas/LayoutPage"
            },
            "description": "Present only when `layout` was requested and actually measured."
          },
          "parts": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "$ref": "#/components/schemas/DocumentPart"
            },
            "description": "Optional per-part manifest when an oversized document was split (RFC 01). Original page ids are preserved; runtime consistency with coverage/quality is not schema-proven."
          },
          "quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "pipeline_version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "allOf": [
          {
            "properties": {
              "usage": {
                "type": "object",
                "properties": {
                  "status": {
                    "const": "settled"
                  }
                },
                "required": [
                  "status"
                ]
              },
              "quality": {
                "type": "object",
                "properties": {
                  "status": {
                    "enum": [
                      "complete",
                      "partial"
                    ]
                  }
                }
              }
            }
          }
        ]
      },
      "Job": {
        "title": "Job",
        "description": "Public durable job envelope (metadata/status only; no embedded medical payload). Execution state machine: queued -> processing -> completed | failed; queued -> cancelled; queued|processing -> cancel_requested -> cancelled | completed | failed. completed/failed/cancelled are immutable terminals. Result availability is separate from execution state: completed may be available | expired | deleted; failed/cancelled are always unavailable and expose no partial payload. Progress/ETA are advisory and nullable (never fabricated). Status/usage/time/error couplings are enforced here: active => reserved usage, no completed_at, no error; completed => settled usage, completed_at, no error; failed => released usage, terminal time, error; cancelled => released OR settled (with non-empty started units), terminal time, a safe cancellation error code. Which concrete started units may be settled is a runtime tariff/adapter decision, NOT a schema claim.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "type",
          "status",
          "created_at",
          "result_availability",
          "status_url",
          "result_url",
          "usage"
        ],
        "properties": {
          "id": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "type": {
            "type": "string",
            "enum": [
              "document",
              "transcription"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "processing",
              "cancel_requested",
              "completed",
              "failed",
              "cancelled"
            ]
          },
          "progress": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 100,
            "description": "Advisory only. Null when no honest estimate exists."
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "updated_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "completed_at": {
            "$ref": "#/components/schemas/NullableTimestamp"
          },
          "result_availability": {
            "type": "string",
            "enum": [
              "available",
              "expired",
              "deleted",
              "unavailable"
            ]
          },
          "status_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "result_url": {
            "type": "string",
            "format": "uri",
            "maxLength": 2048
          },
          "error": {
            "$ref": "#/components/schemas/JobError"
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "status": {
                  "enum": [
                    "queued",
                    "processing",
                    "cancel_requested"
                  ]
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "usage": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "reserved"
                    }
                  },
                  "required": [
                    "status"
                  ]
                },
                "result_availability": {
                  "const": "unavailable"
                },
                "completed_at": {
                  "type": "null"
                },
                "error": false
              }
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "completed"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "usage": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "settled"
                    }
                  },
                  "required": [
                    "status"
                  ]
                },
                "result_availability": {
                  "enum": [
                    "available",
                    "expired",
                    "deleted"
                  ]
                },
                "completed_at": {
                  "$ref": "#/components/schemas/Timestamp"
                },
                "error": false
              },
              "required": [
                "completed_at"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "failed"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "usage": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "const": "released"
                    }
                  },
                  "required": [
                    "status"
                  ]
                },
                "result_availability": {
                  "const": "unavailable"
                },
                "completed_at": {
                  "$ref": "#/components/schemas/Timestamp"
                },
                "error": {
                  "$ref": "#/components/schemas/JobError"
                }
              },
              "required": [
                "completed_at",
                "error"
              ]
            }
          },
          {
            "if": {
              "properties": {
                "status": {
                  "const": "cancelled"
                }
              },
              "required": [
                "status"
              ]
            },
            "then": {
              "properties": {
                "usage": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "enum": [
                        "released",
                        "settled"
                      ]
                    }
                  },
                  "required": [
                    "status"
                  ],
                  "allOf": [
                    {
                      "if": {
                        "properties": {
                          "status": {
                            "const": "settled"
                          }
                        },
                        "required": [
                          "status"
                        ]
                      },
                      "then": {
                        "required": [
                          "billable_units"
                        ],
                        "properties": {
                          "billable_units": {
                            "type": "array",
                            "minItems": 1
                          }
                        }
                      }
                    }
                  ]
                },
                "result_availability": {
                  "const": "unavailable"
                },
                "completed_at": {
                  "$ref": "#/components/schemas/Timestamp"
                },
                "error": {
                  "$ref": "#/components/schemas/JobError"
                }
              },
              "required": [
                "completed_at",
                "error"
              ]
            }
          }
        ]
      },
      "TranscriptionOptions": {
        "title": "TranscriptionOptions",
        "description": "Transcription options. Defaults match RFC v6 03 §1.1: diarize=true, timestamps_granularity=segment, role_attribution=none. Word-level timestamps have no output contract in R1, so `word` is DEFERRED from the R1 request shape (not silently allowed). `suggest` role attribution remains a valid gated request value, but the baseline must reject it with a typed error rather than fabricate roles. No profanity filtering by default.",
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "diarize": {
            "type": "boolean",
            "default": true
          },
          "timestamps_granularity": {
            "type": "string",
            "enum": [
              "segment"
            ],
            "default": "segment",
            "description": "R1 emits `segment` only. A `word` profile is deferred until a word-level output contract exists and is not part of this draft shape."
          },
          "role_attribution": {
            "type": "string",
            "enum": [
              "none",
              "suggest"
            ],
            "default": "none",
            "description": "`suggest` is a separate gated capability with uncertainty/evidence; baseline never infers identity and there is no caller role-confirmation input in R1."
          }
        }
      },
      "TranscriptionRequestFields": {
        "title": "TranscriptionRequestFields",
        "description": "Non-file fields of POST /transcriptions. Reused verbatim as the JSON `request` part of a multipart upload, so the audio and processing options can be submitted in one request. `idempotency_key` is required. `wait_seconds` requests a bounded synchronous wait; if the result is not ready by then, the response contains the accepted job.",
        "type": "object",
        "required": [
          "idempotency_key"
        ],
        "properties": {
          "idempotency_key": {
            "$ref": "#/components/schemas/IdempotencyKey"
          },
          "wait_seconds": {
            "type": "integer",
            "minimum": 0,
            "maximum": 10,
            "default": 0,
            "description": "Maximum time to wait for a completed result after the job is durably accepted. 0 returns the job immediately; 1–10 may return the result directly, otherwise the accepted job is returned."
          },
          "language": {
            "type": "string",
            "enum": [
              "ru",
              "en",
              "auto"
            ],
            "default": "auto",
            "description": "Supported modes depend on provider/profile; `auto` returns the detected language."
          },
          "options": {
            "$ref": "#/components/schemas/TranscriptionOptions"
          },
          "billing": {
            "$ref": "#/components/schemas/Billing"
          }
        }
      },
      "TranscriptionRequest": {
        "title": "TranscriptionRequest",
        "description": "JSON body of POST /transcriptions: exactly one FileSource plus shared non-file fields.",
        "type": "object",
        "allOf": [
          {
            "$ref": "#/components/schemas/TranscriptionRequestFields"
          },
          {
            "type": "object",
            "required": [
              "file"
            ],
            "properties": {
              "file": {
                "$ref": "#/components/schemas/FileSource"
              }
            }
          }
        ],
        "unevaluatedProperties": false
      },
      "MultipartTranscriptionRequest": {
        "title": "MultipartTranscriptionRequest",
        "description": "The single JSON `request` part of multipart POST /transcriptions. Same non-file fields, including `idempotency_key` and `wait_seconds`, no `file`.",
        "type": "object",
        "$ref": "#/components/schemas/TranscriptionRequestFields",
        "unevaluatedProperties": false
      },
      "TranscriptionSegment": {
        "title": "TranscriptionSegment",
        "description": "Timed text segment. Speaker id is nullable when the speaker is undetermined and is stable only within this result (never patient/doctor identity).",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "index",
          "start_seconds",
          "end_seconds",
          "text"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "index": {
            "type": "integer",
            "minimum": 0
          },
          "speaker_id": {
            "type": [
              "string",
              "null"
            ],
            "maxLength": 128
          },
          "start_seconds": {
            "type": "number",
            "minimum": 0
          },
          "end_seconds": {
            "type": "number",
            "minimum": 0
          },
          "text": {
            "type": "string",
            "maxLength": 200000
          }
        }
      },
      "SpeakerConfidence": {
        "title": "SpeakerConfidence",
        "description": "Described confidence measurement for an inferred role. A numeric score is never emitted without a `kind` and `methodology`; calibrated and raw uncalibrated scores are distinct kinds. `calibrated` requires a non-empty calibration/profile reference. This is a local public definition and does not assume any medical-lane confidence shape.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "kind",
          "methodology"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "calibrated",
              "uncalibrated_score"
            ]
          },
          "methodology": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "profile": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "description": "Calibration/profile reference required for `calibrated`."
          },
          "score": {
            "type": [
              "number",
              "null"
            ],
            "minimum": 0,
            "maximum": 1,
            "description": "Only meaningful with kind+methodology; never a bare score."
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "kind": {
                  "const": "calibrated"
                }
              },
              "required": [
                "kind"
              ]
            },
            "then": {
              "required": [
                "profile"
              ],
              "properties": {
                "profile": true
              }
            }
          }
        ]
      },
      "TranscriptionSpeaker": {
        "title": "TranscriptionSpeaker",
        "description": "Speaker entry. Role is `unknown` by default. `role_origin` records provenance: `not_assigned` (role must be `unknown`) or `inferred` (requires at least one non-empty evidence segment id and, if a score is given, a typed `confidence` object). Caller role confirmation is not an R1 input, so `client_confirmed` is not part of this draft shape. Array order is never confirmation.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "id",
          "role",
          "role_origin"
        ],
        "properties": {
          "id": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "role": {
            "type": "string",
            "maxLength": 64,
            "description": "Default `unknown`. Other values require a supported role-attribution profile."
          },
          "role_origin": {
            "type": "string",
            "enum": [
              "not_assigned",
              "inferred"
            ]
          },
          "evidence_segment_ids": {
            "type": "array",
            "maxItems": 10000,
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          "confidence": {
            "$ref": "#/components/schemas/SpeakerConfidence"
          }
        },
        "allOf": [
          {
            "if": {
              "properties": {
                "role_origin": {
                  "const": "not_assigned"
                }
              },
              "required": [
                "role_origin"
              ]
            },
            "then": {
              "properties": {
                "role": {
                  "const": "unknown"
                }
              }
            }
          },
          {
            "if": {
              "properties": {
                "role_origin": {
                  "const": "inferred"
                }
              },
              "required": [
                "role_origin"
              ]
            },
            "then": {
              "required": [
                "evidence_segment_ids"
              ],
              "properties": {
                "evidence_segment_ids": {
                  "type": "array",
                  "minItems": 1
                }
              }
            }
          }
        ]
      },
      "TranscriptionResult": {
        "title": "TranscriptionResult",
        "description": "Transcription payload, identical for the short sync response and GET /jobs/{job_id}/result. `duration_seconds` is measured from the input audio; billable rounding is tariff-defined. Unintelligible/overlap/language-switch/unsure-dosage get warnings; no score is emitted without a described method (see SpeakerConfidence). Completed product => settled usage; `quality.status` here is complete|partial only.",
        "type": "object",
        "additionalProperties": true,
        "required": [
          "type",
          "id",
          "job_id",
          "status",
          "created_at",
          "completed_at",
          "expires_at",
          "duration_seconds",
          "language",
          "text",
          "segments",
          "speakers",
          "quality",
          "pipeline_version",
          "usage"
        ],
        "properties": {
          "type": {
            "const": "transcription"
          },
          "id": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "job_id": {
            "$ref": "#/components/schemas/OpaqueId"
          },
          "status": {
            "const": "completed"
          },
          "created_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "completed_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "expires_at": {
            "$ref": "#/components/schemas/Timestamp"
          },
          "duration_seconds": {
            "type": "number",
            "minimum": 0,
            "maximum": 3600
          },
          "language": {
            "type": "string",
            "maxLength": 16,
            "description": "Detected/handled language, e.g. ru, en."
          },
          "text": {
            "type": "string",
            "maxLength": 10000000
          },
          "segments": {
            "type": "array",
            "maxItems": 100000,
            "items": {
              "$ref": "#/components/schemas/TranscriptionSegment"
            }
          },
          "speakers": {
            "type": "array",
            "maxItems": 1000,
            "items": {
              "$ref": "#/components/schemas/TranscriptionSpeaker"
            }
          },
          "quality": {
            "$ref": "#/components/schemas/Quality"
          },
          "pipeline_version": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "usage": {
            "$ref": "#/components/schemas/Usage"
          }
        },
        "allOf": [
          {
            "properties": {
              "usage": {
                "type": "object",
                "properties": {
                  "status": {
                    "const": "settled"
                  }
                },
                "required": [
                  "status"
                ]
              },
              "quality": {
                "type": "object",
                "properties": {
                  "status": {
                    "enum": [
                      "complete",
                      "partial"
                    ]
                  }
                }
              }
            }
          }
        ]
      },
      "JobResult": {
        "title": "JobResult",
        "description": "Typed result union returned by GET /jobs/{job_id}/result and by a short-wait 200 submit. `type` discriminates: document | transcription. The union uses the same schemas as the synchronous response and shares one Usage model. No partial payload is exposed for failed/cancelled jobs.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/DocumentResult"
          },
          {
            "$ref": "#/components/schemas/TranscriptionResult"
          }
        ],
        "discriminator": {
          "propertyName": "type"
        }
      }
    }
  },
  "x-lissa-contract": {
    "status": "draft",
    "release": "R1",
    "deployed": false,
    "approved": {
      "architecture": "accepted-2026-10-05",
      "wire": false,
      "limits": false,
      "tariffs": false,
      "providerRegion": false,
      "ui": false
    },
    "source": "contracts/public-api/v1/openapi.yaml (JSON syntax; valid JSON-compatible YAML 1.2)",
    "notes": "Single source of truth. JSON Schemas under schemas/ are referenced directly; no handwritten duplicate spec. Toolchain and compatibility remain draft and are not GA-approved."
  }
}