As an ODH user, I would like to know the meaning of the single fields exposed by the API

[rcavaliere]

• [x] @Piiit will make an evaluation about the possibility to add these descriptions directly in the swagger, as technically feasible for the tourism API (as confirmed by @RudiThoeni)

[Piiit]

@sseppi @rcavaliere Done, please test...

• Go to https://mobility.api.opendatahub.testingmachine.eu/
• Scroll down to "schemas"

Not perfect, but good enough to have it integrated in our ODH browser I guess. The schema definitions are currently not linked as output description to the above calls, because depending on the representation and select parameters they might not correspond. To make it perfect, I would need to write several specific rules... I do not know if that is necessary. Let me know

[Piiit]

@rcavaliere I have not set a description for every field, we could also define default values, min,max and other constraints, if you like... for that I would need some domain expertise

[Piiit]

@mrabans FYI @gappc Maybe useful for the data browser integration?

[rcavaliere]

@Piiit looks promising. But I fear that this information is generic and not specific for every data type (e.g. e-charging, air quality), which may need some specific information for that. Do you have a proposal on how we could handle this?

[gappc]

@Piiit, @mrabans, @sseppi, @RudiThoeni I didn't take a deep look but this direction is definitely useful for the Databrowser, as we rely on information provided by the Swagger / OpenAPI definitions. It would also be very nice to narrow down the types and restrictions on them (e.g max. size) where possible. That way we could further automate things in the Databrowser. Ideally, the same ideas and concepts should be used across all ODH domains, such that the Databrowser can reuse as much logic as possible.

All in all, nice work :)

[Piiit]

@Piiit looks promising. But I fear that this information is generic and not specific for every data type (e.g. e-charging, air quality), which may need some specific information for that. Do you have a proposal on how we could handle this?

To solve this we would need several things: 1) some additional descriptive columns in several tables, that describe the actual data their:

• station
• data type
• station type
• event
• etc.... 2) a new table that contains the station types with a description, links to documentation etc. 3) a json schema definition for each metadata field, that a data collector must register. For example, a data collector for ParkingStations would register a certain schema to describe that station with types, constraints, json structure etc. Data pushes only accept those schemas then. In addition, a discriminator field must be defined for those metadata JSON to distinguish them. For example, one discriminator could be the station type, another the origin or a field inside the metadata JSON itself. We could look at jsonld for that.

These schemas could be used to automatically generate a swagger document (Open API v3 yaml file)... not perfect, because data comes in dynamically at high speed and might change too fast.

Another idea is to have "metadata" calls in the API itself, that explain and validate the output.

The descriptive fields must be updated manually, or with each data collector.

We would need a v3 API for that, because it probably needs incompatible changes

[Piiit]

Closing, please open new issues if additional functionality is needed...

[mrabans]

@Piiit thanks for explaining. In an first step I think a pure description is enough. Probably there is no need to validate data from the data providers right now on a schema level. The biggest issue is explaining to data consumers how this data is composed and should be interpreted. This is different for each data type, so the additional table is probably needed.

[rcavaliere]

@Piiit @mrabans as I said, I will try to start document these specific details for each source / station types in a separate document. We will then see how to optimally integrate this together to provide ODH customers with all details needed in order to perfectly understand our API and the type of data we provide

[sseppi]

As Roberto said, we need now to understand what kind of information the data consumer needs and collect in a document/spreadsheet, in order to take a better decision. Maybe we could also ask for feedback to data consumers.

@rcavaliere maybe it could be an Idea to create a dedicated issue about that, and put it in the Customer Care Kanban. so we can keep it tracked.