",
"lifecycle_state": {
"value": "complete",
"defining_code": {
"terminology_id": { "value": "openehr" },
"code_string": "532"
}
},
"commit_audit": {
"_type": "UPDATE_AUDIT",
"system_id": "integration-test-system",
"change_type": {
"terminology_id": "openehr",
"code_string": "249"
},
"committer": {
"_type": "PARTY_IDENTIFIED",
"name": "integration-test-committer"
}
}
}
],
"audit": {
"_type": "UPDATE_AUDIT",
"system_id": "integration-test-system",
"change_type": {
"terminology_id": "openehr",
"code_string": "249"
},
"committer": {
"_type": "PARTY_IDENTIFIED",
"name": "integration-test-committer"
}
}
}
```
EHRbase rejects this with validation errors indicating it expected `DV_CODED_TEXT` fields (`value` and `defining_code`) under `change_type`. Better also rejects it.
## Questions
1. For the REST `Create CONTRIBUTION` request body, should `audit` and `versions[].commit_audit` be serialized as `UPDATE_AUDIT` or as `AUDIT_DETAILS`?
2. Should `UPDATE_AUDIT.change_type` be serialized as `TerminologyCode` / `TERMINOLOGY_CODE`, or as `DV_CODED_TEXT`?
3. Is the OpenAPI schema wrong, the example wrong, or are we misunderstanding how `Terminology_code` in the Service Model should be represented in canonical JSON?
4. Should implementations accept `_type: "UPDATE_AUDIT"`, `_type: "AUDIT_DETAILS"`, both, or should `_type` be omitted for this DTO?
5. For SDK authors, what should be treated as the ground truth: the Platform Service Model, the REST OpenAPI schema, the REST examples, or the common behavior of current CDRs?
Our practical concern is that we need to generate stable TypeScript types and runtime serializers. At the moment, it looks like the most interoperable SDK behavior would be vendor-specific serialization profiles:
- Better: `UPDATE_AUDIT` with `DV_CODED_TEXT`-shaped `change_type`
- EHRbase: `AUDIT_DETAILS` with `DV_CODED_TEXT`-shaped `change_type`
But before encoding that into the SDK, we would like to know whether there is a normative answer we are missing.
Thanks in advance for any clarification.
---
### Author:  [@borut.jures](https://discourse.openehr.org/u/borut.jures)
#### Post date: [2 June 2026 12:11 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/2 "2026-06-02T12:11:19Z")
> [@HHeiser](#):
>
> it looks like the most interoperable SDK behavior would be vendor-specific serialization profiles
Please never do that 🙏
---
### Author:  [@pablo](https://discourse.openehr.org/u/pablo)
#### Post date: [2 June 2026 12:15 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/3 "2026-06-02T12:15:25Z")
@HHeiser you should always check against the spec, the schemas can have errors since those are manually edited.
> **[4.3.6. AUDIT\_DETAILS Class - Common Information Model](https://specifications.openehr.org/releases/RM/latest/common.html#_audit_details_class)**
>
> Class | openEHR Common Information Model specification
**AUDIT\_DETAILS.change\_type is DV\_CODED\_TEXT**
In fact, the openEHR SDK schema has DV\_CODED\_TEXT [openEHR-SDK/src/main/resources/json\_schema/openehr\_rm\_1.1.0\_all.json at master · CaboLabs/openEHR-SDK · GitHub](https://github.com/CaboLabs/openEHR-SDK/blob/master/src/main/resources/json_schema/openehr_rm_1.1.0_all.json#L378-L380)
That schema was copied and evolved in parallel to the spec schema, adding more strict constraints like regexes for formatted data, some of those were contributed back the the spec.
Another thing is that you can do a GitHub Blame on the official schema to check when the change\_type started to reference the `TerminologyCode`. But! also check you are using the latest version.
---
### Author:  [@HHeiser](https://discourse.openehr.org/u/HHeiser)
#### Post date: [2 June 2026 13:41 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/4 "2026-06-02T13:41:06Z")
Thanks for the reply.
The main problem we have is not with `AUDIT_DETAILS` (which clearly requires `AUDIT_DETAILS.change_type` as `DV_CODED_TEXT`), but with `UPDATE_AUDIT` (which should require `UPDATE_AUDIT.change_type` as `TERMINOLOGY_CODE`), since this is the object that should be used in the `/contribution` endpoint. I could not find `UPDATE_AUDIT` in your SDK schema.
However, the official [OpenAPI specification](https://specifications.openehr.org/releases/ITS-REST/Release-1.0.3/computable/OAS/ehr-validation.openapi.yaml), which we use for our TypeScript SDK, contradicts itself by using `TerminologyCode` for the `change_type` in the properties but the shape of `CodedText` in the example (See Line 3292-3314):
```yaml
UpdateAudit:
title: UPDATE_AUDIT
required:
- change_type
- committer
type: object
properties:
_type:
type: string
default: UPDATE_AUDIT
change_type:
$ref: '#/components/schemas/TerminologyCode'
description:
$ref: '#/components/schemas/UDvText'
committer:
$ref: '#/components/schemas/UPartyProxy'
description: The set of attributes required to document the committal of an information item to a repository. Used by the server to create an AUDIT_DETAILS object.
example:
change_type:
value: creation
defining_code:
terminology_id: openehr
code_string: '249'
description: Description text
committer:
_type: PARTY_IDENTIFIED
name: A user name
```
The same problem is found in the website version of the [ITS-REST specs](https://specifications.openehr.org/releases/ITS-REST/Release-1.0.3/ehr.html#tag/CONTRIBUTION/operation/contribution_create):
The attribute `audit` is described as `object(UPDATE_AUDIT)`, but the example on the right shows `change_type` as `DV_CODED_TEXT` (with `defining_code`), as if it would be part of `AUDIT_DETAILS`
**Does that mean that the API-Specs are wrong, the RM and SM specs are correct and should be considered the sole ground truth? So that in the Contribution Endpoint, `audit` and `commit_audit` should be of type `UPDATE_AUDIT` with `change_type` of type `TERMINOLOGY_CODE`.**
* * *
It may additionally be an implementation problem, as Better and EHRbase do not handle this correctly:
EHRbase incorrectly expects `AUDIT_DETAILS` with `change_type` of type `DV_CODED_TEXT` and yields this error otherwise:
`"Error while processing given json input: Could not resolve type id 'UPDATE_AUDIT' as a subtype of `com.nedap.archie.base.OpenEHRBase`: no such class found\n at [Source: UNKNOWN; byte offset: #UNKNOWN] (through reference chain: org.ehrbase.openehr.sdk.response.dto.ContributionCreateDto[\"audit\"])"`
Better correctly expects `UPDATE_AUDIT` (otherwise yields `"Could not resolve type id 'AUDIT_DETAILS' as a subtype of com.marand.thinkehr.server.rest.data.openehr.OpenEhrCommitAudit: known type ids = [UPDATE_AUDIT] (for POJO property 'audit')"`, but ignores the given `change_type`value silently and always persists `249|creation`.
---
### Author:  [@pablo](https://discourse.openehr.org/u/pablo)
#### Post date: [2 June 2026 18:34 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/5 "2026-06-02T18:34:30Z")
@HHeiser where is UPDATE\_AUDIT in the RM?
---
### Author:  [@pablo](https://discourse.openehr.org/u/pablo)
#### Post date: [2 June 2026 20:55 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/6 "2026-06-02T20:55:56Z")
TL;DR: IMO the SM spec and the REST API schemas should be fixed, changing change\_type to DV\_CODED\_TEXT.
Long answer:
I got it now, it’s not an RM class, it’s from the SM ([openEHR Platform Service Model](https://specifications.openehr.org/releases/SM/latest/openehr_platform.html#_update_audit_class)). I thought the SM wasn’t even considered by the REST API, though we designed that to be the source for the REST API. There in the SM change\_type is actually [Terminology\_code](https://specifications.openehr.org/releases/BASE/latest/foundation_types.html#_terminology_code_class), which I think is incorrect and should be DV\_CODED\_TEXT.
UPDATE\_AUDIT is used in [EHR API openEHR specs](https://specifications.openehr.org/releases/ITS-REST/Release-1.0.3/ehr.html#tag/CONTRIBUTION/operation/contribution_create)
Defined as: “the set of attributes required to document the committal of an information item to a repository. Used by the server to create an AUDIT\_DETAILS object.”, which is the definition taken from the SM.
So UPDATE\_AUDIT is just AUDIT\_DETAILS without the system\_id and time\_committed, and there is no reason why the change\_type is a Terminology\_code.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [2 June 2026 21:54 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/7 "2026-06-02T21:54:30Z")
There is a bit too much text posted here and I hardly follow anymore what is what…
But, I am glad that you’ve got Better and EHRbase aligned - if I understand for your message they are.
The SM specs are outdated, in upcoming REST API they are not referred anymore. Terminology\_code is a type introduce recently (last few years) but I don’t think is adopted, and I think it got mixed in some specification as dependency (like in SM), but that was not a deliberate action (as it is a breaking change).
The json-schema (ITS-JSON repo) is also potentially outdated, as it was generated from/with Archie and it might validate json payload, but not sure if is validating REST api resources - I would not rely on that too much for now.
> [@HHeiser](#):
>
> The main problem we have is not with `AUDIT_DETAILS` (which clearly requires `AUDIT_DETAILS.change_type` as `DV_CODED_TEXT`), but with `UPDATE_AUDIT` (which should require `UPDATE_AUDIT.change_type` as `TERMINOLOGY_CODE`), since this is the object that should be used in the `/contribution` endpoint. I could not find `UPDATE_AUDIT` in your SDK schema.
For the record, can you tell:
- which version of REST API specs are you using? (I suppose latest=1.0.3, not development, right?)
- which OAS yaml variant (there are 3 types) do you use for SDK code-generation?
> [@HHeiser](#):
>
> what the ground truth should be: the REST specification, the OpenAPI schema, the examples, or the behavior of existing CDRs.
I would say the order is:
1. openEHR REST specification on first place
2. CDR implementation, assuming they are conformant
3. OAS schema (yaml files) - but I know there were some limitation in what can be specified there, because of polymorphism and the OpenAPI 3.0 specs, and the redocly renderer; perhaps newer OAS specs version are more powerful, but we are not there yet
4. RM validatiton rules / constraints - where applicable
5. Examples - but treath them as Examples
So bottom line, what prevails here: ITS-REST specs (check also development branch), and CDR implementations.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [2 June 2026 21:58 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/8 "2026-06-02T21:58:25Z")
> [@pablo](#):
>
> @HHeiser where is UPDATE\_AUDIT in the RM?
Some types had to be introduced by OAS schema, because RM type were not designed to act as REST resources. In this case, the RM mandates some properties to be filled in, but those only happen after server side process the request. Thus the request payload is not a full valid RM instance - hence those REST-only types defined in OAS yaml.
---
### Author:  [@ian.mcnicoll](https://discourse.openehr.org/u/ian.mcnicoll)
#### Post date: [3 June 2026 08:16 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/10 "2026-06-03T08:16:10Z")
\>\> Some types had to be introduced by OAS schema
That seems to be the basis for the confusion. The REST specs and examples are aligned to the RM, whereas the OAS introduces a pseudo-class UPDATE\_DETAILS which is essentially a constraint on AUDIT\_DETAILS with some defaults, but not actually exist as a valid RM object.
Note that the GET Contribution expects an AUDIT\_DETAILS to be returned
It feels as if
> \*\*`change_type` of type `TERMINOLOGY_CODE`
> \*\*
is just an error, and that `change_type` should be a DV\_CODED\_TEXT
and my interpretation is that the Better CDR is compliant with the OAS but has not understood the requirement to turn UPDATE\_DETAILS into plain AUDIT\_DETAILS on persisting the data. Possibly built backwards from the OAS like the Cistec Typescript SDK?
Clearly this does need fixed or at least clarified. There may be other similar issues with other OAS wrappers like updateVersion?
---
### Author:  [@thomas.beale](https://discourse.openehr.org/u/thomas.beale)
#### Post date: [3 June 2026 11:13 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/11 "2026-06-03T11:13:28Z")
> [@ian.mcnicoll](#):
>
> That seems to be the basis for the confusion. The REST specs and examples are aligned to the RM, whereas the OAS introduces a pseudo-class UPDATE\_DETAILS which is essentially a constraint on AUDIT\_DETAILS with some defaults, but not actually exist as a valid RM object.
This is precisely what the Abstract Platform Services spec was for - to specify these things, including transactions to the API, which is what we are talking about here.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [3 June 2026 11:20 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/12 "2026-06-03T11:20:48Z")
Ah thanks Ian, this gets more clear now.
I see that in 1.0.2 specs (which were not based on OAS) we had examples on POST with:
```auto
"commit_audit": {
"change_type": {},
"description": {},
"committer": {
/* optional structure - will use the outer committer if absent */
}
}
```
and response with
```auto
"change_type": {
"value": "creation",
"defining_code": {
"terminology_id": {
"value": "openehr"
},
"code_string": "249"
}
}
```
But this was changed in 1.0.3 because of refactor on OAS (which required a local type) and alignment to SM [UPDATE\_AUDIT](https://specifications.openehr.org/releases/SM/development/openehr_platform.html#_update_audit_class). As we decided lately, that wasn’t a good move, and the next release on REST 1.1.0 does not have the tight coupling with SM, and we can emit a correction or clarification there.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [3 June 2026 11:39 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/13 "2026-06-03T11:39:40Z")
Back to these questions:
> [@HHeiser](#):
>
> - For the REST `Create CONTRIBUTION` request body, should `audit` and `versions[].commit_audit` be serialized as `UPDATE_AUDIT` or as `AUDIT_DETAILS`?
> - Should `UPDATE_AUDIT.change_type` be serialized as `TerminologyCode` / `TERMINOLOGY_CODE`, or as `DV_CODED_TEXT`?
> - Is the OpenAPI schema wrong, the example wrong, or are we misunderstanding how `Terminology_code` in the Service Model should be represented in canonical JSON?
> - Should implementations accept `_type: "UPDATE_AUDIT"`, `_type: "AUDIT_DETAILS"`, both, or should `_type` be omitted for this DTO?
> - For SDK authors, what should be treated as the ground truth: the Platform Service Model, the REST OpenAPI schema, the REST examples, or the common behavior of current CDRs?
So, in conclusion, for the specs we should change:
- both `UPDATE_AUDIT` and `AUDIT_DETAILS` should have `change_type` property as `DV_CODED_TEXT`; we’ll drop the `TERMINOLOGY_CODE` typing of that property.
- examples should be consistent with schema
- the question is whether to clear out that the `UPDATE_AUDIT` is just `AUDIT_DETAILS` without server side values i.e. `system_id` and `time_committed`; will then CDRs going to accept it (as is not a type defined in the RM); in any case `_type` is then necessary.
Would you agree on this? (ping also @matijap @vidi42 and @birger.haarbrandt )
SM specs remains decoupled and should not play a role in this.
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [3 June 2026 15:05 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/14 "2026-06-03T15:05:34Z")
I made a ticket [SPECITS-95](https://openehr.atlassian.net/browse/SPECITS-95) and we’ll try to fix this in upcoming 1.1.0
---
### Author:  [@HHeiser](https://discourse.openehr.org/u/HHeiser)
#### Post date: [3 June 2026 18:11 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/15 "2026-06-03T18:11:43Z")
Great @sebastian.iancu, thanks for the effort!
Release 1.1.0 has many important and useful improvements. Any rough ideas on when it will be published?
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [3 June 2026 18:25 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/16 "2026-06-03T18:25:49Z")
It was finalize, we are now awaiting final acceptance. I can imagine we’ll be able to release it in the upcoming 3-4 weeks, if nothing new more urgent is discovered.
Thanks for your report and analysis - you were very sharp to spot this issue.
---
### Author:  [@HHeiser](https://discourse.openehr.org/u/HHeiser)
#### Post date: [3 June 2026 18:43 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/17 "2026-06-03T18:43:51Z")
A timeline measured in weeks is great!
And I am just the investigator and messenger here, this bug was spotted by Martin, one of our engineers that is working on the TS SDK 🙂 I will forward your compliments 👍
---
### Author:  [@sebastian.iancu](https://discourse.openehr.org/u/sebastian.iancu)
#### Post date: [11 June 2026 21:27 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/18 "2026-06-11T21:27:06Z")
I pushed the change in the specification now - see [EHR API openEHR specs](https://specifications.openehr.org/releases/ITS-REST/development/ehr.html#tag/CONTRIBUTION/operation/contribution_create) - so that we can release it soon, together with the rest of changes for Release 1.1.0
---
### Author:  [@pablo](https://discourse.openehr.org/u/pablo)
#### Post date: [14 June 2026 17:46 UTC](https://discourse.openehr.org/t/contribution-update-audit-change-type-in-rest-api-vs-vendor-implementations/16928/19 "2026-06-14T17:46:52Z")
That was the right choice, `TERMINOLOGY_CODE` didn’t make any sense in REST or SM, just added confusion.