The POST /directory doesn’t specify if the body can be empty.
https://specifications.openehr.org/releases/ITS-REST/Release-1.0.2/ehr.html#directory-directory-post
Testing EHRBASE it seems the current implementation requires the body of the request to be non empty.
IMO creating an empty ehr.directory is totally valid. What do others think?
Maybe this should be clarified in the REST API specs.
Can you help me understand the implication of an empty directory by means of a use case?
This question is about conformance with the specifications, not about business requirements or use cases.
In terms of conformance, we need the specification to be complete, correct and unambiguous. Which means, we should specify normal cases, border cases and fail/invalid cases. Reading the current spec, it doesn’t say if an empty body in the POST /directory is supported or not, so different implementations can choose to support or not support that border case. This generates incompatible implementations, because there is room for interpretation, which shouldn’t happen on a formally defined specification (meaning the ‘unambiguous’ aspect is not good).
A use case should come from the business requirements, which is on a different semantic level than compliance testing. Though, use cases should be mapped to the specification, so for implementing a specific use case, a complete, correct and unambiguous spec is also needed.
I’m currently dedicated to conformance testing work, which makes me review the specs in detail, that is why I have these very low level questions.
Hope that helps.
Although it doesn’t say it exactly, the EHR model implies that directory and also folders attributes should only be populated by non-empty values. Since these fields are OBJECT_REFs, the field can be technically filled with no absolute guarantee that the OBJECT_REF points to something.
We don’t have a formal way of forcing the target of an OBJECT_REF to exist or be a non-empty structure, but that would be the more obvious invariant to express - I can’t think of any use for empty directory or folders.
Also, creation of non-referring OBJECT_REFs has to be considered a bug.
If an API only causes the creation of a directory or folders when being supplied some actual contents, then this condition will be satisfied. This is what the Platform definition specifies in the class I_EHR_DIRECTORY:
create_directory (
ehr_id: UUID[1],
a_dir_struct: UV_FOLDER[1]
)
Pre_has_ehr: has_ehr (an_ehr_id)
Pre_definitions_valid: definitions_valid (a_dir_struct)
Pre_no_directory: not has_directory (ehr_id)
Pre_content_valid: valid_content(a_dir_struct)
It is not 100% clear to me whether the corresponding REST API call requires the body parameters or if they are both optional.
{
"items": [...],
"folders": [{}]
}
I suggest that it should be documented that at least one of items or folders is non-empty.
I’m not sure if I’m following, I think you are describing a NULL directory or folders with a non-NULL OBJECT_REF. But I’m talking about creating the FOLDER instance pointed by the OBJECT_REF, like we do with the EHR_STATUS, which is the same case since it is pointed by an OBJECT_REF. In POST /ehr an EHR_STATUS is created for the EHR when no body payload is provided. My question is related to that behavior, why can’t the same be used for POST /directory with an empty body payload?
So this is not about creating an OBJECT_REF that points to nothing, but just the FOLDER, VERSIONED_FOLDER and OBJECT_REF when no body is provided in POST /directory (this is also not for ehr.folders).
Also, thinking about the FOLDER attributes, the only required one is the name, and since it is the root, it could just be “/” or “root” or whatever that could be updated later by PUT /directory
That is not currently specified.
Only pointing out that although technically possible, it should be treated as an error, for obvious reasons.
The other semantics I described in the Platform spec indicate (correctly in my view) that the only way to create EHR.directory is by providing some content, i.e. non-empty directories cannot be created.
But I don’t think the case you described is exactly the case I described, since I’m considering actually creating the FOLDER and VERSIONED_FOLDER instances with default values, not just the OBJECT_REF.
What I don’t see clearly is why we have a difference between create_ehr, that actually creates a default EHR_STATUS, and create_directory for creating a default FOLDER without providing data.
**create_ehr** (
an_ehr_status: `EHR_STATUS[0..1]`
): `UUID`
Thought I’m not pushing on supporting this, I think needs some clarification on the REST API spec for supporting or not supporting creating the directory without a payload I think most people reading the REST API spec won’t read the Service Model).
The data is in the a_dir_struct: UV_FOLDER[1] parameter - or am I missing something basic?
I’m not talking about the SM, I see the parameter is there, and we know the REST API and the SM have is not 1 to 1 right now, we still need to harmonize…
My initial question came from the REST API spec only. Let me go back one step:
If we support or not creating a default folder without providing a body in the HTTP request in the REST API endpoint POST /directory, should be explicitly said in the REST API spec, since this is a border case and is not clear if it is supported or not (I’m talking just REST API, not SM).
Comparing the POST /ehr that creates a default EHR_STATUS without providing any data for it, I was thinking, for consistency, we might be able to create a default FOLDER for ehr.directory on POST /directory without a body in the HTTP request.
Though I know the cases are not exactly the same, since POST /ehr works over the EHR resource and the associated EHR_STATUS, I guess because it is 1…1 in the RM. And POST /directory works over the FOLDER resource, managing only the ehr.directory structure. If ehr.directory would be 1…1 I guess POST /ehr will also create that structure (OBJECT_REF, VERSIONED_FOLDER, FOLDER) with default values, isn’t it?
The argument against doing that is that the directory structure is entirely optional, and not used at all by some implementations - e.g. AFAIK, Better’s system doesn’t use FOLDERs, they use only tags to achieve a similar effect. So creating this default structure wouldn’t make sense in that product. The relationship between EHR and EHR_STATUS is on the other hand mandatory, so something has to be created for EHR_STATUS when an EHR is created.
So I think in this case, the SM is correct (there are other places you have found already that we need to fix…!)
Why would you have a directory/folder endpoint if there is no folder implementation (which exists in Better btw)
We are on agreement, I guess this should be addressed when we dedicate some time for SM - REST API harmonization. I have some issues on my list, I can create them on Jira to avoid forgetting.
I guess the FOLDER endpoints are just for front-end interaction, in the back-end they chose to implement folders as tags, which is fine IMO. I also guess they might have other features depending on tags, and tagging is flexible enough to represent both folders and tags, and maybe other classification/organization structures if tags are hierarchical. All guesses, I don’t know their systems or their design rationale.