Semantic Rules

Semantic rules verify business, clinical, and interoperability correctness after core HL7 → FHIR conversion and postConvert(), but before FHIR delivery. Rules inspect the generated Bundle and report deterministic validation findings without modifying the Bundle.

Rule lifecycle

Rule file structure

A semantic rule file extends SemanticRulesDsl through @BaseScript. One Groovy file may declare one rule or a group of related rules.

package core

import static io.firesonic.script.api.validation.RuleSeverity.*

import org.hl7.fhir.r4.model.*

import groovy.transform.BaseScript
import io.firesonic.script.api.validation.dsl.*

@BaseScript SemanticRulesDsl dsl

rule("SEMANTIC-CORE-ENC-001") { SemanticRuleBuilder r ->

    r.severity ERROR

    // Global rule: appliesTo(...) is intentionally omitted.

    r.category "Core platform"
    r.title "Encounter identifier is required"
    r.description "Every Encounter resource must contain at least one identifier."
    r.failureMessage "Encounter does not contain an identifier"

    r.validate { SemanticRuleContext ctx, SemanticIssueCollector issues ->
        ctx.each(Encounter) { Encounter encounter ->
            if (!encounter.hasIdentifier()) {
                issues.add(r, encounter)
            }
        }
    }
}

Rule anatomy

Severity

Scopes and global rules

Use appliesTo(...) when a rule belongs to specific HL7 workflows. Scope helpers combine the HL7 message family with one or more trigger events.

rule("SEMANTIC-PAT-ADT-001") { r ->
    r.severity ERROR

    r.appliesTo(
        ADT(A01, A04, A08, A31)
    )

    ...
}

Multiple message families may be combined when the same rule applies across workflows:

r.appliesTo(
    SIU(S12, S13, S14),
    ADT(A01, A04)
)

Validation context

SemanticRuleContext provides indexed, read-only access to the generated Bundle, originating message, and FHIR resources. Prefer these helpers instead of manually traversing bundle.entry.

Real-world example: active appointment for a deceased patient

This scheduling rule demonstrates why semantic validation goes beyond structural FHIR validity. A Patient and an Appointment may each be technically valid resources, while the combination is operationally inconsistent if the patient is marked as deceased and the appointment remains active.

The rule applies only to SIU scheduling workflows that create or update appointment state. It first checks whether the Bundle contains a deceased Patient, then inspects Appointment resources and reports an ERROR for active states.

package scheduling

import groovy.transform.BaseScript

import io.firesonic.script.api.validation.dsl.*

import org.hl7.fhir.r4.model.*

import static io.firesonic.script.api.validation.RuleSeverity.*
import static io.firesonic.script.api.validation.dsl.Hl7Scopes.*
import static io.firesonic.script.api.validation.dsl.SIUEvent.*

@BaseScript SemanticRulesDsl dsl

rule("SEMANTIC-APT-001") { SemanticRuleBuilder r ->

    r.severity ERROR

    r.appliesTo(SIU(S12, S13, S14))

    r.category "Scheduling"
    r.title "Active appointment for deceased patient"
    r.description "A patient marked as deceased must not have an active appointment."
    r.failureMessage "Active appointment exists for deceased patient"

    r.validate { SemanticRuleContext ctx, SemanticIssueCollector issues ->

        boolean hasDeceasedPatient = ctx.exists(Patient) { Patient patient ->

            patient.hasDeceasedBooleanType() &&
                    patient.getDeceasedBooleanType().booleanValue()
        }

        if (!hasDeceasedPatient) {
            return
        }

        ctx.each(Appointment) { Appointment appointment ->

            if (appointment.getStatus() in [
                    Appointment.AppointmentStatus.BOOKED,
                    Appointment.AppointmentStatus.PENDING,
                    Appointment.AppointmentStatus.PROPOSED
            ]) {
                issues.add(r, appointment)
            }
        }
    }
}

Reporting validation issues

Rules report findings through SemanticIssueCollector. The rule identifier and configured severity are inherited automatically from the current rule definition.

When a resource is supplied, FireSonic records its FHIR resource type and resource ID with the semantic issue when available.

r.validate { SemanticRuleContext ctx, SemanticIssueCollector issues ->

    ctx.each(Patient) { Patient patient ->

        if (!patient.hasIdentifier()) {
            issues.add(r, patient)
        }
    }
}

Validation result and postValidation()

The platform builds a SemanticValidationResult containing all collected INFO, WARNING, and ERROR issues. It is passed to Lifecycle Hooks through postValidation(...) after semantic validation and before the final delivery/rejection decision.

@Override
void postValidation(
        MessageEnvelope envelope,
        Bundle bundle,
        SemanticValidationResult result) {

    if (result.isEmpty()) {
        return
    }

    LOG.info("Semantic validation completed: ${result.summary()}")

    result.errors().each {
        LOG.error("[${it.ruleId}] ${it.message}")
    }

    result.warnings().each {
        LOG.warn("[${it.ruleId}] ${it.message}")
    }

    result.info().each {
        LOG.info("[${it.ruleId}] ${it.message}")
    }
}

Rule hot reload Commercial

Automatic semantic-rule hot reload lets FireSonic activate validated rule changes without restarting the FireSonic runtime.

Best practices

• Keep each rule focused on one business or interoperability requirement.
• Prefer workflow-specific scopes with appliesTo(...); use global rules only for truly universal requirements.
• Use stable, descriptive rule identifiers, titles, descriptions, and failure messages.
• Keep validation deterministic: the same input Bundle should produce the same validation result.
• Prefer each(), exists(), findAll(), and count() over manual Bundle traversal.
• Report findings through issues; do not construct SemanticValidationResult manually.
• Reserve ERROR for conditions that must block delivery; use WARNING or INFO for non-blocking observations.
• Keep transformation logic in integration scripts and validation logic in semantic rule files.