Reference

[jamlung-ri]

References are the “instructions” to tell OCL what resources to put in your collection and how to do it. References are akin to FHIR's logical definition, sometimes known as the Compose statement of a ValueSet.

In OCL, references often point to either concepts or mappings; they can also point to something broader e.g. all concepts in a repository. You can have one reference per concept that you want in your collection, or you can have one reference that brings in multiple concepts or mappings. Additionally, any reference can either be an INCLUDE or an EXCLUDE reference, which determines whether the concept(s)/mapping(s) should be brought into the collection or if they should be specifically omitted from the collection.

References also can have "Cascade" parameters, which tell OCL to not only get a single concept, but also to traverse the associations (i.e. mappings or hierarchy) of a concept to bring in more concepts. For example, users will often add an entire Concept Set to their collection, which brings in the concept for the set, plus any question concepts within that set, plus any answer concepts underneath those questions, and so on.

References can sometimes point to a specific version of a repository, but they often simply point to one or more concepts/mappings themselves without specifying a version. In this case, version resolution happens as part of building a collection expansion. Best practices for modeling references can be found in this document: https://docs.google.com/document/d/1QvWX0H6TP1_yJSiNkE9xWIrYmn9opp6O0-qQp57m4zc/edit

User Stories:

• As a consumer, I want to search for and find reference(s) so that I can better understand why the collection is resolving in a certain way.
• As a consumer, I want to evaluate a reference on-the-fly, without needing to save the results to a collection/valueset expansion, so that I can see how OCL would resolve that reference (i.e. what concept(s)/mapping(s) would come out of it) without interference from other references in the collection.
• As a consumer, I want to view the details of a reference (e.g. all attributes in a human-readable format) so that I can understand its fully behaviors, including cascade behavior, resolution details, what filters are in use, etc. (example reference from API)
• As a consumer, I want to see where a reference is being used, including a list of repo versions that it belongs to, expansions that use it, and results of that reference in those expansions, so that I can fully grasp the outcome and effects of that reference and where else it is used within the repository's history.
• As a consumer, I want to visualize the results of a reference (as a list and as a visual map-like view) to see how the resulting concepts/mappings relate to each other so that I can better understand the full effects of that reference.

[jamlung-ri]

One note about this: our current model of reference building in the API is not entirely FHIR conformant. It may not necessarily be FHIR-illegal, but it at least doesn't go along with most of the value set building norms that FHIR would do. Several examples of this have come out of the Phase 2 Kenya SMART Guidelines project.