Clinical Vocabulary v1.4

Overview

Namespace URI:

https://ns.cascadeprotocol.org/clinical/v1#

Preferred Prefix:

clinical:

Version:

1.4

Status:

Stable

Schema File:

clinical.ttl (Turtle/RDF)

SHACL Shapes:

clinical.shapes.ttl

The Clinical Vocabulary provides a comprehensive schema for representing clinical documents and structured health records imported from EHR systems via Apple HealthKit. It supports both narrative clinical documents (progress notes, discharge summaries) and structured records (medications, allergies, lab results, conditions, immunizations, procedures, and vital signs).

All classes align with HL7 FHIR resources and use standard healthcare terminologies including LOINC, SNOMED CT, RxNorm, and ICD-10.

Document Classes

Classes for representing clinical documents and their structure.

Structured Record Classes

Classes for representing discrete clinical data elements from EHR systems.

Longitudinal Record Classes v1.2

Classes for tracking health data over time with reconciliation and episode management.

Key Data Properties

Document Metadata

Terminology Codes

Usage Example

@prefix clinical: <https://ns.cascadeprotocol.org/clinical/v1#> .
@prefix cascade: <https://ns.cascadeprotocol.org/core/v1#> .
@prefix prov: <http://www.w3.org/ns/prov#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

# Medication record example (v1.3 — full FHIR enrichment)
<#med-metformin-123> a clinical:Medication ;
    cascade:schemaVersion "1.3" ;
    cascade:dataProvenance cascade:ClinicalGenerated ;
    clinical:drugName "Metformin HCl 500 MG Oral Tablet" ;
    clinical:dosage "500 mg" ;
    clinical:route "oral" ;
    clinical:frequency "twice daily" ;
    clinical:rxNormCode "197361" ;
    clinical:status "active" ;
    clinical:prescriber "Dr. Sarah Johnson" ;
    clinical:indication "Type 2 Diabetes" ;
    clinical:courseOfTherapyType "continuous" ;
    clinical:medicationForm "Tablet" ;
    clinical:activeIngredient "Metformin hydrochloride" ;
    clinical:ingredientStrength "500 mg" ;
    clinical:asNeeded false ;
    clinical:refillsAllowed 3 ;
    clinical:supplyDurationDays 90 ;
    clinical:dispensedQuantity "90 tablets" ;
    clinical:prescriptionCategory "community" ;
    clinical:provenanceClass "healthKitFHIR" ;
    clinical:sourceFhirResourceType "MedicationRequest" ;
    clinical:clinicalIntent "prescribed" ;
    clinical:sourceEHR "Epic MyChart" ;
    prov:wasAttributedTo <https://id.cascadeprotocol.org/users/abc123> .

# Lab result example (v1.4 — full metadata)
<#lab-a1c-456> a clinical:LabResult ;
    cascade:schemaVersion "1.4" ;
    cascade:dataProvenance cascade:ClinicalGenerated ;
    clinical:testName "Hemoglobin A1c" ;
    clinical:value "6.5" ;
    clinical:unit "%" ;
    clinical:referenceRange "4.0-5.6 %" ;
    clinical:referenceRangeLow "4.0"^^xsd:decimal ;
    clinical:referenceRangeHigh "5.6"^^xsd:decimal ;
    clinical:interpretation "H" ;
    clinical:observationStatus "final" ;
    clinical:loincCode "4548-4" ;
    clinical:effectiveDate "2025-12-15T08:30:00Z"^^xsd:dateTime ;
    clinical:issuedDate "2025-12-15T14:22:00Z"^^xsd:dateTime ;
    clinical:orderingProvider "Dr. Sarah Johnson" ;
    clinical:performingLab "Quest Diagnostics" ;
    clinical:sourceRecordId "obs-a1c-20251215-001" ;
    clinical:sourceEHR "Epic MyChart" ;
    clinical:provenanceClass "healthKitFHIR" .

# Lab test series example (v1.4 — longitudinal tracking)
<#series-a1c> a clinical:LabTestSeries ;
    cascade:schemaVersion "1.4" ;
    clinical:canonicalTestName "Hemoglobin A1C" ;
    clinical:testLoincCode "4548-4" ;
    clinical:seriesCategory "diabetes" ;
    clinical:firstResultDate "2024-06-15T08:00:00Z"^^xsd:dateTime ;
    clinical:lastResultDate "2025-12-15T08:30:00Z"^^xsd:dateTime ;
    clinical:resultCount "4"^^xsd:integer ;
    clinical:latestValue "6.5" ;
    clinical:latestUnit "%" ;
    clinical:latestInterpretation "H" ;
    clinical:trendDirection "increasing" ;
    clinical:trendConfidence "high" ;
    clinical:trendReason "3-point upward trend over 18 months" ;
    clinical:hasAbnormalHistory true ;
    clinical:currentReferenceRange "4.0-5.6 %" ;
    clinical:currentReferenceRangeLow "4.0"^^xsd:decimal ;
    clinical:currentReferenceRangeHigh "5.6"^^xsd:decimal ;
    clinical:derivedFromRecord <#lab-a1c-456> .

FHIR Alignment

The Clinical Vocabulary aligns with HL7 FHIR R4 resources to ensure interoperability with healthcare systems:

SHACL Validation

The vocabulary includes SHACL shapes for data validation. Use the shapes file to validate clinical records:

• Required property constraints (e.g., medications must have drugName)
• Datatype constraints (e.g., dates must be xsd:dateTime)
• Value range constraints (e.g., severity must be mild/moderate/severe)

Download SHACL shapes for integration with your validation pipeline.

Data Provenance

All clinical records use cascade:ClinicalGenerated provenance to indicate EHR-verified data:

• Source: Apple HealthKit HKClinicalRecord API
• Origin: Patient portals (Epic MyChart, Cerner, etc.)
• Classification: Clinical-generated, EHR-verified
• Privacy: May contain PHI - encrypted storage required

Changelog

Version 1.4 (2026-01-28)

• Added 5 new lab result properties for enhanced metadata
  • orderingProvider, performingLab, observationStatus (clinical context)
  • sourceRecordId (FHIR traceability)
  • panelMembership (panel container back-reference)
• Added structured reference range properties: referenceRangeLow, referenceRangeHigh, referenceRangeText
• Added issuedDate for result issuance timestamp
• Added clinical:LabTestSeries class for longitudinal lab result tracking
  • Lab equivalent of MedicationUseEpisode — one series per LOINC code per patient
  • 20 properties for identity, trending, reference ranges, and source linkage
  • Trend inference with confidence and explainable reason
  • No gap-based splitting (unlike medication episodes)
• Extended derivedFromRecord, sourceExternalId, and hasUnresolvedConflicts domains to include LabTestSeries
• Extended sourceEHR and provenanceClass domains to include LabResult

Version 1.3 (2026-01-26)

• Added 14 medication enrichment properties from FHIR extraction pipeline
  • Tier 1 (Clinical Detail): prescriber, indication, courseOfTherapyType, asNeeded, medicationForm, activeIngredient, ingredientStrength
  • Tier 1 (Provenance): provenanceClass, sourceFhirResourceType, clinicalIntent
  • Tier 2 (Dispensing): refillsAllowed, supplyDurationDays, dispensedQuantity, prescriptionCategory
• SHACL shapes with enumerated value constraints for courseOfTherapyType, provenanceClass, sourceFhirResourceType, clinicalIntent, prescriptionCategory
• Full end-to-end FHIR extraction pipeline: JSON → MedicationSummary → MedicationRecord → TTL
• Previously-defined but unpopulated terms (ndcCode, snomedCode) now extracted from FHIR

Version 1.2 (2026-01-15)

• Added MedicationUseEpisode class for longitudinal medication tracking
  • Represents continuous periods of medication use
  • Links to source MedicationRecord(s) via derivedFromRecord
  • Includes inferred status with explainable confidence/reason
  • Supports multi-system drug coding (RxNorm, NDC, SNOMED, ATC)
• Added Supplement class for dietary supplements and OTC products
  • Explicit regulatoryStatus (dietarySupplement, otcDrug, homeopathic, herbalRemedy)
  • evidenceStrength property for clinical evidence level
  • DSLD integration for NIH supplement database
• Added ~25 new data properties for episode and supplement serialization
• Episode identity rules: gap > 90 days creates new episode
• Supplements intentionally do NOT create episodes (different regulatory status)

Version 1.1 (2026-01-01)

• Added 7 structured clinical record classes: Medication, Allergy, LabResult, Condition, Immunization, Procedure, VitalSign
• Added ~50 data properties for structured records
• Added vital sign component properties for multi-value observations (blood pressure)
• Added SHACL shapes for all structured record types
• Validated with OWL-RL reasoner (no inconsistencies)
• Validated with Apache Jena SHACL validator

Version 1.0 (2025-12-26)

• Initial release with document-centric vocabulary
• ClinicalDocument and subtypes (ProgressNote, DischargeSummary, etc.)
• ClinicalSection for document structure
• Document metadata properties (importedAt, sourceEHR, etc.)
• Narrative content properties