# Inconsistency in REST API Create EHR implementations -needs spec clarification? **Category:** [ITS](https://discourse.openehr.org/c/its/41) **Created:** 2021-01-04 15:36 UTC **Views:** 867 **Replies:** 27 **URL:** https://discourse.openehr.org/t/inconsistency-in-rest-api-create-ehr-implementations-needs-spec-clarification/1199 --- ## Post #1 by @ian.mcnicoll Hi - I am having a little trouble with the POST /ehr call across the Better and EhrBase implementations // EhrBase ``` { "_type": "EHR_STATUS", "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1", "name": "ehr status", "subject": { "external_ref": { "id": { "_type": "HIER_OBJECT_ID", "value": "{{subjectId}}" }, "namespace": "{{subjectNamespace}}", "type": "PERSON" } }, "is_modifiable": "true", "is_queryable": "true" } ``` This works but fails if the namespace contains a '.' character - this has been reported as a bug. Better CDR ``` { "_type": "EHR_STATUS", // "archetype_node_id": "openEHR-EHR-EHR_STATUS.generic.v1", // "name": "ehr status", "subject": { "external_ref": { "id": { "_type": "HIER_OBJECT_ID", "value": "{{subjectId}}" }, "namespace": "{{subjectNamespace}}", "type": "PERSON" } }, "is_modifiable": "true", "is_queryable": "true" } ``` This only works if the archetype details are removed. My understanding is that they are mandatory, although in fact the archetype described is not actually 'real'. It is not defined in any way in either CDR. Advice? --- ## Post #2 by @birger.haarbrandt We might change EHRbase in a way that makes it more aligned with Better's implementation. Personally, I think the archetype_node_id is mere noise and not really helpful here --- ## Post #3 by @ian.mcnicoll I agree but I think EHR_STATUS inherits from LOCATABLE so it may be mandatory in RM terms. We could agree that the CDR handles that aspect, of course!! and there is perhaps a case for formalising how we handle non-Composition archetyping as there are cases where other_details carries archetyped info. --- ## Post #4 by @pablo IMO what we are really missing here is the opportunity to spec what should be an EHR_STATUS archetype and tolling support for such archetypes. The EHR_STATUS should be archetyped, even though there is only one archetypable structure there. Short solution would be doing what Better does, good solution would be spec + tooling support. --- ## Post #5 by @yampeku I can try to support the class to be able to generate a couple of examples/use cases --- ## Post #6 by @ian.mcnicoll I agree but just as important than tooling is some way to 'register' these archetypes with the CDR. It is the other_details aspect that does lend itself to being archetyped. --- ## Post #7 by @birger.haarbrandt This is actually on the roadmap for us (because it bugs me on many occasions) but not sure yet how this would be designed. I think @sebastian.iancu mentioned that they do this already in their implementation. Would be great to learn what works (best). --- ## Post #8 by @ian.mcnicoll We would really need something like an EHR_STATUS template, I think, so that we could add other archetype into other_details. That could be uploaded to the CDR like any other template?? --- ## Post #9 by @pablo [quote="ian.mcnicoll, post:8, topic:1199"] We would really need something like an EHR_STATUS template [/quote] Exactly, in fact the ehr_status can be updated through a contribution, and everything updated that way should have archetypes and templates. Including folders, but that's another discussion :) Some limitations and workarounds I implemented in the EHRServer on the status and folder are because archetypes are not clear for those classes. --- ## Post #10 by @sebastian.iancu I'm strongly against making exceptions or workarounds or relaxing things in rest api specs - let's keep specs consistent and predictable. So we should keep name and archetype_node_id mandatory, those are not really noise. If you need some artifacts, here I've upload some close to what we use in our production: https://discourse.openehr.org/t/ehr-status-a-locatable/1055/4?u=sebastian.iancu --- ## Post #11 by @heath.frankel I agree with Sebastian, I think we need to keep the canonical format inline with the RM. Simple formats and SDK can take shortcuts where they see fit to make implementations more efficient. The EHR_STATUS template is implementation dependent, so what we need is the ARCHETYPE and a sample template. The EHR_STATUS archetype used by Ocean is very similar to Sebastian's except it includes the other_details ITEM_TREE as part of the archetype and has an items SLOT. [openEHR-EHR-EHR_STATUS.default.v1.adl|attachment](upload://A7i61fbrCedEAhG1vnD6XJ4W3u7.adl) (1.2 KB) The benefit of this approach is that you can include multiple ITEM and CLUSTER archetypes in the template, not just a single ITEM_TREE, providing a lot more flexibility with the data you have in the EHR_STATUS. Sebastian has a merge use case in his templates, some include demographics, the Ocean EHR_STATUS template has a VIP status, I can think of other research cohort data that may need to be included. [ehr_status.opt|attachment](upload://5XpoWcsuv8bTbQOMUtQjUr5Un1j.opt) (7.7 KB) To enable this same flexibility to support multiple other_details use cases with an ITEM_TREE slot requires you to have another ITEM_TREE archetype with just an items ITEM slot, which seems cumbersome to me. --- ## Post #12 by @sebastian.iancu thanks @heath.frankel I think you are right - I did not payed too much attention to that part, and it is also true that we use that part at this time only for merge-info. The VIP info we store it on PARTY, as well as all associated patient IDs. --- ## Post #13 by @ian.mcnicoll Thanks Heath - your use-case is what I had in mind. Are there any other places in the RM where we might need this sort of non-composition based templating and how do we design the service that would allow us to register these against a particular CDR? I can see that uploading the template would be simple enough but how do you associate it with the correct part of the CDR data tree? --- ## Post #14 by @heath.frankel @ian.mcnicoll, I think we need to be looking at supporting EHR_ACCESS templates. This obviously needs some archetypes, including an EHR_SETTINGS structure, which has not been defined in the RM. Ocean implemented a subtype of EHR_SETTINGS with archetype structures that supported various access control use cases including allow/deny PERSON, ORGANISATION, ROLE, AGENT and specifying compositions that are public and private that override a default access policy. It would be good to provide a draft specification and implementation guidance before too many implementers invent their own solutions. Others have suggested Folders should have templates, which is not something I have had much experience with. --- ## Post #15 by @matijap I don't see ourselves (Better) supporting archetyping of EHR_STATUS anytime soon, but I will take a note to at least ignore the two fields so that we at least accept what the specification demands. --- ## Post #16 by @pablo I agree in which we need to look for support in specs and tooling, also on ITS artifacts. To be consistent with the specs, everything that is archetypable should be able to have ADL/OPT support, even if the structure has no constrant, that should be stated by the AOM/TOM, not by the RM. Without archetypes, there is no consistency in the specs and on implementations. A side effect is those structures are not queryable without archetypes and real paths. Then, each implementer is open to support our not those areas, but at least would have some specs, samples and tooling supporting constraining EHR_STATUS and FOLDER. --- ## Post #17 by @birger.haarbrandt Technically you can query the data without any templates. This is how it is done inside Better and EHRbase at the moment. But of course this is not something that I recommend, it's pretty much freestyling on the RM --- ## Post #18 by @ian.mcnicoll Yup - we have done that already on Better CDR and have the queries to prove it (good to know it is supported on Ehrbase) but as you put it Birger it is 'freestyling' and @matijap, I think you should consider moving it up your roadmap, on that basis. It would be much better to use a template to document and constrain the expected structure. --- ## Post #19 by @thomas.beale [quote="birger.haarbrandt, post:17, topic:1199"] Technically you can query the data without any templates [/quote] Just to be a pedant, what is meant here is that you can't query data that has not been committed using a template. You can and indeed mostly should query only with archetypes. (Just adding this here in case any openEHR newcomers happen to read this and misunderstand it). --- ## Post #20 by @pablo Yes, technically data instances can be queried because all objects/instances will have paths even if there is no archetype for that structure. That is like a schemaless approach, an will need to have information about the structures beforehand. To have predictable structures, and formal compliance with the specs, archetypes are needed, even if there are no constraints there, like having an { * } constrain. In the implementation side, having an archetype or opt allows to precalculate some indexes to make queries faster. If also allows to create query builders, because you have some paths to work with without looking at the data (like looking at a schema to build a query). --- ## Post #21 by @ian.mcnicoll Right now we can query as long as the data is RM compliant, even if the archetype labels in the data are not actually registerd with the CDR (or actually don't exist!). I'm grateful because, at least for us it solved the population query demographics issue mentioned else where but it would be better if it was backed by a template for reference purposes. Here is the structure we embed in EHR_STATUS.other_details. It is actually based on a CKM archetype ``` ```json ---- "otherDetails": { "@class": "ITEM_TREE", "name": { "@class": "DV_TEXT", "value": "Tree" }, "archetype_node_id": "at0001", "items": [ { "@class": "CLUSTER", "name": { "@class": "DV_TEXT", "value": "Anonymised person (PARENT)" }, "archetype_details": { "@class": "ARCHETYPED", "archetype_id": { "@class": "ARCHETYPE_ID", "value": "openEHR-EHR-CLUSTER.person_anonymised_parent.v0" }, "rm_version": "1.0.1" }, "archetype_node_id": "openEHR-EHR-CLUSTER.person_anonymised_parent.v0", "items": [ { "@class": "ELEMENT", "name": { "@class": "DV_TEXT", "value": "Administrative Gender" }, "archetype_node_id": "at0001", "value": { "@class": "DV_CODED_TEXT", "value": "Not known", "defining_code": { "@class": "CODE_PHRASE", "terminology_id": { "@class": "TERMINOLOGY_ID", "value": "local" }, "code_string": "at0012" } } }, { "@class": "ELEMENT", "name": { "@class": "DV_TEXT", "value": "Birth Sex" }, "archetype_node_id": "at0002", "value": { "@class": "DV_CODED_TEXT", "value": "Female", "defining_code": { "@class": "CODE_PHRASE", "terminology_id": { "@class": "TERMINOLOGY_ID", "value": "local" }, "code_string": "at0010" } } }, { "@class": "ELEMENT", "name": { "@class": "DV_TEXT", "value": "Vital Status" }, "archetype_node_id": "at0003", "value": { "@class": "DV_CODED_TEXT", "value": "Alive", "defining_code": { "@class": "CODE_PHRASE", "terminology_id": { "@class": "TERMINOLOGY_ID", "value": "local" }, "code_string": "at0004" } } } ] }, { "@class": "CLUSTER", "name": { "@class": "DV_TEXT", "value": "Identifiable Person (PARENT)" }, "archetype_details": { "@class": "ARCHETYPED", "archetype_id": { "@class": "ARCHETYPE_ID", "value": "openEHR-EHR-CLUSTER.person_identifiable_parent.v0" }, "rm_version": "1.0.1" }, "archetype_node_id": "openEHR-EHR-CLUSTER.person_identifiable_parent.v0", "items": [ { "@class": "ELEMENT", "name": { "@class": "DV_TEXT", "value": "Person Identifier" }, "archetype_node_id": "at0001", "value": { "@class": "DV_IDENTIFIER", "issuer": "GOSH", "assigner": "GOSH", "id": "4ff62524-64bb-421d-b664-eea72ef925ee", "type": "GOSH MRN" } }, { "@class": "ELEMENT", "name": { "@class": "DV_TEXT", "value": "Person Identifier" }, "archetype_node_id": "at0001", "value": { "@class": "DV_IDENTIFIER", "issuer": "GOSH", "assigner": "GOSH", "id": "MRN 12342345", "type": "GOSH ANNEX MRN" } }, { "@class": "ELEMENT", "name": { "@class": "DV_TEXT", "value": "Year of Birth" }, "archetype_node_id": "at0008", "value": { "@class": "DV_DATE_TIME", "value": "2013" } } ] } ] } ``` AQLs -code snippet for creating the select ``` if (ctx.vars.maxAge) { aql = aql + ' and e/ehr_status/other_details/items[openEHR-EHR-CLUSTER.person_anonymised_parent.v1]/items[at0014]/value/value <= \'' + (currentYear - ctx.vars.minAge).toString() + '\''; ``` --- ## Post #22 by @rong.chen Isn't it a good thing to be able to query the data only using archetypes? Templates tend to be local / application specific, and they will change over time possibly faster than archetypes. so in my view, it's desirable to be able to query data (that are created using different kind of templates). --- ## Post #23 by @birger.haarbrandt Yes, it is. I did not choose my words carefully enough. The point is that I would like EHR_STATUS, feeder_audit etc. to be constraint using templates. This would make life easier because you are getting a machine readable documentation of your data structure (e.g. you easily learn how to obtain the VIP flag of an EHR_STATUS.) Then you can easily extract the correct RM paths from the archetypes used in the template. Sorry for the confusion this caused. --- ## Post #24 by @rong.chen Then it makes sense. Thanks, Birger! --- ## Post #25 by @sebastian.iancu @ian.mcnicoll, i guess you know it, but perhaps it will not harm to mention here that the `@class` should have been `_type`, and that most of name/value nodes does not require the type declaration (unless they are coded texts). --- ## Post #26 by @ian.mcnicoll Yes - sorry forgot to make it clear that this uses Better's 'raw json' format that pre-dated the official canonical JSON format has a couple of differences that you highlighted. --- ## Post #28 by @ian.mcnicoll HI Lin, Can you maybe this question to a new topic, as I suspect it might get quite a few different responses and deserves its own space! --- ## Post #29 by @linforest Thank you for your kindly reminder. --- **Canonical:** https://discourse.openehr.org/t/inconsistency-in-rest-api-create-ehr-implementations-needs-spec-clarification/1199 **Original content:** https://discourse.openehr.org/t/inconsistency-in-rest-api-create-ehr-implementations-needs-spec-clarification/1199