SampleToInsightJsonBridge

URS & FS — User Requirements and Functional Specification

This document describes the controlled interface and behaviour of SampleToInsightJsonBridge for Sample-to-Insight JSON Bridge.

Domain limits and critical parameters

• Verifies data-to-insight pipeline per HL7 FHIR Genomics Reporting IG, GA4GH Phenopackets, CAP/CLIA §GEN.48800 and FDA SaMD guidance: source data completeness (5 layers: pre-analytical, sequencing, variant calls, interpretation, clinical context), terminology normalization (HGVS, SNOMED CT, LOINC, INN, HGNC), reportability rules application (config loaded, rules executed, variants filtered with full traceability), knowledge base enrichment (OncoKB, ClinVar, PharmGKB, ACMG SF with failure tracking
• ⚠️ Critical: Sample-to-insight bridge is CRITICAL TRANSITION from data to decisions. Data loss during transformation = false-negative insight. Semantic distortion = false-positive or incorrect insight. Unnormalized terminology breaks EHR/CDSS interoperability. Missing transformation audit = irreproducible and uninvestigatable. FHIR compliance mandatory for modern EHR integration. KB enrichment failure must not produce unenriched insight without warning. Tool validates TRANSFORMATION PROCESS and
• 5. Audit Retention: Retain transformation audit logs ≥ clinical result retention period.

URS — User Requirements Specification

input.csv contract

SampleID,PatientID,AssayName,OutputFormat,SchemaVersion,HasPreAnalyticalData,HasSequencingMetrics,HasVariantCalls,HasInterpretationData,HasClinicalContext,MissingRequiredFields,Variants_HGVS_Compliant,Conditions_SNOMED_Coded,Observations_LOINC_Coded,Drugs_Normalized_INN,Genes_HGNC_Symbols,UnnormalizedTerms_Count,ReportabilityRules_ConfigLoaded,RulesApplied_Successfully,VariantsEvaluated_ByRules,VariantsIncluded_InInsight,VariantsExcluded_ByRules,OncoKB_Annotation_Applied,ClinVar_Annotation_Applied,PharmGKB_Annotation_Applied,ACMG_SF_Checked,Annotations_Added,Annotations_Failed,NoDataLoss_DuringTransform,NoSemanticDistortion,UnitsPreserved,RelationshipsMaintained,IntegrityViolations_Count,OutputJSON_SyntaxValid,OutputJSON_SchemaValid,FHIR_Profile_Compliant,Required_FHIR_Resources_Present,OutputSize_KB,TransformationSteps_Logged,SourceReferences_Traceable,RuleDecisions_Documented,AnnotationSources_Cited,PipelineVersion,TransformTimestamp_Utc
BRIDGE-2026-001,PAT-LUNG-042,NSCLC_CGP,FHIR_Genomics,2.1.0,true,true,true,true,true,0,true,true,true,true,true,0,true,true,45,3,42,true,true,true,true,28,0,true,true,true,true,0,true,true,true,true,85.2,true,true,true,true,v4.2.1,2026-06-09T14:30:00Z
BRIDGE-2026-002,PAT-CRC-055,CRC_Panel,FHIR_Genomics,2.1.0,true,true,true,false,true,5,true,false,true,false,true,8,true,false,32,0,0,true,false,false,false,12,7,false,false,true,false,4,false,false,false,false,42.1,true,false,false,false,v4.2.1,2026-06-09T15:10:00Z

Input validation rules

FS — Functional Specification

Example output.json

{
  "utilityId": "sampletoinsightjsonbridge",
  "utilityFolder": "SampleToInsightJsonBridge",
  "package": "LiquidBiopsy",
  "overallStatus": "PASS|WARNING|FAIL",
  "sourceFile": "input.csv",
  "processedAtUtc": "2026-06-10T00:00:00Z",
  "checks": [
    {
      "parameter": "SampleID",
      "value": "BRIDGE-2026-001",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-001"
    },
    {
      "parameter": "PatientID",
      "value": "PAT-LUNG-042",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-002"
    },
    {
      "parameter": "AssayName",
      "value": "NSCLC_CGP",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-003"
    },
    {
      "parameter": "OutputFormat",
      "value": "FHIR_Genomics",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-004"
    },
    {
      "parameter": "SchemaVersion",
      "value": "2.1.0",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-005"
    },
    {
      "parameter": "HasPreAnalyticalData",
      "value": "true",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-006"
    },
    {
      "parameter": "HasSequencingMetrics",
      "value": "true",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-007"
    },
    {
      "parameter": "HasVariantCalls",
      "value": "true",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-008"
    },
    {
      "parameter": "HasInterpretationData",
      "value": "true",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-009"
    },
    {
      "parameter": "HasClinicalContext",
      "value": "true",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-010"
    },
    {
      "parameter": "MissingRequiredFields",
      "value": "0",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-011"
    },
    {
      "parameter": "Variants_HGVS_Compliant",
      "value": "true",
      "status": "PASS|WARNING|FAIL",
      "message": "Deterministic rule-based check result",
      "ruleReference": "FS-RULE-012"
    }
  ],
  "criticalFindings": [],
  "warnings": [],
  "audit": {
    "inputHash": "sha256:<calculated at runtime>",
    "rulesVersion": "<utility executable version>",
    "documentation": "SampleToInsightJsonBridge.documentation.html"
  }
}

Traceability matrix

IQ/OQ/PQ test scenarios

QA/QC and change control

• Do not rename columns without updating validator, documentation and test set.
• Retain input.csv, output.json, executable version and checksum.
• Before production use, perform IQ/OQ/PQ or equivalent CSV/CSA verification.
• Critical limits shall be verified against the approved specification, registration dossier and local SOPs.
• The utility provides structured QC decision support; final release decision remains with QA/QP and approved procedures.