Support for JSON and SDF serialization formats on request headers
Raise CR
Analysis
Execution
Raise CR
Analysis
Execution
Description
Currently sending complex data over headers is not well documented. Also, some implementations might like to have support for SDF or JSON serialization of such data.
see discussion below:
Jake Smolka Hey everyone! I've been looking into the REST API audit headers: https://specifications.openehr.org/releases/ITS-REST/latest/overview.html#design-considerations-http-headers Is there some specification about how the header-values are build, i.e. possible values, formatting and so on. I see that they are directly derived from the openEHR objects, but, for instance, I can see no direct and trivial way of formatting a PARTY_IDENTIFIED's identifiers list from the example in the API doc. And generally it feels like a specific parser is needed, as the values aren't really plain JSON/XML. Wouldn't it make sense to map those headers with only one value directly to it, e.g. openEHR-AUDIT_DETAILS.change_type: code_string="251" (omitting the redundant code_string part and maybe the "s too). And just pass a valid JSON (base64 encoded?) as the value of the committer field? 3:40 PM Thomas Beale This specification is being built to describe and standardise such micro-formats, so could be a place to add any agreed efficient serial representation of types like PARTY_IDENTIFIED etc. https://specifications.openehr.org/releases/SM/latest/serial_data_formats.html Jake Smolka 2 hours ago Does that make sense? But sure, this would solve the ambiguity of the format in the current doc. Sebastian Iancu 1 hour ago having also the other formats (JSON & SDF) will allow more complex data to be sent over those headers Sebastian Iancu 1 hour ago it is consistent with other parts of specs, as we support either canonical RM JSON, wither the SDF Sebastian Iancu 1 hour ago and we keep also current published format Sebastian Iancu 1 hour ago i am not sure I understand you do you mean by "makes sense" - I think you have a point the complex identifiers will turn into a complicated set key/value for those headers, with potential deserialization issues that has to be tackled in specs; thus having a JSON will at least tell how to parse the data Jake Smolka 1 hour ago Yeah sure :slightly_smiling_face: I meant regarding putting rich formatted payload into header value fields. But "the internet" says this is a viable approach as long as the payload is encoded correctly. But I wouldn't keep the current format, like in the examples here https://specifications.openehr.org/releases/ITS-REST/latest/overview.html#design-considerations-http-headers, because it is ambiguous. Sebastian Iancu 1 hour ago in any case we have to maintain backwards compatibility, but we also want to make it easy for implementors Sebastian Iancu 1 hour ago maybe a bit of more specs about current encoding/serialization will also not harm Sebastian Iancu 1 hour ago and not sure, but we could also put a note to deprecated in favour of JSON/SDF - if SEC agrees Jake Smolka 1 hour ago Okay, compatibility is a good point, true. So let's aim for adding other formats, but let's also have a chat about what the others maybe already do with that part of the spec and what they think about changes here. :+1: 1
Currently sending complex data over headers is not well documented.
Also, some implementations might like to have support for SDF or JSON serialization of such data.
see discussion below:
Jake Smolka Hey everyone! I've been looking into the REST API audit headers: https://specifications.openehr.org/releases/ITS-REST/latest/overview.html#design-considerations-http-headers Is there some specification about how the header-values are build, i.e. possible values, formatting and so on. I see that they are directly derived from the openEHR objects, but, for instance, I can see no direct and trivial way of formatting a PARTY_IDENTIFIED's identifiers list from the example in the API doc.
And generally it feels like a specific parser is needed, as the values aren't really plain JSON/XML. Wouldn't it make sense to map those headers with only one value directly to it, e.g. openEHR-AUDIT_DETAILS.change_type: code_string="251" (omitting the redundant code_string part and maybe the "s too). And just pass a valid JSON (base64 encoded?) as the value of the committer field?
3:40 PM
Thomas Beale This specification is being built to describe and standardise such micro-formats, so could be a place to add any agreed efficient serial representation of types like PARTY_IDENTIFIED etc. https://specifications.openehr.org/releases/SM/latest/serial_data_formats.html
Jake Smolka 2 hours ago
Does that make sense? But sure, this would solve the ambiguity of the format in the current doc.
Sebastian Iancu 1 hour ago
having also the other formats (JSON & SDF) will allow more complex data to be sent over those headers
Sebastian Iancu 1 hour ago
it is consistent with other parts of specs, as we support either canonical RM JSON, wither the SDF
Sebastian Iancu 1 hour ago
and we keep also current published format
Sebastian Iancu 1 hour ago
i am not sure I understand you do you mean by "makes sense" - I think you have a point the complex identifiers will turn into a complicated set key/value for those headers, with potential deserialization issues that has to be tackled in specs; thus having a JSON will at least tell how to parse the data
Jake Smolka 1 hour ago
Yeah sure :slightly_smiling_face: I meant regarding putting rich formatted payload into header value fields. But "the internet" says this is a viable approach as long as the payload is encoded correctly.
But I wouldn't keep the current format, like in the examples here https://specifications.openehr.org/releases/ITS-REST/latest/overview.html#design-considerations-http-headers, because it is ambiguous.
Sebastian Iancu 1 hour ago
in any case we have to maintain backwards compatibility, but we also want to make it easy for implementors
Sebastian Iancu 1 hour ago
maybe a bit of more specs about current encoding/serialization will also not harm
Sebastian Iancu 1 hour ago
and not sure, but we could also put a note to deprecated in favour of JSON/SDF - if SEC agrees
Jake Smolka 1 hour ago
Okay, compatibility is a good point, true. So let's aim for adding other formats, but let's also have a chat about what the others maybe already do with that part of the spec and what they think about changes here.
:+1:
1