Many progammers ar notoriously example-driven so using good examples and documentation is important, see below.
1. In the STORED QUERIES section...change “some users/developers write queries, others just consume them” —> ”some users/developers write queries, others just call/execute them and consume the responses”
2. It would be more pedagogical if query examples (in all sections) contained (at least) two dynamic query parameters and something more “clinical” than “uid”, for example something like glucose_limit and hba1c_limit
3. Populate the parameters in ”Example URI” to contain example values after the equal (=) signs.
4a. The example ”GET /query/org.openehr::compositions?temperature_from=36&temperature_unit=degC” is good rather good except that another qualified name than the ”reserved” org.openehr::composition should probably be used...
4b. ...and degC vs deg C (used in e.g. http://www.openehr.org/releases/AM/latest/docs/ADL2/ADL2.html) is potentially confusing. It is likely also wrong and instead should be Cel according to UCUM (see also previous mailing list discussions...) so use something less controversial in the example
5. In the "Common Query Parameters" section under "ehr_id" change to:
”This parameter SHOULD be supplied when executing ’single EHR queries’ and MAY be used by the underlying backend to perform routing, optimizations or similar, It MUST NOT be supplied for ’population queries’ and similar multi-patient queries.”
6. The section "Common Query Parameters" could be renamed “common headers and query parameters” and
7. "ehr_id" should be replaced by "openEHR-EHR-id" in at least two places of the document referring to the header name.