Rules

Six rules are enough to resolve each of the Scenarios to a single expansion. Rules 1 and 2 make the first two rules from the earlier working document precise: "no equivalent duplicates" and "use the highest-ranked source". Rules 3 to 6 are new: without them, at least one scenario has more than one possible result.

These are drafts. Where a scenario forces a choice, each rule takes a draft default and lists the alternatives. The prototype has every alternative as an option, so you can see what it changes. The examples use the scenarios' ranked list: 1. PIH, 2. CIEL.

Rule	What it decides	Scenarios that need it
1. Equivalency	Which concepts are equivalent, and where OCL looks	All
2. Substitution	Which of two equivalent concepts the expansion contains	All
3. Cascading from a replaced concept	Whose answers and set members a replaced concept brings	3, 4, 4b
4. Answers point to concepts in the expansion	What a question's answers are once they've been replaced	1, 2, 4b
5. The reference stays as written	Whether OCL saves the reference as written or rewrites it to the replacement	All
6. Adding a reference	What someone sees when they add a concept that has an equivalent	5

Rule 1. Equivalency

Two concepts are equivalent when an active SAME-AS mapping links them directly, and both of their sources are on the collection's ranked list.

• Either direction. The mapping can be stored in either source: PIH → CIEL or CIEL → PIH.
• Mappings, not IDs. A shared concept ID means nothing on its own. CIEL:1498 Mild ≡ PIH:1901 Mild because a mapping says so.
• Retired mappings and retired concepts don't count.
• No chains. Two concepts that are each SAME-AS the same SNOMED CT term aren't equivalent to each other.
• Looked up in the sources, not the collection. The equivalent doesn't have to be in the collection. OCL uses the repo version of each ranked source that the expansion uses: the one the ranked list names, or else the one an unversioned reference would resolve to.

Why: every scenario turns on which CIEL concepts have a PIH equivalent. In the scenarios' data, counting only mappings stored in PIH, or counting retired mappings too, changes no result:

• Each of the 37 PIH equivalents has an active SAME-AS mapping stored in PIH.
• CIEL's own SAME-AS mappings to PIH agree with PIH's.
• Among these concepts, CIEL's only retired SAME-AS mapping to PIH points to a code that has no concept in PIH.

The clauses still matter beyond the five scenarios (Data notes). They also give draft answers to two open questions: does the direction of the mapping matter, and do chains count?

Alternatives:

• Count only mappings stored in the higher-ranked source, so the source you trust more decides.
• Follow chains through a shared reference term, such as a SNOMED CT concept.

In the prototype:

• Look for equivalents in: the ranked sources, or the collection only.
• Count SAME-AS mappings stored in: either source, the higher-ranked source only, or the lower-ranked source only.
• Retired mappings and concepts: don't count, or count.

Rule 2. Substitution

Wherever an expansion would include a concept, it includes instead that concept's equivalent from the highest-ranked source that has one, provided that source ranks above the concept's own. A concept with no such equivalent stays as it is.

• It applies to every reference, whether to one concept (scenario 5) or a cascade (scenarios 1 to 4b), and at every level of a cascade.
• A concept and its replacement count as one concept. The expansion contains it once, never both: no equivalent duplicates.
• One expansion can mix sources. In scenario 2, CIEL:162821 Mild to moderate and CIEL:162822 Moderate to severe stay CIEL concepts beside four PIH answers.

Why: this rule merges the earlier document's two rules. Together with Rules 1 and 4, it fully resolves scenarios 1 and 2, where both possible results already agree.

Open: what happens when one source has two equivalents for the same concept (a tie)? None of the scenarios has one. Draft: keep the original concept and flag it.

In the prototype:

• A concept with a higher-ranked equivalent: is replaced by it; is left out, which is what omitIfExistsIn does today; or stays, with no equivalency at all.
• Two equivalents in one source: keep the original and flag it, or use the lowest code.

Rule 3. Cascading from a replaced concept

The cascade follows Q-AND-A and CONCEPT-SET mappings to every level.

Draft default: once a concept is replaced, its answers and set members are the replacement's own, from the replacement's source. Rule 2 then applies to each of them, and so on down.

Each concept is cascaded once, so cycles end, and an answer shared by several questions is one concept in the expansion. In scenario 4b, for example, PIH:664 Negative answers three tests.

Why: scenarios 3, 4 and 4b differ on exactly this point, and no other rule decides it. Under the default:

• Scenario 3: PIH:2545 has PIH's four answers. PIH:1067 Unknown is in, and CIEL:165267 Recently quit using tobacco is out.
• Scenario 4: PIH:7539 has PIH's set. Condition clinical status is in. Problem severity, Provisional diagnosis, Final diagnosis, Patient-reported and Quartenary are out.
• Scenario 4b: Stool test has no PIH equivalent, so it keeps CIEL's members. Under it, PIH:304 Stool microscopy has PIH's nine answers.

Reason for the default: in OpenMRS, a concept's answers and set members belong to the concept. Following the replacement keeps every concept as its own source defines it. Following the referenced concept would give PIH:2545 an answer list PIH never defined, which is in effect a concept customization nobody asked for.

Option	Scenario 3: PIH:2545's answers	Scenario 4	Trade-off
Follow the replacement (draft)	PIH's 4	PIH's set: 18 concepts	Each concept is as its own source defines it, but the result can add or drop content the user referenced
Follow the referenced concept	CIEL's 4, recoded: 3 PIH plus CIEL:165267	CIEL's set, recoded: 22 concepts	The user gets what they referenced, but questions and sets get answer lists no source defines
Union	PIH's 4 plus CIEL:165267	Both: 29 concepts	Nothing referenced is lost, but PIH:2545 still differs from PIH's definition
Step by step	As "follow the referenced concept"	CIEL's members, with PIH's answers under them: 18 concepts	The literal reading of "cascade, apply equivalency, repeat". It's listed so nobody picks it by accident

The union keeps going below the first level. Under PIH:1379 Diagnosis certainty, it adds CIEL's Provisional diagnosis, Final diagnosis and Patient-reported.

Rule 4. Answers and set members point to concepts in the expansion

A question's answers and a set's members are always concepts in the expansion. When a Q-AND-A or CONCEPT-SET mapping points to a replaced concept, the dictionary treats it as pointing to the replacement.

Why: in scenario 1, CIEL:161557 Partner HIV tested stays a CIEL concept. CIEL's Q-AND-A mappings point to CIEL:1065, CIEL:1066 and CIEL:1067, and none of those is in the expansion. Without this rule, the question would reach OpenMRS with no answers.

Under Rule 3's draft default, this rule is needed wherever a concept that wasn't replaced points to one that was:

• Scenario 1: Partner HIV tested → Yes, No, Unknown.
• Scenario 2: Problem severity → four of its six answers.
• Scenario 4b: Stool test → Stool exam and Fecal occult blood test. Also the reducing-substance and fat tests → their answers.

Under "follow the referenced concept", nearly every mapping needs it, at both ends.

Open: how OCL records this. An expansion's members are concept and mapping versions, and a mapping from CIEL:161557 to PIH:1065 isn't a version of any mapping in any source. There are two options:

• Keep CIEL's mapping and the SAME-AS mapping in the expansion, and have the export and the OpenMRS import apply the replacement.
• Generate the re-pointed mapping as part of the expansion. That would be a new kind of member.

In the prototype:

• Mappings that point to a replaced concept: point to the replacement, or stay as stored. If they stay as stored, the prototype marks the answers OpenMRS would lose.

Rule 5. The reference stays as written

OCL saves a reference as the user wrote it, and expands it as if it named the replacement. A reference to CIEL:163731 with cascade stays a reference to CIEL:163731. Its resolved resources, and the expansion, contain PIH:2545 and PIH's answers.

Why: every scenario starts from a reference to a CIEL concept, so every scenario needs this decided. Under Rule 3's draft default, all five expansions come out the same either way: a reference rewritten to PIH:2545 also gives PIH's answers. The choice makes a difference elsewhere:

• Later changes. A reference saved as written follows the ranked list and the sources. If the order changes, or PIH retires its SAME-AS mapping, the next expansion changes too. A rewritten reference stays PIH:2545.
• Every kind of reference. Only a reference that names one concept, or starts a cascade from one, can be rewritten. A reference with a filter, a search term or a whole repository has no single concept to rewrite.
• What the collection shows. The references keep what the user added, such as an IG's CIEL concepts (use case 2). The expansion shows what the dictionary contains.
• Rule 3. Rewriting a cascade's starting concept settles Rule 3 for that concept: it gets the replacement's answers and members, whichever option we choose.

Alternatives: rewrite the reference to the replacement when it's added; or ask the user each time (Rule 6).

In the prototype:

• The reference: stays as written, or is rewritten to the replacement.
• Ranked list: swap it to CIEL, then PIH, after the reference was added. That shows where the two choices for this rule differ.

Rule 6. Adding a reference to a concept that has an equivalent

Adding it is allowed, and the reference is saved as written (Rule 5). OCL tells the user which concept the dictionary will contain, for example "CIEL:1065 Yes resolves to PIH:1065 Yes".

Why: scenario 5 asks what happens when the reference is added. Telling the user makes the substitution visible without blocking them. It also keeps authoring separate from expansion, and expansion is the first milestone.

Alternatives:

• Block it, the way a source blocks a second Yes.
• Offer to use PIH:1065 instead, which rewrites the reference (Rule 5's alternative).
• Allow it without telling the user.

In the prototype:

• When someone adds it: allow it and tell them, offer the replacement, block it, or allow it silently.

How the rules resolve each scenario

Each scenario resolves to one expansion. In every scenario, the collection's reference is still to the CIEL concept (Rule 5). Only the expansion contains the PIH concepts.

Scenario	Rules used	Expansion under the draft rules
1. Partner HIV tested	1, 2, 4, 5	CIEL:161557 Partner HIV tested; PIH:1065 Yes, PIH:1066 No, PIH:1067 Unknown
2. Problem severity	1, 2, 4, 5	CIEL:162820 Problem severity; PIH:1901 Mild, CIEL:162821 Mild to moderate, PIH:1900 Moderate, CIEL:162822 Moderate to severe, PIH:1903 Severe, PIH:7059 Fatal
3. Tobacco use status	1, 2, 3, 5	PIH:2545 History of tobacco use; PIH:1090 Never, PIH:1548 In the past, PIH:1550 Currently, PIH:1067 Unknown
4. Visit diagnoses	1, 2, 3, 5	PIH:7539 Visit Diagnoses, with PIH's 6 members and their answers: 18 PIH concepts
4b. Stool test	1, 2, 3, 4, 5	CIEL:161451 Stool test, with CIEL's 6 members (2 of them replaced by PIH); PIH:304 Stool microscopy, with PIH's 9 answers
5. Adding CIEL:1065 Yes	1, 2, 5, 6	The expansion contains PIH:1065 Yes, and the user is told when they add the reference

The prototype's tests check these results against OCL's data, for the draft defaults and for "follow the referenced concept".

Not needed for these five scenarios

A full design needs rules for these too, but none of the five scenarios tests them. They're also on Open questions.

• Two or more equivalents in one source. The scenarios' data has none.
• A concept from a source not on the ranked list, reached by a cascade.
• Three or more ranked sources, such as a custom source, PIH and CIEL. Under Rule 1's no-chains clause, a custom concept and a PIH concept that both map to the same CIEL concept could both end up in the expansion.
• Keeping a lower-ranked concept on purpose, by excluding one reference from substitution.
• Exclusions: whether excluding CIEL:1065 also excludes PIH:1065.
• A replaced concept's other mappings, such as CIEL's mappings to SNOMED CT and ICD-10: whether any of them carry over to the replacement.