We need to define valid payloads in JSON and XML for the POST endpoints that don't have a format defined. This leads to different representation of the same resource on different implementations.
Current body documented on https://specifications.openehr.org/releases/ITS-REST/latest/ehr.html#ehr-ehr-post
Is not compliant with the JSON schema:
+ EHR_STATUS.name is mandatory on the schema
+ EHR_STATUS.archetype_node_id is mandatory on the schema
And a related item is to clarify the use for the _type field when the object doesn’t need it but the object is the root in the payload, like it happens on POST /ehr with the payload being EHR_STATUS, the EHR_STATUS._type is not required because the endpoint already know the expected type.
I think the _type documentation needs to clarify this case, current documentation for _type is: “Metadata attributes (those that are not also RM attributes) will always be prefixed by a '_'. One example is the _type attribute, which should be used to specify the RM type whenever polymorphism is involved or the underlying definition in RM type is abstract (dynamic type is different from the static type). This follows same rule as for XML typing. The value of this attribute MUST be the uppercase class name from the RM specification.“
+ update the JSON examples for POST /ehr
+ clarify usage of _type for root objects in payloads where no polymorphism is present
I adding missing nodes (name, archetype_node_id) to json, but to remove the root _type I’m not very convinced: as you mentioned, the endpoint/resource may create confusion that an EHR is required, but actually expects EHR_STATUS - perhaps better is to keep it to make clear what is expected.
Once again, _type is not always or everywhere required, only when needed - but it should not harm or break the server if is being sent “aggressively”.
Besides this, there is still to discuss “relaxed schema” for some other endpoints (like “name” here), but that is another topic (or issue).