Review format of Annotation.annotationSource

[tschaffter]

The current design is based on the format adopted by Google Healthcare API.

• Creating and managing annotation records
• Google AnnotationSource schema (beta)

First, Google defined the object CloudHealthcareSource that includes a single property: name. This name can be used to build a URL to get the resource. This approach allows to easily reference different objects such as our Note schema or any (FHIR) schema that could be added in the future. Simplify storing the DB record ID is not possible and advised because: 1) ObjectId in MongoDB are not unique across multiple collections, 2) does not implement ID opacity (good practice for security).

We could have:

properties:
    annotationSource:
        type: string
        example: "name/of/a/resource"

This implementation is the most straightforward. However it requires the user of the API to read the doc to figure out what the value of annotationSource must be the name of a resource. This design also limit future extension and is more likely to introduce breaking change than the approach adopted by Google with

properties:
    annotationSource:
        schema:
            $ref: CloudHealthcareSource.yaml

where CloudHealthcareSource.yaml would be

properties:
    name:
        type: string
        example: "name/of/a/resource"

One assumption we make if annotationSource is a string and not a schema that we can extend in the future is that the source of an annotation must be accessible through the same API service instance as where the annotation objects are saved. However, there could be benefit to storing annotation to a data node instance that is different from the data node that includes the source information, for example for scalability and performance reason.

Proposal

Defining CloudHealthcareSource.yaml limit the risk of introducing breaking changes in the future and provide more flexibility. Thus, I would recommend adopting this design.

[tschaffter]

Related to #89

[github-actions[bot]]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.