Skip to content

Update release notes and changelog for ADE 1.5.1 release #582

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
cookeac merged 1 commit into from
Dec 10, 2025
Merged

Update release notes and changelog for ADE 1.5.1 release #582

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 16 additions & 2 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,19 @@
# Changelog

## [v1.5.0](https://github.com/adewg/ICAR/tree/HEAD)
## [v1.5.1](https://github.com/adewg/ICAR/tree/HEAD)

[Full Changelog](https://github.com/adewg/ICAR/compare/v1.4.1...HEAD)
[Full Changelog](https://github.com/adewg/ICAR/compare/v1.5.0...HEAD)

**Closed issues:**

- Add further enumerated values to icarProductionPurposeType [\#566](https://github.com/adewg/ICAR/issues/566)
- Animal Disposal Types Mapping [\#565](https://github.com/adewg/ICAR/issues/565)
- Add parents and other attributes in parturition icarProgenyDetailsResource [\#564](https://github.com/adewg/ICAR/issues/564)
- Prepare for a small ADE 1.5 release [\#536](https://github.com/adewg/ICAR/issues/536)

## [v1.5.0](https://github.com/adewg/ICAR/tree/v1.5.0) (2025-11-04)

[Full Changelog](https://github.com/adewg/ICAR/compare/v1.4.1...v1.5.0)

**Closed issues:**

Expand Down Expand Up @@ -34,6 +45,9 @@

**Merged pull requests:**

- Merge from Develop - schema bundling fixes and changelog [\#574](https://github.com/adewg/ICAR/pull/574) ([cookeac](https://github.com/cookeac))
- Bundle schema job fix [\#573](https://github.com/adewg/ICAR/pull/573) ([AlexeyHardCode](https://github.com/AlexeyHardCode))
- Update changelog for v1.5.0 [\#572](https://github.com/adewg/ICAR/pull/572) ([cookeac](https://github.com/cookeac))
- Fix typo: regurgiating → regurgitating in observation summary metrics [\#571](https://github.com/adewg/ICAR/pull/571) ([Copilot](https://github.com/apps/copilot-swe-agent))
- Fix spelling errors in identifier type names [\#570](https://github.com/adewg/ICAR/pull/570) ([Copilot](https://github.com/apps/copilot-swe-agent))
- Merge from Develop branch for ADE 1.5 release [\#569](https://github.com/adewg/ICAR/pull/569) ([cookeac](https://github.com/cookeac))
Expand Down
48 changes: 20 additions & 28 deletions ReleaseNotes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,38 +1,30 @@
# Important changes from ADE v1.2.x
## Release notes for ADE v1.5.1
ADE 1.5.x provides greater support for code generation from Open API specifications.
In particular:
- OpenAPI files and JSON schemas have been adjusted to work with OpenAPI 3.1 (implemented in ADE 1.4 release)
- There are multiple OpenAPI files in the [url-schemes](https://github.com/adewg/ICAR/tree/ADE-1/url-schemes) folder. You will always find simple GET examples in the exampleUrlScheme.json, and other files contain examples of GET, POST, and batch POST methods for feeds, health, management, milk, performance, registration, reproduction, and sorting resources.
- **Importantly** the [bundled-schemes](https://github.com/adewg/ICAR/tree/ADE-1/bundled-schemes) folder contains a generated [combinedURLScheme.json](https://github.com/adewg/ICAR/blob/ADE-1/bundled-schemes/combinedURLScheme.json) OpenAPI specification that combines all resources into a single scheme. We encourage you to target this for code generation into your language of choice.

There are some important changes that particularly affect OpenAPI code generation between ADE 1.2.x and ADE 1.3.x and later.
If you have implemented ADE 1.2.x or earlier, and particularly if you have used OpenAPI code generation in languages such as C# and Java, you should be aware of these changes.
Contributors have found success using recent versions of [OpenAPI Generator](https://openapi-generator.tech/) that support OpenAPI 3.1 to generate code for C# and Java. If you are targeting Python, consider the [ICAR-Pydantic](https://github.com/adewg/ICAR-pydantic) Github project and repository.

## Standard Discriminator for resources is now `ResourceType`
# Specific fixes from v1.5.0 to v1.5.1:
1. Fix a problem with the scripts that generated the bundled combinedURLScheme.json with the wrong OpenAPI version.
2. Create a new icarAnimalBaseResource (type) that is inherited by both icarAnimalCoreResource and icarProgenyDetailsResource. This allows some requested/expected optional progeny attributes to be available for parturition events. This has been tested with C# and Java code generation and does not seem to break anything with Animal APIs.

The OpenAPI specification allows you to specify a "discriminator" which is used to support de-serialisation of objects from JSON text to native in-memory objects. ADE 1.2.x did not implement this consistently, primarily due to limitations in version 5.x of the common [openapi-generator tool](https://openapi-generator.tech/).
You can see the full list of changes at [the ADE 1.5.1 Release](https://github.com/adewg/ICAR/releases/tag/v1.5.0) or in the [changelog](https://github.com/adewg/ICAR/blob/ADE-1/CHANGELOG.md)

You can use a discriminator to differentiate, and help to de-serialise JSON into the correct concrete classes (a concept in object-oriented languages like C# and Java). For instance, if you read from a data source that may contain `icarResource` objects, you want to know whether the actual object being read should be instantiated as an `icarTreatmentEventResource`.

The OpenAPI rules for discriminators are:
* The same discriminator must be used in the base class and derived classes
* The discriminator must be declared as a string property
* The discriminator is required
# Changes from previous versions of ADE

We had discriminators in ADE 1.2.x, but these were not declared as string properties (only as a discriminator) and we used different discriminators for Resources (`resourceType`) and Events (`eventType`). However, events are also resources.
If you have implemented ADE 1.3.x you will find changes to `icarStatisticsResource` which corrects the use of arrays in that version, and changes to `icarWithdrawalEventResource` and `icarConsignmentType` which relate to inheritance/aggregation problems that have been fixed.

Version 5.x of openapi-generator does not work properly if the discriminator is defined as a property and required. This does not match the OpenAPI specification.
ADE 1.4.x and up also made the following changes:
- URL schemes have been updated to OpenAPI Specification OAS3.1
- JSON Schema semantics have been updated correspondingly to use JSON Schema 2020-12
- In icarResource, meta SHOULD be considered required, and in icarMetaDataType, the source and sourceId SHOULD both be considered required.
- Some manufacturer-specific attributes of icarReproHeatEventResource are deprecated.
- In icarResourceReferenceType, the attributes @context, @id, and @type are deprecated. Use the new attributes instead.

We identified this when specifying the [generic data exchange API](https://github.com/adewg/ICAR/blob/ADE-1/docs/generic-data-exchange-api.md) where being able to de-serialise objects correctly is essential. We found that some other code generators also did not correctly generate code with our previous specification of discriminators.
If you have implemented ADE 1.2.x, you will find that `ResourceType` is now fully specified as a string and (mandatory) discriminator, which was necessary to support deserialisation of objects from JSON into generated code.

## Corrections made in ADE 1.3.1 and ADE 1.3.2 patch releases
* `icarWithdrawalEventResource` inherited from the incorrect event type (#347)
* `icarStatisticsResource` had separate arrays for groups and statistics. The statistics were intended to be nested inside the groups (#353)
* In `icarConsignmentType` `originAddress` and `destinationAddress` were originally strings, and in ADE 1.3 these were extended with `"anyOf"` to also support a schema.org `PostalAddress`. However, this broke Java implementations. We have reverted these to strings, marked them as deprecated for future releases, and added `originPostalAddress` and `destinationPostalAddress` for structured addresses. If you have started implementing 1.3, you should regenerate and check your code for 1.3.2.

## Changes made in ADE 1.3.x:
* The discriminator `resourceType` is defined as a string property in `icarResource.json`. It is therefore included in all resources, including events, using "allOf".
* `resourceType` is a required field as is required by the OpenAPI specification.
* `eventType` has been removed from events as it will not function properly as a discriminator.
* `identifierType` has been removed from `icarIdentifierType.json`. Identifiers are always embedded in known contexts in JSON objects - there is never a need to make a decision when de-serialising these. Further, the only reason why identifiers are subclassed is to assist implementers to understand, find, or define the correct schemes in the [well-known identifier schemes](https://github.com/adewg/ICAR/blob/ADE-1/well-known/identifier-types.md).

## Changes to your implementations from ADE 1.2.x
* Regenerate your code using **openapi-generator 6.x** or later
* Don't use `eventType` or `identifierType` in your implementations
* **Let your data interchange partners know.** Most implementations prior to 1.3.x won't actually need to use the discriminator because the API context defines the type of data to be de-serialised. However, having `resourceType` as a required field may cause problems. We note that as a discriminator in the base class, it was technically always required by the OpenAPI spec, but this may not have been noted and implemented.
* This is also a reminder to continue using the [tolerant reader pattern](https://github.com/adewg/ICAR/wiki/Design-Principles#user-content-fault-tolerance-and-extensibility) described in the ADE design principles, which helps insulate from many of these changes.
Loading