# X12 naming conventions

A short glossary of the names and indices used throughout Cyclone's parsers.

## Segments

Two- or three-letter codes that identify a row type. The codes are mnemonic:
`CLM` = claim, `NM1` = name, `BPR` = beginning segment for payment
order/remittance advice, `SVC` = service, `DTM`/`DTP` = date/time/period.

## Elements

Inside a segment, elements are separated by `*` and are 1-indexed. So
`CLM01` is the first element of the `CLM` segment — the patient control
number on 837P. `CLM02` is the second element — the total claim charge.

## Composite elements

A single element can carry sub-fields, separated by `:`. The sub-fields are
also 1-indexed, suffixed to the element index:

- `CLM05-1` = place of service (Facility Type Code)
- `CLM05-2` = facility code qualifier
- `CLM05-3` = claim frequency code

In the Python code, this is `claim.place_of_service`,
`claim.facility_code_qualifier`, and `claim.frequency_code` on the
`ClaimHeader` model in `cyclone/parsers/models.py`.

## Loops

Four-digit numeric IDs, hierarchical:

- 2000A (Billing Provider hierarchy) contains
  - 2000B (Subscriber hierarchy) which contains
    - 2300 (Claim) which contains
      - 2400 (Service line)

In `cyclone.parsers`, the `parse_837` walker descends through these loops
explicitly.

## Common qualifiers Cyclone cares about

| Qualifier | Meaning | Where |
|---|---|---|
| `ABK` | ICD-10 principal diagnosis | `HI01-1` |
| `ABF` | ICD-10 diagnosis | `HI01-1` |
| `B` | Facility code qualifier (CMS POS) | `CLM05-2` |
| `MC` | Medicaid (claim filing indicator) | 835 `CLP06` |
| `PR` | Payer | 835 `N1*PR` |
| `PE` | Payee | 835 `N1*PE` |
| `G1` | Prior authorization | 837P `REF01` |
| `TJ` | Federal taxpayer ID | 837P `REF01` (rendering provider TIN) |
| `1` | Original claim | 837P `CLM05-3` |
| `7` | Replacement claim | 837P `CLM05-3` |
| `8` | Void/cancel claim | 837P `CLM05-3` |

## The four delimiters

All four are declared in the `ISA` segment (positions 103–106 in the ISA
fixed-width header) and reused throughout the file. Cyclone's tokenizer
in `cyclone/parsers/segments.py` reads the ISA first, then splits the
rest of the file by those characters.

- `*` — element separator
- `:` — component (sub-element) separator
- `~` — segment terminator
- `^` — repetition separator