Feedback on collections API specifications

I’d like to get this community’s feedback on the specifications for the collections API for OCL before Thought Works moves forward with software development. collections are how OCL allows users to create lists of a dictionary’s concepts and mappings. Collections could be used as value sets or subsets, or can simply help with logically grouping content. An important use case for collections is that users will be able to version and publish them (in the same way they can with sources) and point the OpenMRS-OCL Subscription Module to the collection version for synchronization.

Here is the full collections specification:

We also have a specific question that we’d like feedback on with respect to how best to store references to a a concept’s mappings within a collection. The question is described in detail here, along with two proposed solutions:

Please feel free to post any feedback and questions here.



That’s some pretty comprehensive documentation! :slight_smile:

I have concerns about some of the expressions promised in a future phase, and their performance implications. E.g. saying that my collection should include the HEAD of CIEL seems like it will be a performance hog, and I’d argue it’s not really a legitimate use case in include an unpublished version of someone else’s source/collection in your collection. (Including HEAD of your own org’s source/collection does make sense.)

I’m having trouble wrapping my head around the how-to-indicate-mappings question. My programmer sense leans towards the first one, as it seems like a simpler model if each expression only brings concepts or mappings, but not both.

Maybe it helps to work through a common real-world example:

KenyaEMR collection = { CIEL version 17 + Kenya EMR custom concepts }

In this case I guess they want to include all the concepts, and all the mappings. Is there some scenario where you don’t want all the mappings? Or you’d want vs not want the inverse mappings?

Thanks Jonathan for posting!

I read through the docs and I haven’t found any info about the export functionality similar to how it is done for source as described at

Is exporting implicit when creating a new version as described at ?

Could you please clarify that?

@darius - Your point about working with dynamic expressions within collections (e.g. adding HEAD of a source) is a good one and we are not actually going to implement it now. I updated the documentation to make it very clear that these are just ideas and we can has them out in the future. Some support for dynamic expressions is needed – e.g. concepts that match specified SNOMED code or any of its descendants.

Regarding the approach to mappings, for the time being we are going to stick with the simple approach of references only containing a single expression and no additional attributes. Let’s keep thinking this one through. I can definitely imagine times when someone would build a collection for a specific application and would want to filter the mappings (and the names/descriptions) that were part of the collection – this is the main use case I’m thinking about for the future.

@raff - I have added in collections to the Export API and also added the needed parameters into the collections spec. We are planning to make minor modifications to the Export API that should simplify it:

  • GET/HEAD - Return URL of export file if it exists
  • POST - Create new export file if it doesn’t exist
  • DELETE - Delete export file if it exists

However, we still want an easy way for a client to use the above to determine if an export file is currently being processed. Do you think we could just use different HTTP response codes for GET/HEAD/POST that indicate that an export file is currently being processed?


@paynejd, thanks! Using http codes sounds right.

@paynejd / @darius can one be able to subscribe to OCL from the UI? If so what is the subscription URL and/or token:


@whiscard, at this point I can just point you to this wiki page: