Colorado BHA FHIR Implementation Guide
0.3.0-current - ci-build United States of America flag

Colorado BHA FHIR Implementation Guide, published by Colorado Behavioral Health Administration. This guide is not an authorized publication; it is the continuous build for version 0.3.0-current built by the FHIR (HL7® FHIR® Standard) CI Build. This version is based on the current content of https://github.com/CoBHA/CoBHRM-FHIR-IG/ and changes regularly. See the Directory of published versions

Validation & Testing

Page standards status: Informative

Draft for review. This page describes a practical validation and testing approach for implementations of the CoBHRM FHIR Implementation Guide.

This section describes a practical validation and testing approach for implementations of the CoBHRM FHIR Implementation Guide. The goal is to help providers, intermediaries, vendors, and BHA confirm that CoBHRM reporting data is represented consistently in FHIR before it is submitted, piloted, or used for production reporting.

Implementers SHALL be able to demonstrate the following:

  1. required CoBHRM reporting data can be represented using the profiles, questionnaires, terminology, and examples in the IG;
  2. generated FHIR resources are valid HL7 FHIR Revision 4.0.1 resources and conform to the applicable CoBHRM and dependency profiles;
  3. codes used in CoBHRM reporting are drawn from the required value sets or clearly mapped where a ConceptMap is supplied;
  4. questionnaire response reporting of admissions, discharges, diagnosis updates, substance-use reporting, Special Connections reporting, and client demographic updates can be represented in realistic test scenarios; and
  5. validation failures are reported clearly enough for a provider or vendor to correct the source data or mapping.

Validation Scope

Implementers SHALL validate CoBHRM FHIR content at five levels:

FHIR syntax and base-resource validation

Each resource SHALL be valid HL7 FHIR Revision 4.0.1 JSON or XML and SHALL conform to the base FHIR resource rules for its resource type:

  • Patient resources SHALL be valid FHIR Patient resources.
  • EpisodeOfCare resources SHALL be valid FHIR EpisodeOfCare resources.
  • Encounter resources SHALL be valid FHIR Encounter resources.
  • Condition resources SHALL be valid FHIR Condition resources.
  • Organization resources SHALL be valid FHIR Organization resources.
  • QuestionnaireResponse resources SHALL be valid FHIR QuestionnaireResponse resources.

US-Core base profiles

Where US Core profiles are used, resources SHALL validate against the applicable US Core 6.1.0 profiles.

Most CoBHRM profiles are based on US Core 6.1.0 profiles, and will be checked when testing against the CoBHRM profiles.

The US Core Observation Pregnancy Status profile, and US Core Observation Sexual Orientation profiles are used directly.

CoBHRM profile validation

The CoBHRM profiles are based on US Core 6.1.0 profiles wherever possible, and the Questionnaire are based on SDC profiles where possible. Resources that claim conformance to a CoBHRM profile SHALL validate against that profile, which will include validation of the dependency profile. See Profiles for details on the CoBHRM profiles:

Implementers SHALL validate required elements, cardinality, fixed values, required identifiers, supported references, and any profile-specific constraints.

QuestionnaireResponse

Where CoBHRM data is collected through a Questionnaire and submitted as QuestionnaireResponse, implementers SHALL validate the QuestionnaireResponse according to the applicable Questionnaire and SDC expectations. See Questionnaires for details.

Terminology validation

Coded elements SHALL use the value sets required by the IG. Implementers SHALL verify that:

  • local source-system codes are transformed into the required CoBHRM code systems or other specified standard terminologies;
  • values are selected from the applicable value set;
  • required coding systems, codes, and displays are preserved accurately;
  • ConceptMaps supplied by the IG are used consistently when mapping CoBHRM values to standard terminology such as SNOMED CT, ICD-10-CM, CPT/HCPCS, or other referenced systems.

See Terminology for details on the required code systems, value sets, and ConceptMaps.

Validation Versus Data Quality Review

This guidance distinguishes validation from data quality review.

Validation answers: "Is this resource or bundle structurally and terminologically conformant with the IG?"

Examples:

  • Is the resource valid FHIR R4?
  • Does it conform to the claimed CoBHRM profile?
  • Are required elements present?
  • Are coded values in the required value set?
  • Are references resolvable within the submitted content or by the receiving system?

Data quality review answers: "Is the underlying information accurate, complete, and suitable for BHA reporting?"

Examples:

  • Is the client's demographic information current?
  • Is the admission date clinically and administratively correct?
  • Is the discharge reason accurate?
  • Is the diagnosis appropriate for the reported episode?
  • Does the source system contain all fields required for a complete CoBHRM submission?

A resource can be technically valid but still contain inaccurate or incomplete real-world information. Implementers should not treat FHIR validation as a substitute for ordinary reporting-data quality controls. Data quality review is not part of the testing against the IG.

Minimum Test Scenarios

Each implementation should test a small set of realistic scenarios before pilot or production use. The scenarios should use semi-realistic data.

The CoBHRM service must be tested with both valid and invalid data to assure that it returns success and failure responses appropriately. When failure is returned, an OperationOutcome resource SHALL be returned that contains details about the failure. The OperationOutcome resource SHALL be used to provide feedback to the submitter about what caused the failure to enable fixing it.

Client demographic reporting

Test that a client can be represented using the BHA Client Profile and any associated QuestionnaireResponse content.

Include at least:

  • client identifier(s);
  • name;
  • date of birth;
  • address or residence information where available;
  • race and ethnicity;
  • sex at birth, gender identity, and sexual orientation where required or collected;
  • household language;
  • veteran status where applicable;
  • disability codes where applicable;
  • least data populated.

Expected result: the client resource and associated questionnaire data validate against the IG and required terminology.

Admission reporting

Test that a new reportable program admission can be represented.

Include at least:

  • client;
  • provider organization;
  • EpisodeOfCare for the reportable program;
  • admission date;
  • service identifier;
  • referral source where available;
  • admission QuestionnaireResponse;
  • related diagnosis information where applicable.

Expected result: the admission scenario validates and the EpisodeOfCare is linked to the correct client and provider organization.

Discharge reporting

Test that a discharge from a reportable program can be represented.

Include at least:

  • existing client;
  • existing EpisodeOfCare;
  • discharge date;
  • discharge type or reason;
  • discharge QuestionnaireResponse;
  • any required updates to diagnosis or substance-use information.

Expected result: the discharge scenario validates, updates the correct EpisodeOfCare, and uses the required discharge terminology.

Diagnosis reporting or update

Test that diagnosis information can be represented and updated for a reportable episode.

Include at least:

  • Condition using the BHA Episode Diagnosis Profile;
  • diagnosis code;
  • diagnosis type where required;
  • relationship to the relevant EpisodeOfCare;
  • diagnosis QuestionnaireResponse where applicable.

Expected result: the diagnosis information validates and is linked to the correct client and episode.

Substance use disorder reporting

Test that SUD-specific reporting information can be represented using the BHA Substance Use Disorder Questionnaire and related resources.

Include at least:

  • primary substance use information;
  • route of administration where applicable;
  • prior treatment information where applicable;
  • ASAM level of care where applicable;
  • related admission, encounter, diagnosis, or episode references as applicable.

Expected result: SUD questionnaire content validates and uses the required CoBHRM terminology.

Special Connections reporting, if applicable

If the implementation supports Special Connections reporting, test the relevant pregnancy/postpartum and baby-reporting scenarios.

Include at least:

  • pregnancy/postpartum risk screening QuestionnaireResponse;
  • Special Connections baby QuestionnaireResponse where applicable;
  • linkage between parent/client and baby/client resources where required by implementation workflow;
  • any pregnancy-status updates represented through the appropriate FHIR resource or questionnaire content.

Expected result: Special Connections content validates against the relevant questionnaires and profiles.

Update versus correction behavior

Test at least one update to previously reported information and at least one correction to data that was entered incorrectly.

Examples:

  • a client demographic update;
  • a corrected admission date;
  • an updated diagnosis;
  • a corrected coded field.

Expected result: the implementation can distinguish an ordinary update from a correction according to the implementation's reporting workflow, preserves enough metadata for auditability, and does not create conflicting duplicate records.

Negative Tests

Implementers should include negative tests, so as to test that the Server catches these errors. These are intentionally invalid or incomplete examples used to confirm that validation catches errors before submission or at the receiving endpoint.

Minimum negative tests include:

  1. missing required client identifier;
  2. missing required admission or discharge date;
  3. invalid code for a required value set;
  4. QuestionnaireResponse item with an answer type that does not match the Questionnaire definition;
  5. diagnosis or encounter that does not reference the relevant EpisodeOfCare when required;
  6. reference to a client, organization, or episode that cannot be resolved;
  7. resource claiming a CoBHRM profile but missing a required profile element;
  8. duplicate or conflicting identifiers for the same logical client or episode.

Negative tests SHALL produce clear validation feedback and should not be silently accepted.

Error Reporting

The server validation errors SHALL be reported in a way that allows the submitting organization to fix the source data or mapping.

When validation fails, the validating system should return or record an error response that includes:

  • severity: fatal, error, warning, or information;
  • error category or code;
  • human-readable diagnostics;
  • resource type and resource id, if available;
  • element path or Questionnaire item linkId, where applicable;
  • expected value set or profile, where applicable;
  • submitted value that caused the failure, where safe to include.

FHIR OperationOutcome is the format for machine-readable validation feedback.

Technical validation errors

Technical validation errors are errors that prevent the submitted FHIR content from conforming to the IG.

Examples:

  • invalid JSON;
  • invalid FHIR resource structure;
  • missing required element;
  • invalid code;
  • invalid or unresolved reference;
  • QuestionnaireResponse inconsistent with the Questionnaire.

Technical validation errors should be corrected before the data is accepted as conformant CoBHRM FHIR content.

Pilot Testing Expectations

Before production use, a pilot implementation should demonstrate the following:

  1. the implementation can generate valid examples for each supported reporting milestone;
  2. the examples pass FHIR validation against the CoBHRM profiles and dependency profiles;
  3. terminology bindings are applied consistently;
  4. at least one admission, discharge, diagnosis update, and client demographic update scenario has been tested end-to-end;
  5. negative tests produce expected validation failures;
  6. validation results are understandable by both technical staff and reporting/data-quality staff;
  7. implementation-specific assumptions, unsupported fields, and known gaps are documented.

A pilot does not need to test every possible behavioral-health scenario. It should focus on the reporting events and data elements that the implementation expects to support in the first release.

Each implementation should maintain a small validation package containing:

  • the IG version or commit tested;
  • validator version and terminology package versions used;
  • sample valid resources or bundles;
  • a test-scenario checklist;
  • validation output for each scenario;
  • mapping notes from local source-system fields to CoBHRM/FHIR elements;
  • a list of known limitations and open questions.

For BHA review or pilot coordination, this package is more useful than a general claim that an implementation "supports FHIR."

Suggested Conformance Statement

An implementation may describe its CoBHRM FHIR readiness using the following language:

This implementation has been tested against the Colorado BHA FHIR Implementation Guide version [version/commit]. The implementation can produce FHIR R4 resources for the supported CoBHRM reporting scenarios identified in [test plan or appendix]. These resources validate against the applicable CoBHRM profiles, required dependency profiles, and terminology bindings, except for the documented limitations listed in [known limitations].

Known Limits of This Guidance

This document does not define:

  • transport requirements;
  • authentication or authorization requirements;
  • batch format requirements;
  • production submission schedules;
  • BHA acceptance criteria outside FHIR conformance;
  • full data-quality policy;
  • certification requirements for vendors or providers.

Those items should be handled in implementation agreements, pilot protocols, reporting policy, or future versions of the IG.

Example Patient Scenarios

The IG includes per-patient examples. Implementers can use these examples to test the representation of realistic scenarios and to confirm that the profiles, questionnaires, and terminology in the IG can support the required reporting information.

All example patients are fictional. Any resemblance to real persons, living or dead, is purely coincidental.