Clinical Vocabulary v1.6

Overview

Namespace URI:

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

Preferred Prefix:

clinical:

Version:

1.5

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

Typed Code Properties v1.6

These typed code properties were aligned to the clinical: namespace in v1.6 as part of the typed code alignment (Task A2). Previously, some Checkup summary classes used checkup:-namespaced code properties; these now uniformly use clinical: predicates per the mixed namespace pattern.

CoverageRecord Properties v1.5 Deprecated

Deprecation Notice: clinical:CoverageRecord and its properties are deprecated. Use coverage:InsurancePlan from coverage.ttl for new insurance data. These properties remain defined for backward compatibility with existing EHR import pipeline data.

Properties for representing insurance coverage data imported from EHR systems. Maps to fhir:Coverage resource.

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:

Clinical Class	FHIR Resource
clinical:Medication	MedicationStatement
clinical:Allergy	AllergyIntolerance
clinical:LabResult	Observation
clinical:Condition	Condition
clinical:Immunization	Immunization
clinical:Procedure	Procedure
clinical:VitalSign	Observation (vital-signs profile)
clinical:ClinicalDocument	DocumentReference
clinical:MedicationUseEpisode v1.2	Derived from MedicationStatement
clinical:Supplement v1.2	No direct FHIR equivalent (non-prescription)
clinical:LabTestSeries v1.4	Derived from Observation (longitudinal grouping by LOINC code)
clinical:CoverageRecord v1.5	Coverage

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.6 (2026-02-22)

• Added clinical:linkedConditionIds DatatypeProperty on clinical:Condition for linking related conditions via space-separated UUIDs (enables Health Map graph traversal)
• Typed code alignment (Task A2): clinical:loincCode on LabResult, clinical:cvxCode preferred over legacy clinical:vaccineCode on Immunization, clinical:icd10Code and clinical:snomedCode on Condition and FamilyHistoryEntry, clinical:snomedCode and clinical:rxNormCode on AllergySummary
• Annotated clinical:vaccineCode as legacy (retained for backward compatibility; use clinical:cvxCode for new serialization)
• Part of Health Map v3 Pre-Phase Track A

Version 1.5 (2026-02-10)

• Added CoverageRecord class for insurance coverage data (11 properties)
  • Maps to fhir:Coverage resource
  • Layer 2 complement to checkup:InsuranceInfo (Layer 3)
• Added 3 new Procedure properties: procedureStatus, procedureCategory, procedureSnomedCode
• Added administrationRoute property for Medication

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