Merge from Develop branch to ADE-1 branch for point release 1.5.1.

CHANGELOG.md

@@ -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:**
 
@@ -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))

ReleaseNotes.md

@@ -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.

enums/icarDeathDisposalMethodType.json

@@ -1,12 +1,14 @@
 {
-  "description": "Enumeration for disposal method. Not specified in previous ADE data dictionary, required by some schemes.",
+  "description": "Enumeration for disposal method. Not specified in previous ADE data dictionary, required by some schemes.\n OnPremise- burial or leaving carcass on site.\n ApprovedService- collected for disposal by an approved service provider.\n Consumption- by wild animals, people on farm, or working dogs",
 
   "type": "string",
 
   "enum": [
     "ApprovedService",
     "Consumption",
     "OnPremise",
-    "Other"
+    "Other",
+    "Cremation",
+    "Research"
   ]
 }

enums/icarProductionPurposeType.json

@@ -1,11 +1,15 @@
 {
-  "description": "Defines the primary product that for which this animal is bred or kept.\\nIf animals are kept for breeding or live trade (sale), specify the end purpose of that breeding/trade.\\n\n - Meat corresponds to UNSPC 50111500 Minimally processed meat and poultry products\\n - Milk corresponds to UNSPC 50203200 Raw milk products from live animals\\n - Wool corresponds to UNSPC 11131506 Unprocessed wool",
+  "description": "Defines the primary product that for which this animal is bred or kept.\\nIf animals are kept for breeding or live trade (sale), specify the end purpose of that breeding/trade.\\n\n - Meat corresponds to UNSPC 50111500 Minimally processed meat and poultry products\\n - Milk corresponds to UNSPC 50203200 Raw milk products from live animals\\n - Wool corresponds to UNSPC 11131506 Unprocessed wool.\\n Suckler - used to breastfeed calves.\\n Breeding - bulls used for semen production.\\n",
 
   "type": "string",
 
   "enum": [
     "Meat",
     "Milk",
-    "Wool"
+    "Wool",
+    "Suckler",
+    "Breeding",
+    "Research",
+    "Pet"
   ]
 }

resources/icarAnimalBaseResource.json

@@ -0,0 +1,81 @@
+{
+  "description": "Base schema containing all common properties for animal and progeny resources.",
+
+  "allOf": [{
+      "$ref": "../resources/icarResource.json"
+    },
+    {
+      "type": "object",
+
+      "required": [
+        "specie",
+        "gender"
+      ],
+
+      "properties": {        
+        "alternativeIdentifiers": {
+          "type": "array",
+          "items": {
+            "$ref": "../types/icarAnimalIdentifierType.json"
+          },
+          "description": "Alternative identifiers for the animal. Here, also temporary identifiers, e.g. transponders or animal numbers, can be listed."
+        },
+        "specie": {
+          "$ref": "../enums/icarAnimalSpecieType.json",
+          "description": "Species of the animal."
+        },
+        "gender": {
+          "$ref": "../enums/icarAnimalGenderType.json",
+          "description": "Gender of the animal."
+        },
+        "birthDate": {
+          "$ref": "../types/icarDateTimeType.json",
+          "description": "RFC3339 UTC date/time of birth (see https://ijmacd.github.io/rfc3339-iso8601/ for how to use)."
+        },
+        "primaryBreed": {
+          "$ref": "../types/icarBreedIdentifierType.json",
+          "description": "ICAR Breed code for the animal."
+        },
+        "breedFractions": {
+          "$ref": "../types/icarBreedFractionsType.json",
+          "description": "Breed fractions for the animal."
+        },
+        "coatColor": {
+          "type": "string",
+          "description": "Colour of the animal's coat, using the conventions for that breed."
+        },
+        "coatColorIdentifier": {
+          "$ref": "../types/icarCoatColorIdentifierType.json",
+          "description": "Colour of the animal's coat using a national or breed-defined scheme and identifier combination."
+        },
+        "managementTag": {
+          "type": "string",
+          "description": "The identifier used by the farmer in day to day operations. In many cases this could be the animal number."
+        },
+        "name": {
+          "type": "string",
+          "description": "Name given by the farmer for this animal."
+        },
+        "officialName": {
+          "type": "string",
+          "description": "Official herdbook name."
+        },
+        "productionPurpose": {
+          "$ref": "../enums/icarProductionPurposeType.json",
+          "description": "Primary production purpose for which animals are bred."
+        },
+        "parentage": {
+          "type": "array",
+          "description": "Parents of the animal.  The array can handle multiple generations by specifying the parent of a parent.",
+          "items": {
+            "$ref": "../types/icarParentageType.json"
+          }
+        },
+        "healthStatus": {
+          "$ref": "../enums/icarAnimalHealthStatusType.json",
+          "description": "Health status of the animal (such as Healthy, Suspicious, Ill, InTreatment, ToBeCulled)."
+        }
+      }
+    }
+  ]
+}

resources/icarAnimalCoreResource.json

@@ -2,95 +2,31 @@
   "description": "Core schema for representing animal",
 
   "allOf": [{
-      "$ref": "../resources/icarResource.json"
+      "$ref": "../resources/icarAnimalBaseResource.json"
     },
     {
       "type": "object",
 
       "required": [
-        "identifier",
-        "specie",
-        "gender"
+        "identifier"
       ],
 
       "properties": {
         "identifier": {
           "$ref": "../types/icarAnimalIdentifierType.json",
           "description": "Unique animal scheme and identifier combination."
         },
-        "alternativeIdentifiers": {
-          "type": "array",
-          "items": {
-            "$ref": "../types/icarAnimalIdentifierType.json"
-          },
-          "description": "Alternative identifiers for the animal. Here, also temporary identifiers, e.g. transponders or animal numbers, can be listed."
-        },
-        "specie": {
-          "$ref": "../enums/icarAnimalSpecieType.json",
-          "description": "Species of the animal."
-        },
-        "gender": {
-          "$ref": "../enums/icarAnimalGenderType.json",
-          "description": "Gender of the animal."
-        },
-        "birthDate": {
-          "$ref": "../types/icarDateTimeType.json",
-          "description": "RFC3339 UTC date/time of birth (see https://ijmacd.github.io/rfc3339-iso8601/ for how to use)."
-        },
-        "primaryBreed": {
-          "$ref": "../types/icarBreedIdentifierType.json",
-          "description": "ICAR Breed code for the animal."
-        },
-        "breedFractions": {
-          "$ref": "../types/icarBreedFractionsType.json",
-          "description": "Breed fractions for the animal."
-        },
-        "coatColor": {
-          "type": "string",
-          "description": "Colour of the animal's coat, using the conventions for that breed."
-        },
-        "coatColorIdentifier": {
-          "$ref": "../types/icarCoatColorIdentifierType.json",
-          "description": "Colour of the animal's coat using a national or breed-defined scheme and identifier combination."
-        },
-        "managementTag": {
-          "type": "string",
-          "description": "The identifier used by the farmer in day to day operations. In many cases this could be the animal number."
-        },
-        "name": {
-          "type": "string",
-          "description": "Name given by the farmer for this animal."
-        },
-        "officialName": {
-          "type": "string",
-          "description": "Official herdbook name."
-        },
-        "productionPurpose": {
-          "$ref": "../enums/icarProductionPurposeType.json",
-          "description": "Primary production purpose for which animals are bred."
-        },
         "status": {
           "$ref": "../enums/icarAnimalStatusType.json",
           "description": "On-farm status of the animal (such as alive, dead, off-farm)."
         },
-        "reproductionStatus": {
-          "$ref": "../enums/icarAnimalReproductionStatusType.json",
-          "description": "Reproduction status of the animal."
-        },
         "lactationStatus": {
           "$ref": "../enums/icarAnimalLactationStatusType.json",
           "description": "Lactation status of the animal."
-        },
-        "parentage": {
-          "type": "array",
-          "description": "Parents of the animal.  The array can handle multiple generations by specifying the parent of a parent.",
-          "items": {
-            "$ref": "../types/icarParentageType.json"
-          }
-        },
-        "healthStatus": {
-          "$ref": "../enums/icarAnimalHealthStatusType.json",
-          "description": "Health status of the animal (such as Healthy, Suspicious, Ill, InTreatment, ToBeCulled)."
+        },        
+        "reproductionStatus": {
+          "$ref": "../enums/icarAnimalReproductionStatusType.json",
+          "description": "Reproduction status of the animal."
         }
       }
     }

resources/icarProgenyDetailsResource.json

@@ -3,57 +3,15 @@
 
   "allOf": [
     {
-      "$ref": "../resources/icarResource.json"
+      "$ref": "../resources/icarAnimalBaseResource.json"
     },
-
     {
-      "type": "object",
-      "required": [
-        "specie",
-        "gender"
-      ],
+      "type": "object",      
 
-      "properties": {
+      "properties": {       
         "identifier": {
-          "description": "Unique animal scheme and identifier combination.",
-          "anyOf": [
-              {"type": "null"},
-              {"$ref": "../types/icarAnimalIdentifierType.json"}
-          ]
-        },
-        "alternativeIdentifiers": {
-          "anyOf": [
-              {"type": "null"},
-              {"type": "array",
-                  "items": {
-                      "$ref": "../types/icarAnimalIdentifierType.json"
-                  }
-              }  
-          ],
-          "description": "Alternative identifiers for the animal. Here, also temporary identifiers, e.g. transponders or animal numbers, can be listed."
-        },
-        "specie": {
-          "$ref": "../enums/icarAnimalSpecieType.json",
-          "description": "Species of the animal."
-        },
-        "gender": {
-          "$ref": "../enums/icarAnimalGenderType.json",
-          "description": "Gender of the animal."
-        },
-        "managementTag": {
-          "anyOf": [
-              {"type": "null"},
-              {"type": "string"}
-          ],
-          "description": "The identifier used by the farmer in day to day operations. In many cases this could be the animal number."
-        },
-        "name": {
-          "type": "string",
-          "description": "Name given by the farmer for this animal."
-        },
-        "officialName": {
-          "type": "string",
-          "description": "Official herdbook name."
+          "$ref": "../types/icarAnimalIdentifierType.json",
+          "description": "Unique animal scheme and identifier combination."
         },
         "taggingDate": {
           "description": "Progeny tagging date in RFC3339 UTC (see https://ijmacd.github.io/rfc3339-iso8601/ for format guidance).",