ICAR Animal Data Exchange Working Group – Technical Meeting 10 March 2022

• In attendance: Alexey S, Andrew C, Andreas S, Arjan L, Erwin S, Graham M, Sven S, Thomas P

Agenda:

Items to discuss today are: icarResource Discriminator property; streaming API for bulk data sharing; herd level milk recording

1. Milk recording information on herd level (#184)

Erwin has created the Get statistics endpoint only. The parameters include: id; the location; the kind or purpose of the statistics; a date range; grouping information type of group, number of animals and a group specifier; statistics information metric, units and aggregation There is a pull request #284 that would be good for people to review and provide feedback on. It was suggested we add an issue to extend the units. It could be useful to have some higher level documentation that describes the endpoints. Review pull request and provide feedback

2. Current icarResource Discriminator property doesnt appear valid (#278)

It would be helpful if people reviewed the pull request #283 and made some comments over the next week. There was a long discussion on whether there was a breaking change and what should be done about it. There are two issues: the declaration of the discriminator and the additional discriminator that was designed for the event type. It could be argued that the declaration of the discriminator could be dealt with by documentation if we wanted to.

We could document that you need to implement the discriminator as a property if you are not using code generation that generates it for you. We could move the event type from being a discriminator to just being a property.

We don't want people to say "they have broken the spec" even when we have not broken it. We would rather find some way to manage the process. It may be a combination of correcting, documenting and doing pull requests and getting people to test their code. Those of you who have servers that already have clients calling them need to liaise with your clients to make sure that they test their implementation or you need to do enough work that you don't break the implementations. We shouldn't wait until 2.0 but try to correct this and be pragmatic about how we correct it. There were comments about which languages may be affected.

Andrew subsequently summarised the problem in a comment on the issue:

There are several issues logged in openapi-generator about this. Essentially it seems that at present discriminators to support data binding and model properties are handled by two different parts of the generator code, and the "discriminator" part does not align with the OpenAPI spec (i.e. doesn't expect the discriminator will be a property in the model).

It is possible to use annotations (As.EXISTING_PROPERTY) to tell the Java and C# generator to use the model property, but then it expects you to populate the value of the property yourself (which is how other languages will do it anyway).

It does look like this is being addressed, filling in the model property automatically on serialization, which has recently been merged into master (6.0.0) for openapi-generator. See #9441 in https://github.com/OpenAPITools/openapi-generator/issues. I have no idea what that means though in actual usable releases in the roadmap.

Next meeting scheduled for 24 March 2022 at 8:15am CET