Representing type hierarchies

[fsteeg]

Current work in progress for #68.

[fsteeg]

As a basic test case for this, I've added single-level broader type support to our reconciliation service at https://test.lobid.org/gnd/reconcile (see https://github.com/hbz/lobid-gnd/commit/5c8d0a8a2049b06dee23827e6e33cf20065b3f1f) and to the testbench (see https://github.com/reconciliation-api/testbench/pull/28). I think this shows how even a simple implementation of broader IDs can be useful. In the future, we could look into full hierarchy support in the testbench, if that makes sense.

[wetneb]

Mentioned in the call: perhaps it would make sense to allow lists of broader types, rather than a single one. It would be useful for the Wikidata endpoint at least.

[thadguidry]

{
  "$schema": "http://json-schema.org/schema#",
  "$id": "https://reconciliation-api.github.io/specs/latest/schemas/suggest-types-response.json",
  "type": "object",
  "description": "This schema can be used to validate the JSON response of a suggest service for types.",
  "properties": {
    "result": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Identifier of the suggested type"
          },
          "name": {
            "type": "string",
            "description": "Name of the suggested type"
          },
          "description": {
            "type": "string",
            "description": "An optional description which can be provided to disambiguate namesakes, providing more context."
          },
          "broader": {
            "type": "string",
            "description": "A broader semantic relation as defined by SKOS http://www.w3.org/2004/02/skos/core#broader",
            "$id": "http://www.w3.org/2004/02/skos/core#broader",
            "additionalProperties": {
              "label": "skos:broadMatch"
            }
          }
        },

Some clients might want to enrich the presentation of properties with additional metadata or annotations. In the above example "broader" is given more context and where that context can be optionally displayed by a smart client.

I read though some of the JSON Schema core and appendix for Working with vocabularies, but not 100% sure my example is conforming for validation, but still wanted to show what I was asking about on our last meeting, that of giving more context for a property such as "broader". And it seems JSON Schema has various ways that more context, annotation, or metadata could be given depending on validation needs, or ignoring validation (the validator ignores, but smart clients can still understand and use, and other clients just safely ignore parts they don't understand, which seems possible with JSON Schema with is various RECOMMENDED, SHOULD, etc in various keywords and descriptors in it's standards)

1. I "think" in the above case that "label" would be ignored by some clients? - https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.10.3.2.3
2. I'm not sure about "$id" but it seems to be valid for JSON Schema? - https://json-schema.org/draft/2020-12/json-schema-core.html#rfc.section.8.2.1
3. In other words, could a service say additional things about a property, without breaking clients like OpenRefine, but another smart client might use the additional information about the property in an nicer suggest widget or reconciling panel. What parts of JSON Schema could be utilized and how, in order to accomplish that? Does my above example demonstrate that case in a valid way? or does it need some tweaks in order to accomplish that goal?
4. I didn't play with $defs but maybe it also has a role here? Don't know.
5. This all might be just a simple exercise of us coming to better understanding of JSON Schema's intricacies.

[fsteeg]

Switched from array of strings to array of types in https://github.com/reconciliation-api/specs/pull/73/commits/f19ce913afe4e9efadf06e42ada07ca321ceac20 as discussed in https://github.com/reconciliation-api/testbench/pull/28 and https://etherpad.lobid.org/p/reconciliation-november-2021.

Next: update our service implementation in https://github.com/hbz/lobid-gnd/pull/293 and testbench in https://github.com/reconciliation-api/testbench/pull/28.

[fsteeg]

Next: update our service implementation [...] and testbench [...].

Done, see https://github.com/hbz/lobid-gnd/pull/293#issuecomment-993368743 and https://github.com/reconciliation-api/testbench/pull/28#issuecomment-993370187.