Guides › LIMS and data hygiene

Validating HLA allele names on import

Updated 2026-10-30 · allele examples checked against IPD-IMGT/HLA 3.66.0 on 2026-10-30

Validating an HLA allele name on import means checking it against the allele list of a named IPD-IMGT/HLA release and classifying it: current, a recognisable older or shorthand form of a current name, a deleted name with or without a successor, a reporting code that stands for a set, or a name that never existed. Each class needs a different action, and none should be "fixed" without leaving a record.

A syntax check alone is not validation. A name such as DQB1*05:03:26:99 is perfectly well formed and does not exist; a name such as A*0101 fails a colon-based regular expression and is a correct pre-2010 spelling of A*01:01.

The classes of name you will meet

All results below were checked against IPD-IMGT/HLA release 3.66.0 with the HLA-Verify engine.

The guides on deleted alleles and converting pre-2010 names cover the history behind the middle rows.

Import checks, in order

1. Record the release you validate against, and the release the laboratory reported against if known. Every verdict below is only true for a release.
2. Separate allele names from everything else. Values without an asterisk, such as serological antigens, need a different path. KIR names such as KIR3DL1*001 look like allele names but belong to a different database; mark them out of scope rather than invalid.
3. Strip the optional HLA- prefix, keeping the original string.
4. Recognise reporting codes before checking names. G and P group names, XX codes, two-field g notation and multiple allele codes are not single alleles. Classify them first, so they are not reported as unknown alleles.
5. Convert legacy spellings mechanically, then check the result. Add colons to colon-less names and change Cw to C. A mechanically converted name must still be checked against the allele list; rollover names such as A*9201 do not convert mechanically and need the name history, which gives A*02:101:01.
6. Check the result against the current allele list and the history. Exact match: current. Prefix of current names: valid at lower resolution. In the history under an HLA ID: renamed or deleted, read the reason. Nowhere: never existed.
7. Flag, do not silently fix. Store the original, the normalised form and the flags together, and route never-existed names to a person.

Why each class needs its own action

Converted names are correct data in an old format. Rejecting A*0101 would discard a valid typing. Converting it without a flag hides the fact that the stored value is a translation.

Deleted names are not errors in the source. B*07:02:06 was a real name until July 2021. Its successor is B*07:436, not B*07:02: shortening a deleted name lands on a different two-field name. A deleted name without a successor, such as A*2401, withdrawn in 1995 as a sequence error, cannot be mapped to anything and should stay unresolved.

Codes are sets. A G group such as A*02:01:01G had 554 members in release 3.66.0, including null alleles. Expanding or reducing it is release-dependent and should be explicit.

Never-existed names may be typos or fabrications. Free-text sources, including AI-written text, can contain names that parse perfectly and do not exist. P*24:02 is one: there is no HLA locus called P. These need a person, not an automatic nearest match.

What "clean" should mean

Define a batch as clean only when it contains no never-existed names, no unresolved deleted names and no group-shaped names that are not real groups. Legacy spellings and reporting codes can be allowed in a clean batch, as long as they are flagged and counted. HLA-Verify's verify endpoint uses this rule: its clean field is true only when the hallucinated, fabricated-group and deleted counts are all zero, while multiple allele codes and out-of-scope names are counted separately and do not affect it.

A useful import report has one line per input value: original string, class, normalised name, flags, release. Counts per class at the end make problems obvious. For a test text of 20 names covering the rows of the table above, the engine returned 8 valid, 5 deleted, 2 group, 3 hallucinated, 1 multiple allele code and 1 out of scope, and clean: false.

Doing it in one call

POST /v1/normalize takes a list of reported strings and returns, for each, the current name, the two-field form, the G group and the flags (deprecated_name, g_group_name, p_group_name, xx_code, lg_notation, mac_code, null_allele), with UNRESOLVABLE where no current name can be given, never a guess. POST /v1/verify does the same classification on free text, such as a report or a comment field. Both name the release in every response.

One caveat: /v1/normalize converts colon-less names mechanically, so a pre-2010 rollover name such as A*9201 comes back unresolvable there, while /v1/verify and POST /v1/translate follow the name history to A*02:101:01. For archives older than 2010, run translate as well. The Python guide shows the same checks against the release files directly.

Send allele names only, never patient identifiers.

Frequently asked questions

Is a regular expression enough to validate HLA allele names?

No. It can reject malformed strings, but fabricated names such as DQB1*05:03:26:99 are well formed, and valid pre-2010 names such as A*0101 fail a colon-based pattern. Names have to be checked against a release.

Should old HLA names be rejected on import?

No. Convert them to the current name, flag the conversion, and keep the original string. Reject only names that never existed in any release.

What should happen to a deleted HLA allele name on import?

Follow its successor if the deletion record gives one, flag the change, and keep the original. If there is no successor, leave it unresolved rather than substituting a similar name.

How should G groups and multiple allele codes be imported?

As sets, not alleles. Store a G or P group name with the release that defines it, and keep a multiple allele code as reported unless you have the code definitions to expand it.