A high-performance FHIRPath implementation in Rust with comprehensive spec compliance


Keywords
fhir, fhirpath, healthcare, hl7, parser
Licenses
MIT/Apache-2.0

Documentation

FHIRPath for Rust 🚀

Crates.io Documentation License: MIT OR Apache-2.0 Rust

Fast, safe, and production-ready FHIRPath implementation in Rust.

FHIRPath is the standard query language for navigating FHIR healthcare data. This library provides high-performance evaluation with 90.9% specification compliance.

✨ Quick Example

use octofhir_fhirpath::FhirPathEngine;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let engine = FhirPathEngine::with_mock_provider().await?;
    
    let patient = json!({
        "resourceType": "Patient",
        "name": [
            {"given": ["Alice"], "family": "Smith"},
            {"given": ["Dr. Alice"], "family": "Smith", "use": "professional"}
        ],
        "active": true
    });
    
    // Get all given names
    let names = engine.evaluate("Patient.name.given", patient.clone()).await?;
    println!("Names: {}", names); // ["Alice", "Dr. Alice"]
    
    // Filter by use and get family name
    let professional = engine.evaluate(
        "Patient.name.where(use = 'professional').family.first()", 
        patient.clone()
    ).await?;
    println!("Professional name: {}", professional); // "Smith"
    
    Ok(())
}

🚀 Installation

As a Library

[dependencies]
octofhir-fhirpath = "0.4"
tokio = { version = "1.0", features = ["full"] }
serde_json = "1.0"

As a CLI Tool

cargo install octofhir-fhirpath

📖 Getting Started

Basic Library Usage

use octofhir_fhirpath::FhirPathEngine;
use serde_json::json;

// Create engine (use MockModelProvider for simple cases)
let engine = FhirPathEngine::with_mock_provider().await?;

// Your FHIR data
let patient = json!({"resourceType": "Patient", "active": true});

// Evaluate expressions
let result = engine.evaluate("Patient.active", patient).await?;
println!("Active: {}", result); // [true]

Production Usage with Full FHIR Support

use octofhir_fhirpath::{FhirPathEngine, FhirPathValue};
use octofhir_fhirpath_model::FhirSchemaModelProvider;

// Create engine with full FHIR R5 schema support
let model_provider = FhirSchemaModelProvider::r5().await?;
let engine = FhirPathEngine::with_model_provider(Box::new(model_provider)).await?;

// Now supports advanced features like type checking, resolve(), etc.
let result = engine.evaluate("Patient.active is Boolean", patient).await?;

Command Line Usage

# Evaluate expression against JSON file
octofhir-fhirpath evaluate "Patient.name.given" --input patient.json

# Interactive REPL for rapid prototyping
octofhir-fhirpath repl --input patient.json

# Enhanced output formats
octofhir-fhirpath evaluate "Patient.name" --output-format pretty --input patient.json
octofhir-fhirpath evaluate "Patient.name.given" --output-format table --input patient.json

# Pipe JSON data
echo '{"resourceType":"Patient","active":true}' | \
  octofhir-fhirpath evaluate "Patient.active"

# Use environment variables
octofhir-fhirpath evaluate "age > %minAge" \
  --input patient.json \
  --variable "minAge=18"

# Web interface and HTTP server
octofhir-fhirpath server --port 8080

See CLI.md for complete command-line reference.

🎯 Key Features

  • Fast: High-performance tokenizer, parser, and evaluator
  • Safe: 100% memory-safe Rust with zero unsafe blocks
  • Compliant: 90.9% FHIRPath specification compliance (1003/1104 tests)
  • Production Ready: Thread-safe, async-first, comprehensive error handling
  • FHIR Support: Full R4/R5 support with Bundle resolution and type checking
  • Interactive: Rich REPL with auto-completion, history, and help system
  • Developer Friendly: Multiple output formats, web interface, extensive documentation

🔧 Common Use Cases

Healthcare Data Query

// Find all active patients over 18
engine.evaluate("Bundle.entry.resource.where(resourceType='Patient' and active=true and birthDate < today()-18 'years')", bundle).await?

// Get medication names from prescriptions
engine.evaluate("Bundle.entry.resource.where(resourceType='MedicationRequest').medicationReference.resolve().code.coding.display", bundle).await?

Data Validation

// Check if patient has required fields
engine.evaluate("Patient.name.exists() and Patient.birthDate.exists()", patient).await?

// Validate phone number format
engine.evaluate("Patient.telecom.where(system='phone').value.matches('[0-9-()]+')", patient).await?

Clinical Decision Support

// Find high-risk patients
engine.evaluate("Patient.extension.where(url='http://example.org/risk-score').valueInteger > 8", patient).await?

// Calculate medication dosage
engine.evaluate("MedicationRequest.dosageInstruction.doseAndRate.doseQuantity.value * 2", medication).await?

📚 Documentation

Guide Description
CLI.md Complete command-line tool reference with REPL and server docs
API Documentation Full Rust API documentation
Examples Code examples and patterns
Specification Compliance Detailed compliance report
Architecture Guide Technical architecture and design patterns
Development Guide Contributing and development setup

⚡ Performance

Built for high-throughput healthcare applications with optimized parsing and evaluation engine designed for production workloads.

🤝 Contributing

We welcome contributions!

# Get started
git clone https://github.com/octofhir/fhirpath-rs.git
cd fhirpath-rs
just test

# See development guide
just --list

📋 Specification Compliance: 90.9%

Fully Supported (100%)

  • Path navigation and filtering
  • Collection operations (where, select, first, last, count, etc.)
  • Mathematical operations and arithmetic
  • String manipulation functions
  • Boolean logic and comparisons
  • Date/time operations
  • Type operations (is, as, ofType)

🟡 Well Supported (85%+)

  • FHIR-specific functions (resolve, extension, children)
  • Advanced filtering with environment variables
  • Lambda expressions and complex iterations
  • Aggregate functions and advanced collections

See TEST_COVERAGE.md for detailed compliance status.

🛠️ Architecture

Modern, modular Rust architecture:

  • 9 specialized crates for flexibility and maintainability
  • Async-first design for scalable healthcare applications
  • Zero-copy parsing with arena allocation for performance
  • Comprehensive error handling with helpful diagnostic messages
  • Thread-safe by design with full Send + Sync support

🔗 Resources

📞 Support & Community

📄 License

Licensed under either of Apache-2.0 or MIT at your option.


Built with ❤️ for healthcare interoperability