In Section 4.17 of the ICAR Data Dictionary:

https://www.icar.org/Guidelines/15-Appendix-A-Data-Dictionary.pdf

the quarter ids are listed as:

• LF Left front
• RF Right front
• LR Left rear
• RR Right rear

However, the enum https://github.com/adewg/ICAR/blob/ADE-1/types/icarQuarterMilkingType.json lists:

• "LF",
• "RF",
• "LB",
• "RB"

Maybe one of the documents should be changed :)

"Ecography" should be "Echography". I'll add a pull request.

If links #19 are only optional, do we need a standard for Pagination?

There is a need for automated discovery of urls. Parties that connect to multiple servers should not rely on client side synthesizing urls. Instead, the server should provide links in the messages to related resources.

The workgroup should choose such a standard (e.g. JSON-ld or hateoas or something else).

As long as we don’t have committed to this, we need temporary workarounds like example url schemes to document the standard.

For data exchange with a milk recording organization we need to be able to determine the current status of animals to report some data about them. In the current API there is no information about the animal status. I could imagine that one could derive the animal status from looking at the last animal actions, however, this seems quite cumbersome.

I'd propose to add an additional status to the AnimalCoreResource with enum values that reflect the current status. Possible enum values:

• other
• fresh
• early
• abort
• ready
• open
• inseminated
• pregnant
• pregnant2
• dry
• lead
• tbcull

We could use tags to indicate which messages are proposed/draft/final in the (example) url scheme. This way, it would be easier to see the current state of the work.
Downside is that it will only be visible with an url scheme and we may want to use tags for grouping messages functionally.

Currently the $ref's are absolute URL's pointing to the adewg's master branch. This makes it hard to test and verify in other repositories.

We should check if we can simply make them relative to the (example) url scheme.

$ref: 'https://raw.githubusercontent.com/alamers/ICAR/convert-to-v3/Release%20Candidate%20Messages/JoinDataMilkSample.json'

from ln587 in https://github.com/adewg/ICAR/blob/master/Release%20Candidate%20Messages/icar-ade-openapispec.yaml

404 error reference to JoinDataMilkSample.json

During the process of implementing a data exchange using the ICAR format we recognized that animals cannot be assigned to groups right now. In our use case animals can be assigned to specific groups to define how they are fed, milked and in which barn area they are located.

A possible integration of that into the ICAR standard could be:

• add a new resource "animal group" that has the attributes "type" as an enumerated value (e.g. "FEEDING", "MILKING", "BARN") and "name" which describes the group as a string value
• allow for CRUD on the new resource type
• add a new attribute "assigned groups" to the animal that consists of a list of "animal groups"

Standards for graph data from Nedap, SCR, ....

GET /locations/{location-scheme}/{location-id}/bcs

• id: unique id of the event resource
• event date: date of the score
• animal identifier: the scheme and the identifier for the animal
• location identifier: the scheme and the identifier for the location
• score: score value
• method: scoring method [manual/visual, automatic] (or if extended [visual, ultrasonic, camera])
• device: equipment/device used for scoring
• meta data

While implementing the ICAR interface, we came across the issue that we need to know location schemata and ids beforehand, especially if we want to allow the user to choose a specific location.

We will now implement an endpoint where we will deliver all available schema/id combinations for locations together with a "name" (the same that we use in our application) so that the user can identify the locations in an external tool.

However, this seems to be a more general issue. Getting information about the supported schemata for e.g. location ids, animal ids etc. for automatic data exchange whould be very helpful.

My proposal would be to support at least these features:

• retrieve the available schemata for a specific identifier type
• retrieve the available IDs for a specific schema, but provide a descriptive name (or similar information) for that, too

For locations (as these are a very central aspect of the interface) I'd even propose to have at least a list of available schema/id combinations. Also possible would be a list of locations, each identified by a name, and each having a collection of alternative identifiers (similar to what animals currently have).

During implementation of milk sampling information we came across this type:

icarValidSampleFillingIndicatorType.json

The enum values are just "0", "1" and "2" and the file references the "ICAR_ValidSampleFillingIndicatorCode list" which I couldn't find anywhere.

I'd propose to use more descriptive enum values in a future version of the standard (as this would be a breaking change). Unit then, putting information about the existing enum values into the description of the type would be very helpful.

As we are approaching version 1.0, we should look at the documentation as well. This ticket is mostly a call for missing documentation: what do you think we should add to the docs?

This is version 1.0 (or pre-1.0) but eventually there will be later versions, and clients and servers may need to distinguish. It would be wise now to recommend a versioning scheme. There are two components to this:

1. Version representation - most APIs are now using SemVer or equivalent (major + minor, breaking changes only in major). Its likely we could do this or indeed only worry about major.

2. Versioning strategy - there are four common methods:
   a. Include version in the URL specification (challenging initially if we are not insisting on a URL format, and forces servers to implement multiple API URLs).
   b. Include version in the URL Query String (?version=1)? Not often used.
   c. Use custom version headers ("accepts-version: 1.0"). Means testing with a browser is extra work.
   d. Use content negotiation (“Accept: application/vnd.xm.device+json; version=1” ). Elegant but much harder to test APIs with a browser.

For instance, see https://restfulapi.net/versioning/

In our use case we want to deliver data to a milk recording organization (MRO) by retrieving the data from our system via an ICAR interface and converting the data into an ADIS file that can be sent to the MRO. To be able to send the data, the user needs to know:

1. When was the end of the previous test day that was executed (because some MROs require/offer the user to send all milk visits since the last test day)
2. What was the start/end date/time of the current test day

With that information, the relevant data can be collected through the ICAR milk visits API.

The data about the test days is available in our system, however, there is no resource type in the ICAR interface that allows us to transfer the values.

My proposal would be to provide a list of test day resources via the ICAR interface. As a follow-up improvement, the "TestDayResult" resource could even reference to one of that resources so they can easily be related.

Should we include a standard for authentication?

The inclusion of both scheme/id and name in the schema for Breeding values was noticed when discussing issue: #89

Questions raised during discussion:

1. Is the duplication an aide or a hindrance to the usability of the standard?
2. Is the Name essentially a Default name? e.g. in the absence of a i18n/l10n/Locale resource to resolve the name of an entity with a given scheme/id for the Locale then the default name would be displayed).
3. Should we adopt a method for making i18n/l10n part of the APIs?

Ideas for discussion (not exhaustive)

• Guidance to producers and consumers of APIs built to the standard
• Adoption of a i18n/l10n mechanism withing the ADE API.
• ...?

Another example:
Animal Health Treatments - Diagnosis (Diagnosis Code and Name)

in our LICENSE file, there is still a placeholder for the copyright holder:
Copyright [yyyy] [name of copyright owner]

I guess this should read
Copyright 2020 ICAR.

Also, it is advised to have a copyright notice in each and every file... I guess that is a bit too much?

We have a need to transfer Conformation Scores (recorded by inspectors, following the ICAR guidelines http://www.icar.org/Guidelines/05-Conformation-Recording.pdf) for a project in New Zealand.

I propose to document the proposed messages in this Issue for review and approval, perhaps based on the work done on scores by the Integrity Systems group in Australia as well as the ICAR Guidelines.

Should enum array values be normalized to follow same naming patter?
Some enums uses whitespace in naming and other not (also some uses dots or other characters):

Example icarReproInseminationType vs icarArrivalReasonType:

InseminationType uses combined names for enum values ("NaturalService", "RunWithBull") and ArrivalReasonType uses names with whitespace ("Internal Transfer", "Sale Return", "Stud Service Return"). Same applies for icarRecommendationType, icarDepartureKindType etc.

I known this is not a big issue, but shoud it still be alligned with common naming convention? :)

• animal number
• location/herd
• customer
• ...

dummy messages in github so they can be accessed

When I generate java code with java -jar openapi-generator-cli-4.2.3.jar generate -g jaxrs-resteasy -i ../src/main/resources/git-icar/url-schemes/exampleUrlScheme.json -o output the resulting code does not compile.

The Collections (i.e. IcarAnimalCoreCollection) extends IcarResourceCollection that has a member of type List, but i.e. has the same field member of type List.

This does not compile

 .../target/generated-sources/openapi/src/main/java/org/openapitools/model/IcarAnimalCoreCollection.java:[54,15]
 name clash: setMember(java.util.List<org.openapitools.model.IcarAnimalCoreResource>) in org.openapitools.model.IcarAnimalCoreCollection 
and setMember(java.util.List<java.lang.Object>) in org.openapitools.model.IcarResourceCollection have the same erasure, yet neither overrides the other

Do I missed a parameter? Is it a problem of the OpenAPI-Generator? What tool do you use to generate compilable java code (> Java 8)?

I want to start working on a proposal for breeding values of an animal

We are using right now :

animalId : unique identification code of an animal - identifier and scheme
base : base string breeding value calculation
Enum:[ GES_BLACK_AND_WHITE, GES_RED_AND_WHITE, GES_LOCAL, GES_BELGIAN_BLUE,
US_NL_COMBINED, US_HOLSTEIN, US_JERSEY, UNKNOWN ]
maybe we can also use a scheme and id for the base - the enum above would be the scheme used by CRV
breedingValues - array of breedingValue
-- scheme/id : the scheme and the id of the breeding value
-- name : name of the breeding value.
-- calculationType: mathematical method used
Enum:[ breeding value, parent average, parent average derived, MRY-DN, Genomic breeding
value, interbull breeding value, converted breeding value, Sire-MGS average, Sire-country
average, Country average, unknown ]
-- value: integer numeric value of an object
-- reliability: number statistical reliability of the breeding value

@cookeac @erwinspeybroeck @alamers

"location" is not set as required for event resources nor for base core resource (icarEventCoreResource). Is this correct or should location information be always mandatory for events?

Another thing is that in some events required undefined fields:

• icarMovementArrivalEventResource.json - requirements refers to nonexisting field "originLocation"
• icarMovementDepartureEventResource.json.json - requirements refers to nonexisting field "destinationLocation"

Resource collection messages should be added for all types of event resources (as now we have for icarWeightEventResource - icarWeightEventCollection). This could be assigned on me if no one working on that already.

examples:
icarReproInseminationEventResource -> icarReproInseminationEventCollection
icarAnimalCoreResource -> icarAnimalCoreCollection
etc.

When working with the Integrity Systems Company group in Australia, we noted there is sometimes a need to record a change of ownership of animals without a movement.
Examples include when animals are purchased or financed on farm, but left to graze there, or when animals change ownership at an auction, but are not yet delivered.

The message has been documented here https://github.com/integritysystemscompany/animal_schema and I propose to copy the documentation here for review, then create a pull request when ICAR members are happy.

@cookeac @erwinspeybroeck @alamers

"location" is not set as required for event resources nor for base core resource (icarEventCoreResource). Is this correct or should location information be always mandatory for events?

Another thing is that in some events required undefined fields:

• icarMovementArrivalEventResource.json - requirements refers to nonexisting field "originLocation"
• icarMovementDepartureEventResource.json.json - requirements refers to nonexisting field "destinationLocation"

Both "originLocation" and "destinationLocation" are part of icarConsignmentType and requirement should be declared there I suppose.

At our working group meeting on 25 July we discussed how a client GETting data from another device or a server can know if it has consumed all data, especially given that clocks of devices might not be perfectly synchronised.

I am creating this issue to capture the discussion so that it is documented for future contributors. I will post the emails between us as comments on the thread so contributors have the narrative that supports the decision we made at the meeting.

Proposed properties:

• icarEventCoreResource.json unique id, aniaml id, location id, event date time
• HeatDetectionMethod enumeration : C=Chemical, V=Visual, P=Pedometer, O= Other
• certainty enumeration : in heat, suspect
• expirationDateTime timestamp on which the heat event expires
• DeviceSpecific
• • Visual
• • • heatSign array : enumeration : Slime, Clear slime, Interested in other animals, Stands under, Bawling, Blood
• • • heatIntensity : enumeration : Very weak, Weak, Normal, Strong, Very strong
• • ScrSenseTime
• • • BreedingWindow : number of hours to AI
• • • heatIndex : indication of the certainty of the heat
• • NedapCowControl
• • • indicationExpirationDateTime : timestamp the indication expires
• • • indicationCertainty
• • • heatChance
• device Identify the device used. Optional
  Use the object as defined for weight:
  Derives from icarResourceReferenceType, so that it can have a link to the device resource. Optional
  deviceType is a device type registered with the database proposed by the Sensor Working Group. This could be a UUID but we prefer a meaningful string.
  serial is an Optional unique serial number of the device itself (or a network ID, if networked?)

As the pull request from @Jongmassey has shown, it is easy for errors to slip in. Right now, we more or less have a set of static files and rely on manual checking.

We should have an environment where we can build the documentation and also perform automated quality checks. For example, running
docker run wework/speccy lint https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml
(on a workstation with Docker installed), will give detailed feedback on things that need improving.

I was doing some testing from a Java perspective: downloading a generated Java client from Swagger UI (Swagger codegen) based on the example url scheme. (I think this would be the most common use case, either generating it from this repo, or from an implementing party directly, as this also generates the transport client.)

I noticed that the code generated is making use of the tags (now: release-candidate-milk, ...).
This then leads to API classes like in the enclosed image: "ReleaseCandidateMilkApi". Thus, the naming of these tags is important, not just for documentation. I suggest to follow the same version rules as for the url scheme and use "ade1-milk", "ade1-registration", ...

Work through with the wider ADE working group the open source or creative commons licence to be used. Make use of https://opensource.org/licenses decision tree and/or https://creativecommons.org/choose/

We can use RN generation tool (for example github-changelog-generator) or do it manually while creating release. Still it is important to have all changes and related issues been marked into PR/commits (refer to guide)

Should icarAnimalIdentifierType and icarLocationIdentifierType be corrected to implement "allOf" inheritance instead of a direct reference to icarIdentifierType sub message?

{
        "$ref": "icarIdentifierType.json",
        "description": "Identifies an animal using a scheme and ID."
}

into

{
    "description": "Identifies an animal using a scheme and ID.",

    "type": "object",

    "allOf": [{
        "$ref": "icarIdentifierType.json"
    }]
}

@cookeac @alamers @erwinspeybroeck

In the icarDateTimeType and also in the example URLs we use the format date-time specified in the JSON schema specification for date time properties.

As far as I remember from our discussions we always want to exchange UTC time stamps. So I'd assume that it's sufficient to just exchange the date and the time component and not the offset.

I didn't check possible ways to fix this, but I guess there is a way to define custom formats (I'll check this tomorrow). Or is that format intended?

• entity model
• process to use the standard from server point of view
• process to use the standard from client point of view
• background of the standard (ICAR ADE)
• how can you contribute?
• commercial and proprietary use
• ...

I'm talking with Lely about what information they have available in T4C about feed intake, and want to start with that to create a definition

previous work :

Information from Lely - existing API structure

A. Lely has two types of feeding

1. Feeding on fences distrubuted by vector device (mainly roughage but can also include concentrate/mineral in a ration)
2. Feeding at astronaut device (concentrate/mineral)
   B. Corresponsing API Methods

There is the following method to get vector feeding info in API
HttpGet --> feedoverview
public class FeedOverviewParam
{
public int? LocationId;
public DateTime? Date;
public int? NrOfAnimals;
public int? KgMilk;
public int DryMatterTotal;
public int ProductTotal;
public int TotalFeedCost;
public List FeedTypes = new List(32);
}
public class VectorFeedTypeParam
{
public int FeedId;
public int TotalProduct;
public int TotalDryMatter;
public decimal FeedCost;
}
This method gives total intake (ProductTotal/gram) daily for the number of animals on a location.
It is also possible to get intake (TotalProduct/gram) feed based on a location.
2.
There is the following method to get astronaut feeding info in API
HttpGet --> feedvisits
public class FeedVisitParam
{
public int DeviceAddress;
public string LifeNumber;
public DateTime FeedDate;
public string FeedName;
public int? NumberOfFeedType;
public int? Credit;
public int? Intake;
}
This method gives total intake (Intake/gram) daily for an animal on a astronaut device for each feedtype.

Is there any real need to have resource collection (icarResourceCollection.jso) be inherited from icarResource base structure? As I understand MetaData is single resource related entity, but not collection of recources.

provide link to the swagger definition - generated readable documentation

Proposed properties:

• id : unique id on the farm (farmlevel)
• serial : an Optional unique serial number of the device itself (or a network ID, e.g. MAC-address, or unique IP-address)
• name : device name - set by farmer
• description : device description - set by farmer
• location : identifier + scheme of the location where the device is located
• software version : version of the software on the device
• hardware version : version of the hardware of the device
• isActive : is the device active at this moment?
• supportedMessages : array of enumerated messages
• manufacturer subresource
• • device type : a device type registered with the database proposed by the Sensor Working Group. This could be a UUID but we prefer a meaningful string.
• • name : name of the manufacturer
• • id : unique id of the manufacturer - domain name/url --> lely.com, …
• • device name : name of the device given by the manufacturer
• • device  description : description of the device
• • device configuration : configuration of the device

Discussed during the meeting on 22 November 2019.

Proposed properties:

• weight The weight of the animal using the Units specified (kilograms if unspecified). Number.
• method The method used to observe the weight. See the list below. (Loadcell if not specified). Optional
• units The units for the weight using UN/CEFACT abbreviations. Kilograms (KGM) if not specified. Enumeration. Optional
• resolution The selected resolution (minimum detectable change) of the device. For instance, 0.5, 2, 5, 10kg. Number. Optional
• device Identify the device used. Optional

1. I propose that we define an enumeration of common UN/CEFACT mass units so people know what may be specified for units.
2. We should define an enumeration for method including:

• Loadcell - weighed using a loadcell or loadbars
• Girth - measured using a girth tape
• Assessed - visual assessment by a person
• Walkover - using walkover weighing or a similar real-time averaging technique
• Predicted - predicted weight on a date using a growth algorithm or similar
• Imaged - predicted using infra-red, camera, or 3D imaging
• GroupAverage - an average applied when a pen of animals are weighed together.

3. I propose we define an object for device that:

• Derives from icarResourceReferenceType, so that it can have a link to the device resource. Optional
• deviceType is a device type registered with the database proposed by the Sensor Working Group. This could be a UUID but we prefer a meaningful string.
• serial is an Optional unique serial number of the device itself (or a network ID, if networked?)

If this is agreed I will define and submit a PR for:

• icarWeightEventResource.json
• uncefactMassUnitsType.json
• icarWeightMethodType.json
• icarWeightEventCollection.json (a paged collection of weights)

@alamers @erwinspeybroeck @cookeac
Just asking for your opinion if you see a need for splitting different types - complex vs code-based types (enums) into separate folders for easier navigation inside code?

example structure:

-types

• icarParentageType.json
• icarSireRecommendationType.json
• icarResourceCollection.json
• etc.

-enums

• icarReproHeatSignType.json
• icarReproHeatDetectionMethodType.json
• etc.

icarAnimalCoreResource.json
icarEventCoreResource.json
icarReproHeatEventResource.json
etc.

The Integrity Systems (Australia) group of companies worked out a good set of messages for animal health diagnosis, treatment plan, and treatment events based on Jon Massey's Bristol University specification, plus feedback from ICAR ADE members and their own experiences.
I will document this under this Issue and organise a pull request when we are happy.

We have already made decisions about inheritance. We now need to implement these in the JSON Schema so that other events and resources can use the base classes.

Define an example url scheme (e.g. the JoinData scheme) to allow for exploring the messages.

Since we havent decided on a linking method (json-ld or hateoas or something else), and we dont have the recommended url scheme as well, we need at least an example scheme to be able to generate documentation.

GET /locations/{location-scheme}/{location-id}/lactations

• id : unique id of the lactation resource

• animal identifier : the scheme and the idnetifier for the animal with this lactation

• location identifier : the scheme and the identifier for the location

• start date : start date of the lactations

• end date : end date of the lactation

• parity : parity of the lactation

• lactation length

• milkWeight : value + unit code

• fatWeight : value + unit code

• proteinWeight : value + unit code

• lactosisWeight : value + unit code

• lastTestDay : Date of the last test day in this lactation

• lactationResultCode : Official 100 days yield, Official 200 days yield, Official 305 days yields, Normal lactation

• icarMilkRecordingMethod--> subresource (we decided to keep them all)
  -- milkRecordingProtocol : Protocol A: Official MRO representative, Protocol B: Herd owner or its nominee, Protocol C: Official MRO representative or herd owner or its nominee
  -- milkRecordingScheme : all milkings at testday, all milkings in period, one milking at testday
  -- milkingsPerDay : 1 per day, 2, 3, 4, Continuous Milkings (e.g. robotic milking)
  -- milkSamplingScheme : proportional size sampling of all milkings, constant size sampling of all milkings, sampling of one milking at alternating moments (Alternative Sampling), sampling of one milking at the same moments (Corrected Sampling), sampling of one milking at changing moments (AMS), sampling of multiple milkings at changing moments (AMS)
  -- samplingMoment : Composite, Morning, Evening
  -- recordingInterval : 1 week, 2 weeks, 3, 4,5,6,7,8,9, daily --> replace by days
  -- certified : true = it is ICAR certified, false = not ICAR certified
  -- milkingType : Official milk result supplied by milk recording organisation, Measure by ICAR approved equipment, Measure by not approved equipment

• meta data

What about 305 lactation? Seperate API or include in the lactation API?
We decided to have no seperate API for this.

Parameters : indicate current or all when requesting lactation(s) of an animal

NOT IN the standard (index - ranking : comparative number stating the value of the cow within a location)
NOT IN somaticCellCountAverage and ueraAverage, ... ?? TO DECIDE

As defined in the principles, we would like to separate out the url scheme from the messages themselves in the standard. We would however like to have a recommended url scheme to make it easier for all parties.

There is a separate ticket for creating an example scheme as a temporary solution, but that (or another proposal) should evolve into a recommended url scheme as well.