What is the proposed way to retrieve available schemata or schema/id combinations for different identifiers

[ghost]

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

[alamers]

My thoughts on this:

In #129 there is a first proposal for this kind of meta data. There, my suggestion is to expand @MetroMarv 's suggestion:

• /locations
• /locations/{scheme}

That solves a (small) part of this ticket: retrieving the id's for a specific scheme for locations. This is sort of trivial since this scheme is part of the URI and it thus (more or less by accident) has a name.

Building on that, we could then have very detailed api's exploring schemata:

• /schemata -> returning a list of 'schemata' amongst, e.g. ['locations', 'animals', 'breeds', 'trait-labels']
• /schemata/locations -> return all available {scheme}'s for locations, e.g. ['nl.kvk','nl.ubn']

However, this feels a bit heavy for something that is quite possibly very static. We could combine all this in a single 'schemata' message.

I'd expect only the actual available identifiers to be quite dynamic and thus warranting its own endpoint. For locations I've provided a suggestion above. For e.g. animals, we have a very extensive set of movements; I'm not sure if we need to extend that. Other schemata that we (currently) have:

• breed identifier
• trait label identifier

These also fit into the schemata scheme:

• /schemata/breed for a list of breed identifier schemes
• /schemata/trait-label for a list of trait-label identifier schemes

But we do not have a way to retrieve the values, unless we do this (or combine it into the previous uri's):

• /schemata/breed/values for a list of breed identifier schemes
• /schemata/trait-label/values for a list of trait-label identifier schemes
  But this is inconsistent with locations and animal schemata. Is that a problem?

To summarize:
I found 4 schemata:

• locations
• animals
• breed
• trait labels

Do we treat them all as equal or is it fine to differentiate exploring the actual available identifiers between these schemata?

[ahokkonen]

I want to rise this issue back to live :)

We are also running into the situation now where we need to pass an information about schemes and also in some cases (for example breeds) a values inside the scheme.

I like the proposal and solution presented by @alamers with small adjustments maybe:

for retrieving list of supported schemas and the values we could use:

• /schemata for all supported schema types / schematas (locations, animals, breeds)
• /schemata/{schemata} for a list of identifier (scheme) for specific schemata (/schemata/breeds)
• /schemata/{schemata}/{schema} for a list of values for specific schemata (/schemata/breeds/{icar.interbull})

Could this be an acceptable and common solution for scheme information retrieving?

[ghost]

I like Antons approach to retrieve schemata. I was thinking whether we could leave "locations" out here because we could just have a look at the /locations endpoint to see which schemata are available. But after thinking about it a littel bit more I prefer to list location schemata as well because the schemata/locations/ endpoint would then (in contrast to the /locations/ endpoint) provide a list of all supported schemata. This makes a lot of sense to me as this provides some information about the capabilities of the system.

[ahokkonen]

As discussed on today's meeting for schemata - going with #109 (comment) proposal, but placing endpoints behind /locations:

• /locations/{location-scheme}/{location-id}/schemata

  • all supported schema types (locations, animals, breeds)

• /locations/{location-scheme}/{location-id}/schemata/{schema type}

  • list of schemata for specific schema type (aka /schemata/breeds with results as 'icar.inderbull.breeds', 'eu.germany.breeds', etc.')

• /locations/{location-scheme}/{location-id}/schemata/{schema type}/{schema}

  • list of values for specific scheme (aka /schemata/breeds/{icar.interbull.breeds})

Is it proper terminology {schemata} for schema type and {schema} for specific schema?

For messaged it would be probably enough to have string based values for /schemata and /schemata/{schemata}, but perhaps more complex message for scheme values? icarResource inheritance needed?

{
  "type": "object",

  "description": "Schema id value type",

  "properties": {
    "id": {
      "type": "string",
      "description": "Id/identifier for scheme value"
    },
    "name": {
      "type": "string",
      "description": "Friendly name for identifier (maybe translation?)"
    }
  }
}

[ghost]

Well, values could just be a list of strings (except for identifiers as Anton suggested), however, we would maybe loose paging and consistency, so I'D still go for (very simple) objects. I'd not make any of those inherit from resources. Apart from that I'm all good with Antons approach.

[ahokkonen]

Simple object for 'schema type' and 'schema' could be something like:

{
  "type": "object",

  "description": "Schema type/schema name type",

  "properties": {
    "name": {
      "type": "string",
      "description": "Schema type/schema name"
    }
  }
}

and for schema values:

{
  "type": "object",

  "description": "Schema id value type",

  "properties": {
    "id": {
      "type": "string",
      "description": "Id/identifier for scheme value"
    },
    "name": {
      "type": "string",
      "description": "Friendly name for identifier (maybe translation?)"
    }
  }
}

any notes, feedback on that @cookeac @alamers @erwinspeybroeck ?

[cookeac]

Feedback from me:

1. I'm pretty comfortable with the schema types as @thomasd-gea has defined e.g. [{"location", "Locations for farms or herds."},...]
2. Same with the schemes themselves
3. Regarding translation, see Guidance on use of schema/id and name pairs within API #107 which has a conversation about translation and where we pulled back from that.
4. The set of schemata and the number of likely schemes supported are small enough that could be one API with nested data rather than needing multiple calls, but with HTTP2 and keepalives I am less worried about this, and separate APIs are nicer to read.
5. When we come to enumerating values (where this is supported), the objects should be icarResource derivatives because if there is a large number we may want to at least support pagination in the spec with icarResourceCollection. However, if you were not going to enumerate things like animals (because there is already an API for that) and hence only things like breeds, then you could perhaps avoid this, and return a simple array of values.

[cookeac]

Fixed by #196