numde/compass-implementation-guide

compass-implementation-guide's Issues

Wrong linkId in gecco reference questionnaire

compass-implementation-guide/input/questionnaire-gecco.json

Line 3928 in 054b4f1

"question": "anamnesis.historyOfTravel.countries",

The "enableWhen"-object of the question with the linkId "1.21.4" has a wrong linkId; it should be 1.21.3 (?)

Suggestions for Questionnaire versioning documentation

Current text

Questionnaire-IDs and Versioning

Besides the technical identifiers, which are stored in Questionnaire.id and Questionnaire.identifier, there is another "world-wide unique" identifier per Questionnaire, called Questionnaire.url. Often, the metadata (Questionnaire) is changed during the data capturing process. Therefore, FHIR provides the Questionnaire.version field to version metadata. Please note that this version is different from Questionnaire.meta.versionId, which corresponds to the FHIR repositories internal versioning.

The QuestionnaireResponse references its corresponding Questionnaire by QuestionnaireResponse.questionnaire, which is a canonical url. Its value MUST correspond to Questionnaire.url. The FHIR standard allows appending the version to a canonical url by seperating it with a pipe (|) character. If you follow this implementation guide, QuestionnaireResponse.questionnaire should always contain also Questionnaire.version.

1. The documentation of canonical URLs makes it clear that canonicals are the preferred way to refer resources that have one: "The canonical URL is the preferred way to reference a resource instance for the resource types on which it is defined." (emphasis in the original). Accordingly, I think it would be good to make it clear. that this is the main way to refer to the questionnaire (and move the fact that it's a canonical URL (with link to the documentation) to this first section, so readers become aware of this term and know where to find the meaning)
2. The current text says: "Often, the metadata (Questionnaire) is changed during the data capturing process. Therefore, FHIR provides the Questionnaire.version field to version metadata." I don't quite understand this usage of the term "metadata" here. I would not consider Questionnaire content - the questions, allowed answers etc. - meta-data, since they are actually the data that define the questionnaire. In that context, meta-data would only be things like Questionnaire.version, Questionnaire.publisher etc. that provide context. Even if the current usage may reflect current usage specifically within the NUM-COMPASS project, I think it will be confusing to people coming from the outside or from a general FHIR-background. Likewise, the changes to be tracked with version are typically actual changes in the questions etc. themselves, i.e. in the core data of the questionnaire. Accordingly, I would rephrase these sentences without using the term "metadata", e.g. "Often, questionnaires are updated while the data capturing process is already ongoing. Therefore, FHIR provides the Questionnaire.version field to version Questionnaire resources, allowing users to distinguish between different version of the same questionnaire."
3. I think the last paragraph would be clearer if the rules are collected at the end, e.g. smt. like: "The QuestionnaireResponse references its corresponding Questionnaire by QuestionnaireResponse.questionnaire, which is a canonical url. The FHIR standard allows appending the version to a canonical url by separating it with a pipe (|) character. Implementers following this implementation guide MUST put the Questionnaire.url with the appended Questionnaire.version. in QuestionnaireResponse.questionnaire."
4. If the Questionnaire version must be added to the URL, I suppose it implies that Questionnaire.version must also always be filled in Questionnaire. If so, I guess that should be added to the documentation. Alternatively, if the version is not required to be set, one would have to change the above to say that the version must be added if it is set in Questionnaire.