fhir_r5_validation 0.7.0

StructureDefinition-driven validation for FHIR R5 resources: structure, cardinality, value set bindings, and invariants.

fhir_r5_validation

A comprehensive validation library for FHIR R5 resources. This package validates FHIR resources against their StructureDefinitions, ensuring compliance with the FHIR specification.

Installation

dependencies:
  fhir_r5_validation: ^0.6.0
  fhir_r5: ^0.6.0
  fhir_r5_path: ^0.6.0

Features

• Structure Validation: Validates that resources conform to their StructureDefinition
• Cardinality Validation: Ensures required fields are present and cardinality constraints are met
• Binding Validation: Validates code bindings against ValueSets and CodeSystems
• Extension Validation: Validates extensions and their structure
• Invariant Validation: Validates FHIRPath invariants defined in StructureDefinitions
• Questionnaire Response Validation: Specialized validation for QuestionnaireResponse resources

Quick Start

import 'package:fhir_r5/fhir_r5.dart';
import 'package:fhir_r5_validation/fhir_r5_validation.dart';

void main() async {
  // Create a patient resource
  final patient = Patient(
    name: [
      HumanName(
        family: 'Doe'.toFhirString,
        given: ['John'.toFhirString],
      ),
    ],
  );

  // Create validation engine
  final validator = FhirValidationEngine();

  // Validate the resource
  final results = await validator.validateFhirResource(
    structureToValidate: patient,
  );

  // Check for errors
  if (results.hasErrors) {
    print('Validation errors found:');
    for (final error in results.results.where((r) => r.severity == Severity.error)) {
      print('  ${error.path}: ${error.diagnostics}');
    }
  } else {
    print('Resource is valid!');
  }
}

Usage

Validating Resources

The FhirValidationEngine provides three methods for validating resources:

From a FHIR Resource Object

final results = await validator.validateFhirResource(
  structureToValidate: patient,
);

From a JSON String

final jsonString = '''
{
  "resourceType": "Patient",
  "name": [{
    "family": "Doe",
    "given": ["John"]
  }]
}
''';

final results = await validator.validateFhirString(
  structureToValidate: jsonString,
);

From a JSON Map

final jsonMap = {
  'resourceType': 'Patient',
  'name': [
    {
      'family': 'Doe',
      'given': ['John']
    }
  ]
};

final results = await validator.validateFhirMap(
  structureToValidate: jsonMap,
);

Validation Results

The ValidationResults class provides detailed information about validation outcomes:

final results = await validator.validateFhirResource(
  structureToValidate: patient,
);

// Check if there are any errors
if (results.hasErrors) {
  // Handle errors
}

// Access all results
for (final result in results.results) {
  print('${result.severity}: ${result.path} - ${result.diagnostics}');
}

// Get results by severity
final errors = results.results.where((r) => r.severity == Severity.error);
final warnings = results.results.where((r) => r.severity == Severity.warning);
final info = results.results.where((r) => r.severity == Severity.information);

// Convert to JSON
final jsonResults = results.toJson();

Providing StructureDefinitions

By default, the validator will attempt to fetch StructureDefinitions automatically. However, you can provide your own:

final structureDef = StructureDefinition(
  url: 'http://hl7.org/fhir/StructureDefinition/Patient'.toFhirUri,
  // ... structure definition content
);

final results = await validator.validateFhirResource(
  structureToValidate: patient,
  structureDefinition: structureDef,
);

Custom HTTP Client

You can provide a custom HTTP client for fetching StructureDefinitions:

import 'package:http/http.dart';

final client = Client();
final results = await validator.validateFhirResource(
  structureToValidate: patient,
  client: client,
);

Validation Types

The validation engine performs several types of validation:

1. Structure Validation: Validates that the resource structure matches its StructureDefinition
2. Cardinality Validation: Ensures required fields are present and cardinality constraints are met
3. Binding Validation: Validates code bindings against ValueSets and CodeSystems
4. Extension Validation: Validates extensions and their structure
5. Invariant Validation: Validates FHIRPath invariants defined in StructureDefinitions

Questionnaire Response Validation

The package includes specialized validation for QuestionnaireResponse resources:

import 'package:fhir_r5_validation/fhir_r5_validation.dart';

// Validate a QuestionnaireResponse against its referenced Questionnaire.
// The Questionnaire is resolved through the provided ResourceCache.
final results = await validateQuestionnaireResponse(
  questionnaireResponse: questionnaireResponse,
  resourceCache: resourceCache,
);

Error Handling

The validator provides detailed error information:

try {
  final results = await validator.validateFhirResource(
    structureToValidate: patient,
  );
  
  if (results.hasErrors) {
    // Process errors
    for (final error in results.results.where((r) => r.severity == Severity.error)) {
      print('Error at ${error.path}: ${error.diagnostics}');
    }
  }
} catch (e) {
  print('Validation failed: $e');
}

Performance Considerations

• StructureDefinitions are cached automatically to avoid redundant fetching
• For batch validation, reuse the FhirValidationEngine instance
• Consider providing StructureDefinitions directly if you have them available
• Use a ResourceCache for better performance with multiple validations

Integration with Other Packages

The validation package integrates seamlessly with other FHIR-FLI packages:

• fhir_r5: Uses FHIR resource models
• fhir_r5_path: Uses the model-independent FHIRPath engine to evaluate invariants (constraints)
• fhir_r5_db: Can validate resources before saving to the database
• fhir_r5_at_rest: Can validate resources before sending to a FHIR server

Documentation

For more detailed documentation, see the FHIR-FLI documentation site.

Say Hello

• As all parts of this are new (FHIR, Flutter, using the two together), I'd love to hear from you if you're working in this space. Open to PR, suggestions or requests. You can email me at [e-mail]. Or, feel free to join our Slack!.

A Dart/Flutter package for validating FHIR® resources. FHIR® is the registered trademark of HL7 and is used with the permission of HL7. Use of the FHIR trademark does not constitute endorsement of this product by HL7.