hl7v2

# Conformance Profiles

Conformance profiles let you validate HL7 v2 messages against
organization-specific constraints beyond the base HL7 spec.

## What is a profile?

A profile is a set of rules that extend the base HL7 schema:

- **Required segments** — this message type MUST contain segment X
- **Forbidden segments** — this message type MUST NOT contain segment Y
- **Required fields** — beyond what the base spec requires (e.g. PID-18
  is optional in the spec but required in your integration)
- **Table bindings** — override which HL7 table a coded field must be in
- **Cardinality** — this message must have between N and M occurrences
  of segment X
- **Value constraints** — arbitrary predicates on field values
- **Custom rules** — multi-segment business logic

## Building a profile

Profiles are built via the functional `HL7v2.Profile` DSL:

```elixir
profile =
  HL7v2.Profile.new("Hospital_ADT_A01", message_type: {"ADT", "A01"})
  |> HL7v2.Profile.require_segment("NK1")
  |> HL7v2.Profile.require_field("PID", 18)
  |> HL7v2.Profile.require_cardinality("OBX", min: 1, max: 10)
  |> HL7v2.Profile.bind_table("PV1", 14, "0069")
  |> HL7v2.Profile.require_value_in("PV1", 2, ["I", "O", "E"])
```

### Declarative DSL builders (recommended)

| Builder | Purpose |
|---|---|
| `require_segment/2` | segment must appear at least once |
| `forbid_segment/2` | segment must not appear |
| `require_field/3` | field must be populated when its segment is present |
| `forbid_field/3` | field must be blank/absent when its segment is present |
| `require_value/5` | field must equal a specific value (with optional `:accessor`) |
| `require_value_in/5` | field must be in a specific allowed-value list |
| `require_component/5` | composite field must have a specific component (or subcomponent) populated — supports `:each_repetition`, `:subcomponent`, `:repetition` |
| `bind_table/4` | field value must be in a specific HL7 table (uses `HL7v2.Standard.Tables`) |
| `require_cardinality/3` | segment must appear within a `{min, max}` range |

All builders above store the constraint as **data** — no closures,
no opaque function references. That means your profiles are:

- **Introspectable**: `inspect(profile)` shows a full data tree
- **Serializable**: the profile can be round-tripped through
  JSON/YAML/etc. (minus the optional `:accessor` function)
- **Diffable**: two profiles can be compared structurally
- **Reusable**: a profile built by one module can be composed,
  extended, or loaded by another without executing code

### Custom rule escape hatches

For cases the declarative DSL can't express (custom predicates,
multi-field invariants, cross-segment rules), two escape hatches
remain:

- `add_value_constraint/4` — a 1-arity closure that receives the
  field value and returns `true`, `false`, or `{:error, reason}`.
- `add_rule/3` — a 1-arity closure that receives the whole
  typed message and returns a list of error maps.

Both still run as part of `HL7v2.Validation.ProfileRules.check/2`
and are fully integrated with the evaluation pipeline. Use them
sparingly — the declarative DSL is preferred because closures are
opaque to tooling.

### Value pinning examples

```elixir
# Simple equality pin
profile
|> HL7v2.Profile.require_value("PV1", 2, "N")

# Allowed-values list
profile
|> HL7v2.Profile.require_value_in("MSA", 1, ["AA", "AE", "AR"])

# Struct-component pin via :accessor
# (QPD-1 is a CE — validate only its identifier component)
profile
|> HL7v2.Profile.require_value("QPD", 1, "IHE PIX Query",
     accessor: & &1.identifier)
```

### Component targeting examples

```elixir
# "Every PID-3 repetition must carry CX-1 (ID Number)"
profile
|> HL7v2.Profile.require_component("PID", 3, 1,
     each_repetition: true)

# "Every PID-3 repetition must carry CX-4.1 (HD namespace_id)"
profile
|> HL7v2.Profile.require_component("PID", 3, 4,
     each_repetition: true, subcomponent: 1)
```

`require_component` currently supports the composite types
registered in `HL7v2.Profile.ComponentAccess`: CX, HD, CE, CWE.
Additional types are a one-line addition — open an issue or PR.

## Validating with a profile

Pass the profile via the `:profile` option to `HL7v2.validate/2`:

```elixir
case HL7v2.validate(msg, profile: profile) do
  :ok ->
    IO.puts("valid against profile")

  {:error, errors} ->
    for %{rule: rule, location: loc, message: msg} <- errors do
      IO.puts("[\#{rule}] \#{loc}: \#{msg}")
    end
end
```

You can also pass a list of profiles:

```elixir
HL7v2.validate(msg, profile: [profile_1, profile_2, profile_3])
```

Profiles with a specific `:message_type` only apply to matching
messages — a profile keyed to `{"ADT", "A01"}` is silently skipped
for an ORU_R01 message.

## Example profiles

The library ships with example profiles in `HL7v2.Profiles.Examples`:

- `hospital_adt_a01/0` — strict hospital ADT profile
- `ihe_lab_oru_r01/0` — IHE-style lab results profile

Copy and customize these for your use case.

## Profile error shape

Profile violations follow the standard validation error shape plus
two profile-specific keys:

```elixir
%{
  level: :error,              # or :warning
  location: "PID",            # segment ID
  field: :patient_account_number,  # field name (if applicable)
  message: "profile requires PID-18 to be populated",
  rule: :require_field,       # which rule type fired
  profile: "Hospital_ADT_A01" # which profile produced this error
}
```

This makes it easy to trace violations back to a specific profile
when multiple profiles are active.

## Custom business rules

For complex multi-segment rules, use `add_rule/3`:

```elixir
profile
|> HL7v2.Profile.add_rule(:guarantor_required_for_inpatient, fn msg ->
  has_inpatient_pv1? = ...  # your logic
  has_gt1? = ...

  if has_inpatient_pv1? and not has_gt1? do
    [%{
      level: :error,
      location: "GT1",
      field: nil,
      message: "guarantor required for inpatient visits"
    }]
  else
    []
  end
end)
```

Custom rule functions receive the full `%HL7v2.TypedMessage{}` and
return a list of error maps. Exceptions inside custom rules are
caught and treated as silent — they don't crash validation.