Clinical Vocabulary v1.17

Overview

Namespace URI:

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

Preferred Prefix:

clinical:

Version:

1.17

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.

Encounter and Participation v1.16

Through v1.15 clinical:Encounter carried a class code, a status, a type, two dates, a facility and one provider name. FHIR R4 Encounter carries considerably more, and US Core marks much of it Must Support. These terms close the gap. Every one of them is an element a conformant server sends and that this vocabulary previously gave an importer no way to record.

Identity and Document Attribution v1.16

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:

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.17 (2026-08-28)

• Shapes-only release; no term added, removed or renamed. Stopped sh:node from escalating a nested sh:Warning into a sh:Violation: SHACL conformance is an empty validation result regardless of severity, so the clinical:status and clinical:documentReferenceStatus value-set warnings on clinical:ClinicalDocumentShape were rejecting the six document subtypes that reach it through sh:node. The two bindings now live on clinical:DocumentStatusShape and clinical:DocumentReferenceStatusShape, which reach all seven document classes by sh:targetClass. Strictly widening: nothing that validated under v1.16 stops validating, and six classes of previously-rejected conformant document now pass.

Version 1.16 (2026-08-27)

• Fifteen new terms (14 properties and one class), two domains dropped, one property deprecated, and the first per-class value sets on clinical:status. Everything here comes from a field-coverage measurement against real R4 exports: each term is a source element that a conformant server sends and this vocabulary had nowhere to put, so an importer dropped it. Every term cites the FHIR R4 element it mirrors by canonical URL.
• Encounter. clinical:encounterReason, clinical:admitSource, clinical:dischargeDisposition, clinical:encounterClassDisplay, clinical:encounterClassSystem, and the participation structure clinical:EncounterParticipant (class) with clinical:hasParticipant, clinical:participantName, clinical:participantRole, clinical:participantRoleCode and clinical:participantSpecialty. See Encounter and Participation.
• Identity. clinical:businessIdentifier, domain-free and repeatable, for the .identifier element every FHIR resource carries. clinical:sourceRecordId keeps its meaning and now states it: the server-assigned logical id (Resource.id). Migration: a converter that has been writing a business identifier to clinical:sourceRecordId must move it. The two predicates are not interchangeable and a reader cannot repair the confusion after the fact.
• Documents. clinical:documentReferenceStatus for DocumentReference.status, which is a different assertion from the docStatus that clinical:status carries; clinical:authenticatorName for DocumentReference.authenticator, who signed a document rather than who wrote it; and repeatable clinical:documentAuthorName for DocumentReference.author 0..*.
• A status nothing checked, on five record types. clinical:status is written onto lab results, vital signs, documents, laboratory reports and allergy records, and no shape declared it on any of them, so the per-class FHIR value sets were unenforced and validation passed in silence. Each shape now binds the value set its source resource binds, verbatim: Observation.status (8 codes) for vital signs and lab results, DiagnosticReport.status (10) for laboratory reports, AllergyIntolerance.clinicalStatus (3) for allergies, and the ten-code set for the base document shape — because clinical:LaboratoryReportShape reaches that shape through sh:node, composition-status is a strict subset of diagnostic-report-status, and the wider set is therefore the only one correct for every class beneath it. All five are sh:Warning, per the core v3.5 ratchet.
• Two domains dropped. clinical:providerName declared rdfs:domain clinical:CoverageRecord while being written on every clinical record type, and clinical:verificationStatus declared rdfs:domain clinical:Condition while FHIR carries verificationStatus on AllergyIntolerance as well. Both are dropped rather than widened to a union, following the v1.11 treatment of clinical:indicationReference: a union on a cross-class predicate makes a reasoner infer that an allergy record is a Condition. No shape ever encoded either domain, so no pod is affected.
• Deprecated: clinical:observationStatus, superseded by clinical:status. Defined in v1.4 with rdfs:domain clinical:LabResult — a class deprecated in v1.13 that no import path emits — bound by no shape and written by no converter. Retired rather than re-domained, because re-domaining it onto the class that is emitted would give an Observation-derived record two status predicates with one FHIR element behind both. Retained, not removed, on the v1.13 terms: any pod carrying it stays valid and readers must continue to accept it.
• clinical.shapes.ttl v1.16 adds the new clinical:EncounterParticipantShape, declares the new encounter facts on clinical:EncounterShape and the new document and identifier properties on clinical:ClinicalDocumentShape. None of the source-text encounter properties carries a value set: FHIR binds reasonCode and admitSource preferred and dischargeDisposition example, and an enum over an example-strength binding rejects conformant data by construction.
• Additive and strictly widening. Every graph that validated under v1.15 validates under v1.16 at the same severity, with new findings at sh:Warning only. No class or property is removed or renamed, and the one deprecation removes nothing.

Version 1.15 (2026-08-14)

• clinical:VitalSignShape's clinical:interpretation is bound to the same value set the lab shapes use, at Warning severity. Through v1.14 the sh:in was on the LAB shapes only, so the identical predicate was checked on a lab result and unchecked on a vital sign. Warning first and Violation in a later version, once the warning is observably absent from conforming output, is the ratchet core v3.5 wrote down for a value that existing data carries.
• Both interpretation value sets gain the fourteen data-absent-reason codes they did not carry, matching health v2.7 byte for byte. A C-CDA nullFlavor of NASK, ASKU and NAV are three different clinical facts and v1.14 flattened all of them to unknown.
• Added clinical:interpretationSourceCode, kept semantically identical to health:interpretationSourceCode. These are two spellings of one record, and letting them drift is how one spelling silently becomes the lenient one.
• clinical:ProcedureShape's name requirement becomes an sh:or over clinical:procedureName and the undefined health:procedureName that a C-CDA import path emits, plus the new warning-severity clinical:ProcedureNameSpellingShape. Every converted procedure previously failed the name requirement while carrying a name, on a predicate no shape targets, so the name itself was validated by nothing.
• This is a MIGRATION WINDOW, not a ratified dual spelling. clinical:procedureName is canonical: it is the only spelling any Cascade vocabulary defines, the record is typed clinical:Procedure, and the health namespace has no procedure class at all. Producers write the canonical spelling only. Both the sh:or alternative and the warning shape are removed together in a later version. A consumer querying health:procedureName must add clinical:procedureName to its query now.
• Additive and strictly widening. Every graph that validated under v1.14 validates under v1.15 at the same severity; the only new finding anywhere is the one Warning above.

Version 1.14 (2026-08-08)

• Shapes only. No class or property added, removed, renamed or deprecated. Apart from the new Encounter shape the change is strictly widening. Real-world Epic FHIR exports, and C-CDA documents through the same pipeline, were failing validation on records that are correct at source.
• New clinical:EncounterShape and clinical:EncounterTemporalShape. clinical:Encounter has been defined since v1.7 and targeted by no shape, so validating an encounter evaluated zero constraints and returned PASS. That is the more dangerous kind of gap: not a failure, an unearned pass. The new shape is deliberately minimal — cardinality, datatype, provenance, and the IRI requirement the clinical:hasEncounter edge implies. It does not constrain what kind of visit an encounter may be: encounterClass gets no enum because FHIR binds Encounter.class extensibly and servers send either the abbreviation (AMB, EMER, IMP) or a display string, and the encounterStatus enum is the FHIR R4 EncounterStatus value set verbatim at sh:Warning. Having a position in time is a Warning, not a Violation, because Encounter.period is 0..1 and a planned encounter legitimately has none.
• clinical:interpretation is bound to the HL7 v3 ObservationInterpretation code system (49 selectable codes, version 3.0.0), plus the data-absent-reason code unknown and the ten retained legacy words. Kept identical to health:interpretation, since these are two spellings of one record and letting them drift is how one spelling quietly becomes the lenient one.
• clinical:snomedCode (four shapes) and clinical:icd10Code are multi-valued, matching CodeableConcept.coding (0..*).
• clinical:cptCode accepted only five digits, which is CPT Category I. The AMA CPT code set also defines Category II (four digits + F), Category III (four digits + T) and Proprietary Laboratory Analyses (four digits + U) codes, all five characters. Pattern widened to ^[0-9]{4}[0-9FTU]$.
• Date properties carried over from a source document — clinical:encounterDate, clinical:documentDate, clinical:onsetDate, clinical:procedureDate — accept xsd:date alongside xsd:dateTime, because FHIR's dateTime primitive is explicitly partial-precision and C-CDA effectiveTime commonly states a calendar day and nothing more. Timestamps Cascade itself generates (clinical:importedAt, the derived episode dates) are unchanged.

Version 1.13 (2026-08-03)

• Deprecated four classes — clinical:LabResult, clinical:Condition, clinical:Allergy, clinical:Immunization — each with owl:deprecated true and rdfs:seeAlso pointing at its health: equivalent, which is the type every import path already emits and which health v2.5 defines and shapes. Retained, not removed: the pod export path remains their sole emitter and existing pods contain them. No emitter changed in this release.
• Documented the intended FHIR R4 value sets on clinical:status and clinical:interpretation, and recorded why two of them are deliberately left unenforced. clinical:MedicationShape has no sh:in on status and clinical:VitalSignShape has none on interpretation, while sibling shapes do. Emitted data uses discontinued for medication status and elevated for vital-sign interpretation, neither of which is in the corresponding constrained set, so adding the constraints would be breaking for existing pods rather than clarifying. The ordered fix is to move emitters onto the FHIR values first, then tighten in a release explicitly flagged as tightening.
• Added clinical:ConsultationNoteShape. clinical:ConsultationNote is one of six rdfs:subClassOf clinical:ClinicalDocument; the other five each carried an explicit sh:targetClass and this one did not. A subclass axiom does not inherit a shape, so consultation notes had been validating vacuously while every sibling document type was checked. Consequence: a consultation note missing importedAt, sourceEHR or fhirResourceId passed before and fails now.

Version 1.12 (2026-07-20)

• Added clinical:parsedIndicationReference, an rdfs:subPropertyOf clinical:indicationReference recording an indication edge the importer derived by parsing a coded or free-text reason and matching it to a condition record in the same pod, as distinct from an explicit reasonReference the source carried. Modelled as a subproperty so traversal over the superproperty returns both families. Matching is code-first with a normalised-name fallback and unambiguous-only; ambiguous and unmatched are counted, never guessed.

Version 1.11 (2026-07-16)

• Widened clinical:indicationReference by dropping its restrictive rdfs:domain clinical:Medication. FHIR carries reasonReference on Procedure, MedicationRequest, MedicationAdministration and Encounter, not only medications, and the old domain would have made a reasoner infer those Procedures are Medications. No SHACL change; existing pods unaffected.

Version 1.10 (2026-07-16)

• Added three record-to-record edges: clinical:hasEncounter (range clinical:Encounter), clinical:indicationReference (open range, since FHIR permits Condition or Observation), and clinical:linkedCondition.
• Deprecated clinical:linkedConditionIds, which packed related-condition UUIDs into one space-separated literal that no graph query can traverse. Retained for backward compatibility.
• Corrected clinical:hasLabResult's rdfs:range from clinical:LabResult to health:LabResultRecord: both importer paths type panel members health:LabResultRecord, so the declared range described a class the data never uses.

Version 1.9 (2026-06-17)

• Added cascade:AIExtracted to every cascade:dataProvenance sh:in enumeration in clinical.shapes.ttl. cascade:AIExtracted (a ClinicalGenerated subclass, declared in core v3.3) is now a permitted provenance value on all clinical record shapes, so records produced by an AI document-extraction pipeline (e.g. the Workbench) validate without error.
• Shapes-only change; no new clinical classes or properties.

Version 1.8 (2026-03-28)

• Added clinical:SocialHistoryRecord class for EHR-extracted social history observations (C-CDA Social History section, LOINC 29762-2). Distinct from health:SocialHistoryRecord (consumer-reported).
• Added 5 properties: clinical:socialHistoryCategory (10-value set), clinical:packsPerYear, clinical:substanceType, clinical:frequencyDescription, clinical:socialHistoryConsent (links to cascade:SocialHistoryConsent for 42 CFR Part 2).

Version 1.7 (2026-03-12)

• Added clinical:Encounter class (fhir:Encounter alignment) with 6 properties: encounterClass, encounterStatus, encounterType, encounterStart, encounterEnd, facilityName
• Added clinical:MedicationAdministration class (fhir:MedicationAdministration alignment) with 4 properties: administeredDate, administeredDose, administeredRoute, administrationStatus
• Added clinical:ImplantedDevice class (fhir:Device alignment) with 5 properties: deviceType, implantDate, deviceManufacturer, udiCarrier, deviceStatus
• Added clinical:ImagingStudy class (fhir:ImagingStudy alignment) with 6 properties: imagingModality, studyDescription, numberOfSeries, studyDate, dicomStudyUid
• Added 3 clinical:LaboratoryReport properties: hasLabResult, panelName, reportCategory
• Added SHACL shapes for all new classes in clinical.shapes.ttl (permissive, sh:minCount 0)

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