Detailed review of DIRECTORY operations on the Service Model


1. Directory paths clarifications


[See also:]

Current spec for directory paths is name-based, allow duplicated sibling folder names, and proposes a “uniqueness modifier” to handle the duplicated sibling names. And shows examples like: /folders[hospital episodes]/items[1]

Potential issues / improvements / discussion points:

a. it is not stated how that “uniqueness modifier” is actually used and what happens if the folder name has the brackets proposed to signal the modifier

b. in the example, there is an inconsistent pointing mechanism: for subfolders their name is used, for items their index is used, why not use the also in the path?

c. the main idea of the path is reference a folder or item in the directory structure, why not consider using uids? (I know names are mandatory and uids are optional, but uid might be needed either way for versioning folders, commented bellow)

d. should each path reference just one folder/item at most? would it be useful to reference a list of siblings with same name by one path? (like an XPath when multiple siblings have the same name)

Pros / Cons / Actions for name-based paths:

+ Pro: name is mandatory on LOCATABLE
+ Con: name is not unique between siblings, a path can point to many siblings
+ Actions: make the name sibling-unique for folders if we want one path-one node, or add explicit support for referencing many siblings with the same name by a path.

2. Considering UIDs to reference FOLDERs and items (mainly COMPOSITIONS)

Currently we agreed on setting the OBJECT_VERSION_ID to the COMPOSITION.uid field to have some version management without the VERSION<COMPOSITION>. So to reference COMPOSITIONS (items) we are covered and really don't need a path to get a COMPO from the directory. To do things like "remove item from folder" we can also use the COMPO.uid, but also need a reference to the parent FOLDER.

Since FOLDER is also a top-level versionable object, wouldn't make sense to also set the OBJECT_VERSION_ID to FOLDER.uid? This would make the uid mandatory for FOLDERs, as I think we have de-facto for COMPOSITIONs.

If that makes sense, then, there is no need to reference FOLDERs by path, we could use the UID, and even use the UID to reference a specific version of the FOLDER, since it is an OBJECT_VERSION_ID (same as we currently use COMPOSITION.uid).

3. Service Model operations

a. has_path(ehr_id, path): Boolean

We need to review the analysis on point 1. to be sure the correct result is returned from this operation, e.g. if the path points to multiple folders, is that "true"? (I guess yes but we need to specify if referencing multiple folders is possible or not)

b. update_directory(ehr_id, folder)

This is the only operation that allows to modify the folder structure and requires the whole structure given to make each modification, which IMHO is not an optimal solution.

We could provide something like:

+ update_folder(ehr_id, path_to_folder, folder)
+ update_folder(ehr_id, folder_uid, folder)

path_to_folder / folder_uid would be identifiers to the parent folder where the "folder" structure should be updated, requiring to pass only the internal structure that changes, not unrelated folders and references to items.

The idea is: simplify things to the client avoiding them to have to handle the whole directory structure to change one thing.

Considerations for versioning:

+ I know the current operation might lead to a really simple implementation for FOLDER versioning, but sees too much to pass the whole thing to update one thing.
+ With the proposed operations above I don't think FOLDER versioning would be much complex, for instance just one VERSIONED_OBJECT<FOLDER> for the is what is needed to version the whole thing when one internal FOLDER is modified. I would clone the current structure internally and apply the changes to that structure, then set that as the latest version for the, while maintaining the previous one. Of course this is lineal versioning and is full structure versioning, smarter people than me could think of delta versioning to save space.

c. delete_directory(ehr_id)

For deleting, we currently have one operation to delete the whole directory, which IMO doesn't make sense. For that I would define operations to delete specific items from FOLDERs or FOLDERs from FOLDERs.

Some alternatives:

+ delete_folder(ehr_id, path_to_folder, path_to_folder_to_del)
+ delete_folder(ehr_id, folder_uid, folder_uid_to_del)
+ delete_folder(ehr_id, folder_uid_to_del)

Operation 3 points directly to the folder to delete, which internally should be deleted from the parent in the server, but the client doesn't need to manage that.

I think deleting one folder would be more common use case than deleting the whole directory of an EHR. Still those operations include the ability of deleting the directory.





Pablo Pazos




Affects versions

SM Release 1.0.0