rxome-generator 1.0.3 → 1.0.4-beta.2

package/JSON_INPUT_FORMAT.md

@@ -0,0 +1,380 @@
+# RxOME QR Code Generator -- JSON Input Format
+
+## Overview
+
+The RxOME QR code generator accepts a JSON object following the
+**PhenoPacket v2** standard with RxOME-specific extensions. The input
+describes a patient's clinical and genomic data, which is then
+protobuf-encoded, encrypted, and rendered as a QR code.
+
+---
+
+## Top-Level Structure
+
+```json
+{
+  "id":                   "string",
+  "comment":              "string",
+  "subject":              { ... },
+  "phenotypicFeatures":   [ ... ],
+  "compressedFeatures":   { ... },
+  "interpretations":      [ ... ],
+  "diagnosis":            { ... },
+  "metaData":             { ... },
+  "credentials":          { ... }
+}
+```
+
+All top-level fields are optional except `credentials` (required for QR
+generation but stripped before encoding).
+
+---
+
+## Field Reference
+
+### Root Fields
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string | No | Unique QR code / record identifier |
+| `comment` | string | No | Free-text remarks |
+| `subject` | object | No | Patient demographics |
+| `phenotypicFeatures` | array | No | HPO terms (detailed form) |
+| `compressedFeatures` | object | No | HPO terms (compact form, preferred) |
+| `interpretations` | array | No | Genomic findings and diagnoses |
+| `diagnosis` | object | No | Disease/condition information |
+| `metaData` | object | No | Creator info, timestamps, schema version |
+| `credentials` | object | **Yes** | API credentials (never encoded in QR) |
+
+> **Note:** Supply either `phenotypicFeatures` or `compressedFeatures`,
+> not both. If `phenotypicFeatures` is provided it is automatically
+> converted to `compressedFeatures` during preprocessing.
+
+---
+
+### `subject` -- Patient Information
+
+```json
+"subject": {
+  "id":                    "proband A",
+  "dateOfBirth":           "1994-01-01T00:00:00Z",
+  "sex":                   "FEMALE",
+  "gender":                { "id": "...", "label": "..." },
+  "alternateIds":          ["ID-2"],
+  "vitalStatus":           { ... },
+  "karyotypicSex":         "XX",
+  "taxonomy":              { "id": "NCBITaxon:9606", "label": "Homo sapiens" },
+  "timeAtLastEncounter":   { ... }
+}
+```
+
+**Sex values:** `"UNKNOWN_SEX"` / `0`, `"FEMALE"` / `1`, `"MALE"` / `2`,
+`"OTHER_SEX"` / `3`. String values are converted to numbers during
+sanitisation.
+
+---
+
+### `phenotypicFeatures` -- Detailed HPO Terms
+
+```json
+"phenotypicFeatures": [
+  {
+    "type":        { "id": "HP:0030084", "label": "Clinodactyly" },
+    "excluded":    false,
+    "severity":    { "id": "HP:0012825", "label": "Mild" },
+    "modifiers":   [],
+    "onset":       { ... },
+    "resolution":  { ... },
+    "evidence":    [],
+    "description": "..."
+  }
+]
+```
+
+Set `excluded: true` to indicate a feature is explicitly absent.
+
+---
+
+### `compressedFeatures` -- Compact HPO Terms (Preferred)
+
+```json
+"compressedFeatures": {
+  "includes": ["HP:0030084", "HP:0000555", "HP:0000486"],
+  "excludes": ["HP:0031360"]
+}
+```
+
+This is the preferred input form. It contains only the HPO IDs, separated
+into present (`includes`) and absent (`excludes`) features.
+
+---
+
+### `interpretations` -- Genomic Findings
+
+```json
+"interpretations": [
+  {
+    "id": "interpretation.id",
+    "progressStatus": "SOLVED",
+    "diagnosis": {
+      "disease": {
+        "id": "OMIM:263750",
+        "label": "Optional disease label"
+      },
+      "genomicInterpretations": [
+        {
+          "subjectOrBiosampleId": "optional.id",
+          "interpretationStatus": 0,
+          "variantInterpretation": {
+            "acmgPathogenicityClassification": "PATHOGENIC",
+            "variationDescriptor": {
+              "geneContext": {
+                "valueId": "HGNC:9884",
+                "symbol": "RB1",
+                "alternateIds": ["5925"],
+                "description": "..."
+              },
+              "expressions": [
+                { "syntax": "hgvs.c", "value": "NM_000321.2:c.958C>T" },
+                { "syntax": "iscn",   "value": "..." }
+              ],
+              "allelicState": {
+                "id": "GENO:0000135",
+                "label": "heterozygous"
+              },
+              "extensions": [
+                { "name": "test-type", "value": "Exome, short read" },
+                { "name": "cnv",       "value": "1" },
+                { "name": "meth",      "value": "1" },
+                { "name": "af",        "value": "0.5" },
+                { "name": "rl",        "value": "42" },
+                { "name": "chr",       "value": "13q14.2" },
+                { "name": "site",      "value": "..." },
+                { "name": "upd",       "value": "..." }
+              ]
+            }
+          }
+        }
+      ]
+    }
+  }
+]
+```
+
+#### Enum Values
+
+**progressStatus:**
+`"UNKNOWN_PROGRESS"` (0), `"IN_PROGRESS"` (1), `"COMPLETED"` (2),
+`"SOLVED"` (3), `"UNSOLVED"` (4)
+
+**acmgPathogenicityClassification:**
+`"NOT_PROVIDED"` (0), `"BENIGN"` (1), `"LIKELY_BENIGN"` (2),
+`"UNCERTAIN_SIGNIFICANCE"` (3), `"LIKELY_PATHOGENIC"` (4),
+`"PATHOGENIC"` (5), `"RISK_ALLELE"` (999)
+
+> **Note that `RISK_ALLELE` is a RxOME specific extension of the PhenoPackage standard.**
+
+**allelicState (Zygosity, GENO ontology):**
+
+| Code | Meaning |
+|------|---------|
+| `GENO_0000137` | Unspecified zygosity |
+| `GENO_0000136` | Homozygous |
+| `GENO_0000135` | Heterozygous |
+| `GENO_0000402` | Compound heterozygous |
+| `GENO_0000134` | Hemizygous |
+| `GENO_0000604` | Hemizygous X-linked |
+| `GENO_0000605` | Hemizygous Y-linked |
+| `GENO_0000606` | Hemizygous insertion-linked |
+| `GENO_0000392` | Aneusomic zygosity |
+| `GENO_0000393` | Trisomic homozygous |
+| `GENO_0000394` | Trisomic heterozygous |
+| `GENO_0000602` | Homoplasmic |
+| `GENO_0000603` | Heteroplasmic |
+| `GENO_0000964` | Mosaic |
+
+#### RxOME Extension Fields
+
+These are carried in the `extensions` array of a `variationDescriptor`:
+
+| Name | Values | Description |
+|------|--------|-------------|
+| `test-type` | Free text (e.g. "Exome, short read", "Multigene panel") | Genetic test performed |
+| `cnv` | `0` = not provided, `1` = deletion, `2` = duplication | Copy-number variation |
+| `meth` | `0` = not provided, `1` = hyper, `2` = hypo, `3` = intermediate | Methylation status |
+| `af` | Numeric string | Allele frequency |
+| `rl` | Numeric string | Repeat length |
+| `chr` | String (e.g. "13q14.2") | Chromosomal region |
+| `site` | String | Methylation site |
+| `upd` | String | Uniparental disomy |
+
+---
+
+### `metaData`
+
+```json
+"metaData": {
+  "created":                    "2021-05-14T10:35:00Z",
+  "createdBy":                  "MGZ Munich",
+  "submittedBy":                "clinician@mgz-muenchen.de",
+  "pseudonym":                  "WDJ6GW2MMZ6A",
+  "phenopacketSchemaVersion":   "2.0",
+  "resources":                  [],
+  "externalReferences":         []
+}
+```
+
+---
+
+### `credentials` -- API Access (Never in QR Code)
+
+```json
+"credentials": {
+  "keyId":   "rxome",
+  "key":     "Rf7VbeUBQmjvAagwsWx6riaZYc7h4OBD4CuxYyZ5bgA=",
+  "keyFile": "/path/to/key",
+  "user":    "clinician@mgz-muenchen.de"
+}
+```
+
+Provide either `key` (Base64-encoded Ed25519 private key) or `keyFile`
+(path to key file), not both. This object is stripped before any data
+enters the QR code.
+
+---
+
+## Encoding Pipeline: Plain vs. Protobuf-Compressed Fields
+
+The QR code contains two distinct areas: **plain-text metadata** (the
+outer JSON envelope) and an **encrypted payload** (protobuf-encoded
+medical data). The pipeline is:
+
+```
+Input JSON
+  |
+  v
+[1] Whitelist  -- keep only recognised PhenoPacket fields; strip credentials
+  |
+  v
+[2] Sanitise   -- convert string enums to numeric (sex, progressStatus, ACMG)
+  |
+  v
+[3] HPO compress -- convert phenotypicFeatures[] to compressedFeatures{}
+  |
+  v
+[4] Protobuf encode -- encode entire medical object to binary (PhenoPacket v2 schema)
+  |
+  v
+[5] Base64
+  |
+  v
+[6] PGP encrypt (OpenPGP, Curve25519)
+  |
+  v
+[7] Assemble QR JSON envelope
+  |
+  v
+[8] Render QR code (PNG)
+```
+
+### What Ends Up in the QR Code
+
+The final QR code contains a JSON string with this structure:
+
+```json
+{
+  "createdBy":  "MGZ Munich",
+  "labid":      "rxome",
+  "keyver":     "2",
+  "apiver":     "1.0",
+  "pseudonym":  "WDJ6GW2MMZ6A",
+  "payload":    "<PGP-encrypted, Base64-encoded protobuf binary>"
+}
+```
+
+### Field Classification: Plain-Text vs. Protobuf+Encrypted
+
+| Field | Storage in QR | Explanation |
+|-------|--------------|-------------|
+| **PLAIN-TEXT (QR envelope, readable without decryption)** | |
+| `createdBy` | plain | Lab/creator name from metaData |
+| `submittedBy` | plain | Submitter email from metaData |
+| `created` | plain | Creation timestamp from metaData |
+| `labid` | plain | Lab identifier from credentials.keyId |
+| `keyver` | plain | Encryption key version (from API) |
+| `apiver` | plain | API version string |
+| `pseudonym` | plain | Patient pseudonym (from API) |
+| **PROTOBUF-ENCODED + ENCRYPTED (inside `payload`)** | |
+| `id` | protobuf + encrypted | Record identifier |
+| `comment` | protobuf + encrypted | Free-text remarks |
+| `subject` | protobuf + encrypted | All patient demographics (DOB, sex, ...) |
+| `compressedFeatures` | protobuf + encrypted | HPO phenotype terms (includes + excludes) |
+| `interpretations` | protobuf + encrypted | All genomic findings, variants, diagnoses |
+| `diagnosis` | protobuf + encrypted | Disease/condition information |
+| `metaData` | protobuf + encrypted | Full metadata structure (without pseudonym) |
+| **NEVER IN QR** | |
+| `credentials` | not stored | Stripped before encoding; used only for API auth |
+
+> **Key insight:** The outer QR envelope carries only non-sensitive
+> routing metadata (who created it, pseudonym, key version). All clinical
+> and genomic data is protobuf-serialised, Base64-encoded, then
+> PGP-encrypted before being placed in the `payload` field.
+
+---
+
+## Complete Example
+
+```json
+{
+  "id": "QR-Code ID",
+  "comment": "useful remarks",
+  "subject": {
+    "id": "proband A",
+    "dateOfBirth": "1994-01-01T00:00:00Z",
+    "sex": "FEMALE"
+  },
+  "compressedFeatures": {
+    "includes": ["HP:0030084", "HP:0000555", "HP:0000486"],
+    "excludes": ["HP:0031360"]
+  },
+  "interpretations": [
+    {
+      "id": "interpretation.id",
+      "progressStatus": "SOLVED",
+      "diagnosis": {
+        "disease": { "id": "OMIM:263750" },
+        "genomicInterpretations": [
+          {
+            "variantInterpretation": {
+              "acmgPathogenicityClassification": "PATHOGENIC",
+              "variationDescriptor": {
+                "geneContext": {
+                  "valueId": "HGNC:9884",
+                  "symbol": "RB1"
+                },
+                "expressions": [
+                  { "syntax": "hgvs.c", "value": "NM_000321.2:c.958C>T" }
+                ],
+                "allelicState": { "id": "GENO:0000135" },
+                "extensions": [
+                  { "name": "test-type", "value": "Exome, short read" }
+                ]
+              }
+            }
+          }
+        ]
+      }
+    }
+  ],
+  "metaData": {
+    "created": "2021-05-14T10:35:00Z",
+    "createdBy": "MGZ Munich",
+    "submittedBy": "clinician@mgz-muenchen.de"
+  },
+  "credentials": {
+    "key": "Rf7VbeUBQmjvAagwsWx6riaZYc7h4OBD4CuxYyZ5bgA=",
+    "keyId": "rxome",
+    "user": "clinician@mgz-muenchen.de"
+  }
+}
+```