Scoring systems

The result.questionnaires array carries the scoring systems applied to the imagery, each modelled as a FHIR QuestionnaireResponse. Every entry records the scoring methodology, the computed score and severity band, the facet answers that fed into it, and an optional explainability media overlay.

"questionnaires": [
  {
    "resourceType": "QuestionnaireResponse",
    "questionnaire": "apasiLocal",
    "scoringSystem": {
      "text": "Local automatic psoriasis area and severity index",
      "coding": [
        { "code": "apasiLocal", "display": "Local automatic psoriasis area and severity index" }
      ]
    },
    "score": { ... },
    "explainabilityMedia": { ... },
    "item": [ ... ]
  }
]

• resourceType: Always "QuestionnaireResponse".
• questionnaire: The internal code/name of the scoring system (e.g., "apasiLocal"). A camelCase identifier; match on the exact string. Do not assume SCREAMING_SNAKE_CASE.
• scoringSystem: Contains the name (text) and coding[] array for the scoring methodology. coding[0].code is the same camelCase identifier as questionnaire.

Naming pattern:

• Local suffix: the scoring system runs on a single body-site image.
• Global suffix: the scoring system aggregates across all body sites for the same encounter.
• a-prefix (e.g. apasiLocal, ascoradLocal, aihs4Local): AI-computed variants of the parent scoring system.

The complete list of supported scoring systems for a given pathology, together with their facet questionnaires, can be fetched from a public, unauthenticated endpoint:

GET https://medical-device-params.legit.health/v2.0/questionnaires?pathology=<ICD-11 code>

Pass the ICD-11 code of the pathology of interest as the pathology query parameter (e.g. EA90 for Psoriasis). The response is an array of objects describing each scoring system applicable to that pathology, with the following fields:

• identifier: the camelCase scoring-system code emitted under questionnaire and scoringSystem.coding[0].code (e.g. apasiLocal, pure4).
• code: short identifier used internally by the severity-assessment endpoint (e.g. apasi, pure4).
• mode: "local" or "global".
• path: the severity-assessment endpoint path.
• title, description: multilingual objects keyed by locale (en_GB, es_ES, ...).
• questionnaire: an array of facet objects, each with code, name (multilingual), description (multilingual), and input (type, min/max, options). These correspond to the FHIR item[] entries emitted under each questionnaire in the diagnostic-report response.

Use this endpoint as the source of truth: the catalog of scoring systems can grow over time.

• score: The numeric outcome of the scoring system along with its severity interpretation. Note: unit ("points") and system ("http://unitsofmeasure.org") are emitted as siblings of valueQuantity inside score, not inside valueQuantity itself.
  • score.interpretation: The interpretation that applies to this particular score value (a single band).
    • score.interpretation.coding[0].code: integer severity code. One of 1 (low), 2 (moderate), 3 (high), or null.
    • score.interpretation.coding[0].display: English string label for the severity tier. One of "low", "moderate", "high".
    • score.interpretation.text: the localized BAND label, translated by the locale query parameter. Examples (English): "None", "Mild", "Moderate", "Severe", "Very severe", "Grade 1" to "Grade 9", "Stage 0" to "Stage 4", plus PROM-specific labels for DLQI, UCT, PURE4, and apulsi.
  • score.interpretations: All defined severity bands for this scoring system, in order. Each band has min (inclusive), max (exclusive), text (band label, translated) and coding[] (machine code + display: code is the integer severity 1/2/3/null; display is the English string label "low"/"moderate"/"high"). Use these to render a band scale or to map a score onto a category client-side.
• explainabilityMedia: an annotated Media resource that highlights how the score was determined. The whole object is null when no annotated explainability media is available for this scoring system run. When present:
  • resourceType: always "Media".
  • content.url: signed S3 URL. Time-limited (about 30 minutes).
  • type: always "Image" (scoring-system explainability is never a video).
  • annotations: array of detection objects, possibly empty. Each entry has id, rect.topLeft.{x,y}, rect.width, rect.height, type (a detection label string from the same fixed set used in the raw view: "Lesion", "Suspicious lesion", "Acne lesion", "Actinic keratosis lesion", "New actinic keratosis lesion", "Treatment", "acne", "wheal", "drainingTunnel", "nonDrainingTunnel", "nodule", "abscess"), and confidence (number 0 to 1 or null).
• item: An array of question-answer objects relevant to the scoring, each containing:
  • linkId: the stable, locale-independent identifier for the facet. Emitted as a JSON integer (a primary key from the backing entity). Note that the FHIR R4 standard usually types linkId as a string; this API emits an integer.
  • code[]: an array with one coding entry whose code and display both carry the TRANSLATED facet name (e.g. "Erythema" in English, "Eritema" in Spanish). Important: code[].code CHANGES with the locale query parameter; do not use it as a stable identifier in your integration logic. The stable, locale-independent identifier is item[].linkId. Switch on linkId, not on code[].code.
  • answer: The recorded response, often including a numeric level (e.g., "Moderate (2)"). answer[].valueCoding.code is the facet value as a JSON number; whole-number values serialize WITHOUT a trailing .0 (e.g. 2, not 2.0), while non-integer values serialize normally (e.g. 2.5).
• reduction: Reserved for a future "score change vs previous report" payload. Always null for anonymous reports.
• history: Reserved for a future "previous scores" payload. Always null for anonymous reports.