CIEL QA checks foundation

[filiperochalopes]

Concept QA — Functional Requirements & Validation Labels

Label Definitions

The 4 labels operate as two independent axes:

• Scope axis: generic (applies to any terminology) vs ciel-specific (applies only to CIEL or OpenMRS bridge/interface terminologies)
• Evaluation axis: in-concept (validated using data within the concept itself) vs between-concept (requires comparing against other concepts in the same source)

Execution types:

• deterministic — can be evaluated by a query or rule engine; returns exact pass/fail
• llm-assisted — requires linguistic judgment or pattern recognition; best evaluated by an LLM
• external — requires lookup against an external source (e.g., SNOMED CT release, RxNORM, WHOATC)

---

FR Label Matrix

FR ID	Functional Requirement	generic	ciel-specific	in-concept	between-concept	execution
FR-01	Only one Preferred name per locale (max 1 locale_preferred=1 per concept+locale)	✅		✅		deterministic
FR-02	No duplicate names within same locale, excluding SHORT (case-sensitive)	✅		✅		deterministic
FR-03	Only one SHORT name per locale (max 1 SHORT per concept+locale)	✅		✅		deterministic
FR-04	SHORT must never be Preferred (SHORT cannot have locale_preferred=1)	✅		✅		deterministic
FR-05	Only one FULLY_SPECIFIED name per locale (max 1 FSN per concept+locale)	✅		✅		deterministic
FR-06	Every concept must have at least one FULLY_SPECIFIED name (in any locale)	✅		✅		deterministic
FR-07	concept_name_type must be within allowed set (FULLY_SPECIFIED, INDEX_TERM, SHORT, or NULL)	✅		✅		deterministic
FR-08	locale must be within the expected allowed set (schema-defined locales)	✅		✅		deterministic
FR-09	FSN uniqueness per locale (refined): FSN must not collide with other FSNs nor preferred synonyms in same locale (case-insensitive; ignore SHORT/INDEX_TERM)		✅		✅	deterministic
FR-10	Preferred synonym uniqueness across active concepts in same locale (case-insensitive)	✅			✅	deterministic
FR-11	Concept UUID must be exactly 36 characters (non-retired concepts only)	✅		✅		deterministic
FR-12	No duplicate mappings: same concept → same (source, code) pair more than once	✅		✅		deterministic
FR-13	CIEL canonical SAME-AS: exactly one SAME-AS to CIEL where code == concept_id; disallow SAME-AS to CIEL pointing to a different code		✅	✅		deterministic
FR-14	No multiple active concepts SAME-AS to the same (source, code) pair (retired concepts excepted)	✅			✅	deterministic
FR-15	No HTML entities in names or descriptions (&...; pattern not allowed)	✅		✅		deterministic
FR-16	English spelling: every word in locale=en names must be correctly spelled; flag likely typos	✅		✅		llm-assisted
FR-17	British vs. American English normalization: British spelling patterns in en names should be moved to en-GB; en must use American spelling	✅		✅		llm-assisted
FR-18	Capitalization: use sentence case for common names; preserve uppercase for initialisms, acronyms, eponyms, and microbial/plant genera	✅		✅		deterministic
FR-19	No disjunctions in preferred names: avoid and/or, /, or or as conjunctions in Question answers; split into synonyms or separate concepts if needed	✅		✅		deterministic
FR-20	Balanced parentheses: parentheses must be syntactically balanced and used only for qualifiers or units	✅		✅		llm-assisted
FR-21	UCUM unit normalization: units in numeric concept names must be valid UCUM; align name and properties.units; flag or correct invalid units	✅		✅		deterministic
FR-22	No mappings to retired/inactive SNOMED CT codes; flag and propose replacement or mark for mandatory review	✅		✅		external
FR-23	Residual ICD codes (ICD-10 ending in .8; ICD-11 ending in Y without & or /) must not use SAME-AS; suggest NARROWER-THAN or a more specific code	✅		✅		deterministic
FR-24	Drug concepts (concept_class = Drug) must have mappings to SNOMED CT, RxNORM, and WHOATC; flag any missing source (removed by @askanter)	✅		✅		deterministic
FR-25	A concept must not have more than one SAME-AS mapping to the same source	✅		✅		deterministic

---

User-Facing Error Messages

FR-01 — Only one Preferred name per locale

"This concept has more than one Preferred name in the same locale."
Each locale can have only one Preferred term. Having multiple preferred names in the same language creates ambiguity during search and display. Please keep a single Preferred name per locale and convert the others to non-preferred synonyms.

---

FR-02 — No duplicate names in same locale (excluding SHORT)

"This concept contains duplicate names in the same locale."
Two or more non-SHORT names share the exact same text within the same language (comparison is case-sensitive). Each name must be unique within a locale. Please remove or edit the duplicates so that every name entry is distinct.

---

FR-03 — Only one SHORT name per locale

"This concept has multiple SHORT names in the same locale."
Only one abbreviated (SHORT) term is allowed per language. Please keep a single SHORT name for this locale and remove or reclassify the others.

---

FR-04 — SHORT must never be Preferred

"A SHORT name is marked as Preferred, which is not allowed."
SHORT names are abbreviations and must never be designated as the preferred display name for a locale. Please remove the Preferred flag from this SHORT name and assign it to a FULLY_SPECIFIED name or a synonym instead.

---

FR-05 — Only one FULLY_SPECIFIED name per locale

"This concept has more than one Fully Specified Name (FSN) in the same locale."
Only one FSN is allowed per language. Please keep the most accurate and specific FSN, and convert any additional entries to synonyms or index terms.

---

FR-06 — At least one FULLY_SPECIFIED name required

"This concept is missing a Fully Specified Name (FSN)."
Every concept must have at least one FSN in at least one locale to be considered valid. Please add a FULLY_SPECIFIED name — preferably in English (en) — before saving this concept.

---

FR-07 — concept_name_type must be within allowed set

"This concept contains an invalid name type."
The name_type field must be one of: FULLY_SPECIFIED, INDEX_TERM, SHORT, or left blank (for synonyms). The value provided is not recognized. Please correct it to one of the accepted values.

---

FR-08 — locale must be within the expected set

"This concept contains a locale that is not supported by this validation schema."
The locale provided is not in the list of permitted languages for this dictionary. Please change the locale to a valid value from the supported set, or remove the name/description if it should not exist in this source. Contact your dictionary administrator if you need to add support for a new locale.

---

FR-09 — FSN uniqueness per locale (refined rule)

"This concept's Fully Specified Name conflicts with another concept's FSN or with a Preferred synonym in the same locale."
Comparison is case-insensitive and excludes SHORT and INDEX_TERM names. FSNs must be uniquely identifying within a locale. Please revise this FSN to be more specific, or adjust the conflicting Preferred synonym on the other concept.

---

FR-10 — Preferred synonym uniqueness across active concepts

"The same Preferred name is used by multiple active concepts in the same locale."
Preferred names must be unique across active concepts (case-insensitive match) to avoid ambiguity during search and data entry. Please revise one of the conflicting Preferred names, mark one as non-preferred, or investigate whether the two concepts represent the same clinical idea and should be merged.

---

FR-11 — UUID must be exactly 36 characters

"This concept has an invalid UUID."
For active (non-retired) concepts, the UUID must be exactly 36 characters long (standard UUID format, e.g., 550e8400-e29b-41d4-a716-446655440000). The current value is either too short or too long. Please regenerate or correct the UUID.

---

FR-12 — No duplicate mappings within a concept

"This concept contains duplicate mappings to the same external source and code."
Each (source, code) combination should appear only once per concept. Having the same mapping more than once provides no additional information and may cause import errors. Please remove the duplicate mapping entries.

---

FR-13 — CIEL canonical SAME-AS mapping

"This concept violates the CIEL canonical SAME-AS rule."
Every active CIEL concept must have exactly one SAME-AS mapping to the CIEL source, and the mapped code must match the concept's own numeric concept_id. This error means either: (a) the SAME-AS self-reference to CIEL is missing, or (b) it exists but points to a different concept ID. Please add or correct the CIEL SAME-AS mapping accordingly.

---

FR-14 — No multiple active concepts SAME-AS to the same external code

"More than one active concept is mapped as SAME-AS to the same external source and code."
A SAME-AS mapping represents a unique equivalence relationship and must not be shared across active concepts. This conflict can cause cloning ambiguity during imports and exports. Please resolve by changing one mapping to NARROWER-THAN or BROADER-THAN, merging the duplicate concepts, or retiring the concept that should no longer be active.

---

FR-15 — No HTML entities in names or descriptions

"This concept contains HTML-encoded entities in a name or description."
Text fields must store plain Unicode characters, not HTML escape sequences. Patterns like &,  , <, or ' are not valid in this context. Please decode each entity and replace it with the actual character it represents (e.g., replace & with &, < with <).

---

FR-16 — English spelling review

"A possible spelling error was detected in an English name."
One or more words in a locale=en name appear to be misspelled. If the term is a known clinical or technical term, verify against a medical dictionary before changing. If the correction is clear, update the name. Do not alter legitimate technical terms, eponyms, or abbreviations.

---

FR-17 — British vs. American English normalization

"A British English spelling pattern was detected in an en (American English) name."
Names in the en locale should follow American English spelling conventions. Common British patterns include suffixes like -our, -ise, -ise, -re, -ogue, and vowel sequences like ae/oe. Please move this name to en-GB or create an en-GB variant, and normalize the en entry to American spelling.

---

FR-18 — Capitalization

"Inconsistent or incorrect capitalization detected in a name."
Preferred and Fully Specified Names should use sentence case (capitalize only the first word and proper nouns). Avoid Title Case for common clinical terms. Exceptions: initialisms (e.g., HIV, DNA), acronyms, eponyms, and microbial or plant genera should remain uppercase or capitalized as appropriate.

---

FR-19 — No disjunctions in preferred names

"The Preferred name contains a disjunction (and/or, /, or or)."
Preferred names should represent a single, unambiguous concept. Disjunctions suggest the name is covering two distinct ideas. Please split the term into separate synonyms, create distinct concepts, or rephrase the name to remove the conjunction.

---

FR-20 — Balanced parentheses

"Unbalanced or misused parentheses detected in a name."
Parentheses must always be balanced (every ( must have a matching )). They should be used only for qualifiers or units of measure. Please fix any unclosed, extra, or incorrectly placed parentheses.

---

FR-21 — UCUM unit normalization

"The unit in this numeric concept's name is missing, invalid, or inconsistent with properties.units."
For numeric concepts, units expressed in the name (e.g., mg/dL) must be valid UCUM expressions and must match the properties.units field. If the unit is absent from properties.units, add it. If there is a conflict between the name and the field, align both. Accepted non-UCUM custom units: IU, HPF, numeric, vol, volume, mass, gm, moles, beat, drop.

---

FR-22 — No retired/inactive SNOMED CT codes

"This concept is mapped to a retired or inactive SNOMED CT code."
The SNOMED CT code referenced in a mapping is no longer active in the current SNOMED CT release. Please replace it with the current active code (check the SNOMED CT browser for suggested replacements), or flag this mapping for mandatory manual review.

---

FR-23 — Residual ICD codes must not use SAME-AS

"A residual ICD code is mapped as SAME-AS, which is not appropriate."
ICD-10 codes ending in .8 ("other specified") and ICD-11 codes ending in Y (without & or /) are residual/catch-all categories and do not represent a precise equivalence. A SAME-AS mapping implies exact equivalence and should not be used here. Please change the mapping type to NARROWER-THAN or identify a more specific ICD code if one exists.

---

FR-24 — Drug concepts must have mappings to SNOMED CT, RxNORM, and WHOATC

"This Drug concept is missing one or more required external mappings."
Concepts with concept_class = Drug are expected to have mappings to SNOMED CT, RxNORM, and WHOATC to ensure interoperability. One or more of these mappings is absent. Please add the missing mapping(s). Do not invent codes — if the correct code is unknown, mark the mapping as requiring curation.

---

FR-25 — No multiple SAME-AS mappings to the same source

"This concept has more than one SAME-AS mapping to the same source."
A concept may have at most one SAME-AS mapping per source. SAME-AS indicates exact equivalence, so multiple SAME-AS mappings to different codes in the same source create ambiguity. Please keep only the correct mapping or change the others to a different mapping type (such as NARROWER-THAN or BROADER-THAN) if appropriate.

Related to:

• AI Assistant Concept QA Check #2331
• Document OpenMRS validation script checks and release workflow integration #2326

[askanter]

I think case and accented characters probably should be considered the same. Need to be sure that searching is also accent-character insensitive

[askanter]

I am not sure we need such lengthy error messages, but ok with them for now. For between concept error messages we should include the concept ID or link to the offending concept(s).

[askanter]

FR-19 is a recommendation only, not a validation rule
FR-21 is a recommendation. Units in name should be represented by units in metadata. They might be equivalent, not identical. I don't think they have to be UCUM (although that would be preferred).
FR-22 probably can't be a validation rule, but only a notification that the code is retired. They may not be replaceable at the time. Also, not sure how we are "flagging a concept for manual review"
FR-23 is a recommendation. I don't know if there will be concepts which are OTHER, etc. which should be SAME-AS to residual codes. Correct interface concepts are unlikely to be OTHER, but dictionaries might contain OTHER (specifically to capture SAME-AS codes to ICD-10, etc.)
FR-24 is not really even a recommendation, as I think drug mapping will be very heterogenous. That rule is something I use to check against, but there are lots of examples where that is not possible (either due to missing reference concepts or due to complexities in the formulation).

[filiperochalopes]

@askanter I am not sure we need such lengthy error messages

I was considering using only the error title and expanding it when clicked. If the error message is displayed during the initial form editing process (in-concept validation), I believe that specifying the concept ID in those cases would not be necessary.