SNOMEDkit

A toolkit for easy access and integration of SNOMED CT in healthcare applications. SNOMEDkit provides dual implementations in Swift 6.2 and Java 17+, enabling SNOMED CT terminology services across Apple platforms, Linux, and any JVM-based environment.

Overview

SNOMEDkit makes it straightforward to work with SNOMED CT terminology — from parsing RF2 release files to performing concept lookups, hierarchy navigation, and Expression Constraint Language (ECL) queries. The framework supports country extensions with a focus on the India Extension (NRCeS) and the India Drug Extension (CDCI), along with multi-language descriptions including right-to-left (RTL) script support.

• Swift 6.2: Strict concurrency with Sendable types, Core Data persistence, Apple framework integration (HealthKit), DICOMKit interoperability, and Linux compatibility.
• Java 17+: Cross-platform support via JDBC and Spring Boot, with Apache Lucene-powered full-text search.
• Shared API Design: Consistent terminology service interfaces across both language implementations.

---

Key Features

• RF2 Release File Parser — Streaming parser for SNOMED CT RF2 distribution files. Supports Full, Snapshot, and Delta release types with memory-efficient processing.
• Terminology Services — Concept lookup by SCTID, hierarchy navigation (ancestors, descendants, siblings), description search, and relationship traversal.
• Expression Constraint Language (ECL) — Parse and evaluate ECL expressions for flexible concept set retrieval.
• Country Extension Framework — Pluggable architecture for loading and querying national extensions, with built-in support for the India Extension (NRCeS).
• India Drug Extension (CDCI) — Integration with the Central Drugs Coordination of India drug terminology, National List of Essential Medicines (NLEM), and government drug program mappings.
• Multi-Language & RTL Support — Multi-language descriptions with support for Hindi, Arabic, Hebrew, and other RTL scripts.
• Swift: Core Data & Apple Integration — Core Data–backed persistence, HealthKit bridging for clinical coding, and DICOMKit integration for DICOM SR coded entries.
• Swift: Linux Compatible — Full functionality on Linux for server-side Swift deployments.
• Java: Spring Boot & Lucene — JDBC persistence, Spring Boot auto-configuration, and Apache Lucene full-text search for high-performance terminology queries.
• Shared API Design — Consistent service protocols and data models across Swift and Java, making it easy to work in mixed-platform environments.

---

Installation

Swift Package Manager

Add SNOMEDkit to your Package.swift:

dependencies: [
    .package(url: "https://github.com/Raster-Lab/SNOMEDkit.git", from: "0.1.0")
]

Then add the dependency to your target:

targets: [
    .target(
        name: "YourTarget",
        dependencies: [
            .product(name: "SNOMEDkit", package: "SNOMEDkit"),
        ]
    )
]

Maven (Java)

Add SNOMEDkit to your pom.xml:

<dependency>
    <groupId>com.rasterlab</groupId>
    <artifactId>snomedkit</artifactId>
    <version>0.1.0</version>
</dependency>

---

Quick Start

Swift — Concept Lookup

import SNOMEDkit

// Load a SNOMED CT snapshot
let store = try SNOMEDStore(rf2Path: "/path/to/SnomedCT_Release/Snapshot")
let service = TerminologyService(store: store)

// Look up a concept by SCTID
let concept = try await service.concept("84114007") // Heart structure
print("Term: \(concept.preferredTerm)")             // "Heart structure"
print("FSN: \(concept.fullySpecifiedName)")          // "Heart structure (body structure)"

// Navigate the hierarchy
let ancestors = try await service.ancestors(of: "84114007")
print("Ancestors: \(ancestors.map { $0.preferredTerm })")

Swift — RF2 Import

import SNOMEDkit

// Stream-parse an RF2 release into a Core Data store
let importer = RF2Importer(releasePath: "/path/to/SnomedCT_Release/Snapshot")
try await importer.importAll(into: store) { progress in
    print("Importing: \(progress.percentComplete)%")
}

Swift — Description Search

import SNOMEDkit

// Search for concepts by description text
let results = try await service.search("myocardial infarction", limit: 10)
for result in results {
    print("\(result.conceptId): \(result.term)")
}

Java — Concept Lookup

import com.rasterlab.snomedkit.TerminologyService;
import com.rasterlab.snomedkit.model.Concept;

// Initialize the terminology service
TerminologyService service = TerminologyService.fromRF2("/path/to/SnomedCT_Release/Snapshot");

// Look up a concept by SCTID
Concept concept = service.getConcept("84114007");
System.out.println("Term: " + concept.getPreferredTerm());
System.out.println("FSN: " + concept.getFullySpecifiedName());

// Navigate the hierarchy
List<Concept> ancestors = service.getAncestors("84114007");
ancestors.forEach(c -> System.out.println(c.getPreferredTerm()));

Java — RF2 Import

import com.rasterlab.snomedkit.rf2.RF2Importer;

// Import an RF2 release into the database
RF2Importer importer = new RF2Importer("/path/to/SnomedCT_Release/Snapshot");
importer.importAll(progress -> {
    System.out.printf("Importing: %.1f%%%n", progress.getPercentComplete());
});

Java — Description Search

import com.rasterlab.snomedkit.TerminologyService;
import com.rasterlab.snomedkit.model.SearchResult;

// Search for concepts by description text
List<SearchResult> results = service.search("myocardial infarction", 10);
for (SearchResult result : results) {
    System.out.println(result.getConceptId() + ": " + result.getTerm());
}

---

Project Structure

SNOMEDkit/
├── swift/
│   ├── Sources/
│   │   └── SNOMEDkit/
│   │       ├── RF2/               # RF2 release file parser (streaming)
│   │       ├── Model/             # Concept, Description, Relationship models
│   │       ├── Services/          # Terminology services & ECL engine
│   │       ├── Extensions/        # Country extension framework
│   │       │   ├── India/         # India Extension (NRCeS)
│   │       │   └── IndiaDrug/     # India Drug Extension (CDCI / NLEM)
│   │       ├── Persistence/       # Core Data store
│   │       ├── Integration/       # HealthKit & DICOMKit bridges
│   │       └── Localization/      # Multi-language & RTL support
│   ├── Tests/
│   └── Package.swift
├── java/
│   ├── src/
│   │   ├── main/java/com/rasterlab/snomedkit/
│   │   │   ├── rf2/               # RF2 release file parser
│   │   │   ├── model/             # Concept, Description, Relationship models
│   │   │   ├── service/           # Terminology services & ECL engine
│   │   │   ├── extension/         # Country extension framework
│   │   │   ├── persistence/       # JDBC persistence layer
│   │   │   └── search/            # Lucene full-text search
│   │   └── resources/
│   ├── src/test/
│   └── pom.xml
├── milestone.md
├── LICENSE
└── README.md

---

Platform Support

Platform	Swift	Java
macOS 14+	✅	✅
iOS 17+	✅	—
visionOS 1+	✅	—
Linux	✅	✅
Windows	—	✅

---

Documentation

• milestone.md — Project roadmap, milestones, and development plan.
• Full API documentation will be available via DocC (Swift) and Javadoc (Java) in a future release.

---

DICOMKit Integration

SNOMEDkit integrates with Raster-Lab/DICOMKit to provide SNOMED CT coded entries for DICOM Structured Reports (SR). Use SNOMEDkit's terminology services to resolve and validate coded terms embedded in DICOM objects.

import SNOMEDkit
import DICOMKit

// Resolve a SNOMED CT code from a DICOM SR coded entry
let codedEntry = try dicomSR.codedEntry(at: path)
let concept = try await service.concept(codedEntry.codeValue)
print("Resolved: \(concept.preferredTerm)")

---

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/my-feature).
3. Commit your changes with clear messages.
4. Open a pull request against main.

Please ensure your code follows the existing style conventions, includes tests for new functionality, and passes all existing tests before submitting.

---

License

SNOMEDkit is released under the MIT License.

---

Related Projects

• Raster-Lab/DICOMKit — Swift DICOM framework for medical imaging.
• Raster-Lab/HL7kit — Swift HL7 v2.x, v3.x, and FHIR framework for healthcare messaging.