ICAR ADE Technical Group Meeting 22 November 2019

Attendees: Andrew Cooke, Erwin Speybroeck, Bert van’t Land, Beate Massen-Francke, Andreas Schultz, Kor Odinga, Anton Hokkonen. Apologies: Conny Graumans, Arjan Lamers, David Bleloch, John Murphy (and his nominee, Marco Lombardo), Sven Schierenbeck, Henning Winkelmann

0. Agenda:

• Update on validation and message schemas
• Naming best practices (question from Anton)
• Collections (question and suggestions from Craig and Andrew)
• Health Treatments (attachment from Andrew)
• ICAR sensor group feedback
• Milking visit yield only (limit the characteristics returned?) (Erwin)
• Mating recommendation (Erwin)
• Weights (Erwin)

1. Update on Validation and Message Schemas

• Issue #27 identified we wanted to automate quality checks
• Anton had suggested using a GitHub Action to implement Speccy validation
• Andrew has implemented this and the code has been fixed to comply. Verbose mode was used to make it easier to find out what causes an error.
• We should investigate use of other libraries for the future, for instance Spotlight.io.
• @Anton will do more research on this.

2. Naming best practices

• Any resource that might be accessed by an API should have “Resource” in the file name, and other attributes should have “Type” in the file name.
• Anything that is an event observed on should also have “Event” in the file name.
• icarMetaDataResource.json should be renamed to icarMetaDataType.json
• icarMovementArrivalResource.json should be renamed to icarMovementArrivalEventResource.json.

3. Collections

• Craig and Andrew had looked into collections, investigating HAL, JSON-API, JSON-LD+Hydra, Collections+JSON, JSON Hyper Schema.
• Andrew had recommended JSON-LD+Hydra and JSON Hyper Schema as these are W3C draft standards.
• With the Speccy validator, including “links” (JSON Hyper Schema) with “$ref” does not validate, so this needs to be addressed.
• Craig is happy with the proposed fields in the files.
• Andrew has submitted this as PR #48, which Erwin has now merged.
• We noted that collection types for the various resources will now need to be defined. These could then be referenced in the Swagger examples (which currently define array resources in Swagger).

4. Health Treatments

• Andrew had been through the JSON Schema developed by Jon Massey based on the document reviewed by this group some months ago.
• We considered four scenarios:

1. A single treatment by itself
2. A course of treatments with start and finish date and total
3. A course with an array of treatments
4. A treatment that (by reference) belongs to a course

• Andrew’s proposed solution was a single treatment event that has:

1. An optional course with summary information
2. An optional array of doses.

• We noted that there are treatments without medicines – for instance hoof trimming, surgery, massage, etc.
• We noted that some treatments may have more than one medicine. A course or a treatment might need to have multiple medicines.
• A treatment might address more than one diagnosis.
• The JoinData “Treatment Plan” contains an array of treatments and an array of diagnoses. Erwin demonstrated what this looked like using Swagger.
• We discussed whether to refer to the ICAR catalogue of diagnoses, or whether to have a text field so that countries could use their own existing catalogues.
• Some participants do use the ICAR catalogue, although though a “mapping” or “key bridge” to standardise local diagnoses.
• Agreed to investigate potential use of at least the “top level” of the ICAR catalogue, perhaps as well as local text and support for deeper use of the catalogue.
• Discussed “Units” of measurement for doses.

1. Use the UN/CEFACT codes which are not all immediately obvious
2. Point people to the UN/CEFACT code list

5. ICAR Sensor Working Group Discussion

• This group would like to create a database of devices which include manufacturer, device, hardware version, software version, certification status.
• They propose addition of a UUID (universally unique ID) that represents each unique device type to each event that could be recorded by a sensor.
• We were concerned about confusion between a “device class ID” (for device type/version) and “device network ID” (unique individual device).
• We agreed to propose to the Sensor Working Group a more readable device class ID that contains manufacturer, device, hardware and software versions in a way that is similar to the USB specification. This will need more investigation.

6. Milking Visit Yield Only

• Lely wished to split the milking visit and publicly provide an API to a simple Milking Visit with a Yield, or (for controlled use) an API that returns a full Milking Visit with all characteristics.
• We noted that this could be done with the current data model by the server assessing the permissions of the caller and returning either the Milking Visit or the Milking visit with characteristics filled in. This is not possible with JoinData permissions.
• We proposed keeping the data structured unchanged (characteristics and quarters are already optional) and defining an additional API that only promises to return the milking visit without quarters and characteristics. The name of this API should be “Milking Visit Limited” or “Milking Visit Simple”.

7. Units for Milking Visit characteristics

• At our 8 November meeting we had agreed:

1. Define the normal expected units for each characteristic (e.g. FAT) in the documentation.
2. Also have a “Units” text field for each characteristic so that non-standard units could be specified, or default units could be listed for clarity (optional). The “Units” field would be optional.
3. Use UN/CEFACT units in the “Units” field. These are not always clear (they are 3 character codes), so their meaning will need to be documented as well.
4. One unit = “IU/l” or “International Units per litre” does not exist in the UN/CEFACT documentation. Nobody in our group was sure how this was described.

• We confirmed we wish to use this approach.

8. Mating recommendation

• Some systems can provide a mating recommendation and this event would cover this.
• Erwin listed the fields: female parity, sire rank, recommendation type, semen type, sire id
• We renamed the proposed fields to “Sire” rather than “Bull” to cater for multiple species.
• We chose to use semen type and other definitions from the insemination event if possible.
• We agreed with the proposal.

9. Weights

• We reviewed a proposed Weight event.
• We noted that a device ID or similar would be required
• The precision of the unit (which in some cases is configurable for speed vs accuracy reasons)
• The method of measurement – single weighed, walk over weighing, bulk (average) weight, manual estimation, machine vision prediction, software prediction/expected weight.
• Ability to tag a weight to a lifetime interval, special event, or “trait code” (such as “birth weight”, “8-month weight”, etc).
• Ability to specify units to differentiate “pounds” (USA) vs. “kilograms” (everyone else). The default units would be kilograms.
• Andrew undertook to review with a group of equipment and software vendors to get feedback.

10. Next meeting dates

• 6 December 2019, 8am CEST (7am GMT, 8pm NZDST)
• 17 January 2020, 8am CEST (7am GMT, 8pm NZDST)
• No meeting on 20 December 2019 or 3 January 2020.