Background

Collections let an implementation use concepts from several sources without copying them. The hard part is equivalency: deciding which of two equivalent concepts the dictionary contains.

From cloning into a source to referencing in a collection

Many OpenMRS implementations manage their dictionary as an OCL source, and clone the concepts they need from external vocabularies such as CIEL.

Cloning already substitutes equivalents. Say the implementation's source has Local Yes SAME-AS CIEL Yes, and Local No SAME-AS CIEL No. When the implementation clones a CIEL Yes/No question, OCL gives the cloned question the answers Local Yes and Local No. The dictionary stays consistent, without both a local and a CIEL Yes.

Cloning has a cost, though: the implementation now owns the copy. The link to the original is weak, so it's hard to take up CIEL's updates, or to tell a standard CIEL concept from a local change.

The newer pattern is to manage the dictionary as a collection that references concepts from several sources, such as the implementation's own source plus CIEL.

	Cloning into a source	Referencing in a collection
Link to the original	Weak: the copy is disconnected from the original	Strong: a reference to the original concept
Customization	Manual, and can break things	Only changes that break nothing, made in the collection
Shared answers such as Yes and No	Substituted once, when the concept is cloned	Substituted the same way every time the collection is expanded

The benefits of collections:

• No unnecessary cloning.
• External vocabularies stay owned by their publishers.
• Adopting upstream updates is simpler.
• Dictionary managers spend less time keeping the dictionary tidy by hand.
• It's obvious when a concept had to be cloned because it needed a breaking change.

The problem: equivalent concepts from different sources

Add a cascading reference to a CIEL question, and the expansion brings CIEL's answers. It does so even when the collection already has the implementation's own answers, mapped SAME-AS to CIEL's. A collection with a CIEL question and a local question ends up with two Yes concepts and two No concepts.

What the implementation wants is what cloning already does: the new question uses the equivalent concepts the dictionary already has.

Why it's hard

Until now, OCL has had no deterministic rule for choosing between equivalent concepts when it resolves a collection. With SAME-AS mappings alone:

• the result could depend on the order in which OCL evaluates things;
• a concept can have several equivalents;
• nothing says which source to prefer.

The direction: a ranked list of sources

A collection names its sources in order of preference, for example: 1. the implementation's source, 2. CIEL. When two concepts are equivalent through a SAME-AS mapping, the expansion uses the one from the higher-ranked source. That makes resolution explicit and deterministic, and flexible enough for different uses.

The order is set explicitly. OCL doesn't infer it, for example from who owns a source.

Where OCL looks for equivalents

The first assumption was that OCL would look only at what the collection already contains. That fails at once. If I add a cascading CIEL reference that brings CIEL's Yes and No, OCL ignores my own source's equivalent Yes and No unless I've already added them to the collection. So OCL has to look for equivalents in the ranked sources themselves, even for concepts the collection doesn't contain yet. That's Rule 1 on the Rules page.

OCL's $cascade already has a narrow version of this: the omitIfExistsIn and equivalencyMapType parameters (OpenConceptLab/ocl_issues#1451 and OpenConceptLab/ocl_issues#1457). It checks one repo version, such as the collection, and leaves a concept out when that repo version contains it or has a SAME-AS mapping to it. It doesn't add the equivalent. The prototype's "OCL today" preset shows the result.

Milestones

1. Expansion in the API. OCL resolves equivalents using the ranked sources when it expands a collection. Building it needs concrete examples (collection, sources, references) to test and evaluate against: the Scenarios are those examples.
2. Authoring. Checking equivalency when someone adds a reference is a separate problem from expansion, and harder for collections that expand automatically. It needs its own requirements; Rule 6 is the first piece.

Questions for the community

These come from the first problem statement and are still open:

1. Should OCL collections support explicit source precedence when resolving references?
2. Is an ordered list of linked sources a reasonable mechanism?
3. Are there scenarios where automatic substitution via SAME-AS mappings would be undesirable?
4. Are there other ways to keep a multi-source dictionary internally consistent?

Other open questions are on Open questions.