From f85a9c38641dbca9d46eba29d2f53aa4c66aa76e Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Wed, 9 Oct 2024 13:11:49 +0200 Subject: [PATCH] Use string objects in suggest responses (#138) - Extract existing string object definition to its own schema file - Reference string-object.json in the suggest response schemas - Update spec & examples to use string objects in suggest responses - Redefine types used in suggest response as described in the spec (instead of referencing the actual type.json schema) - Clarify in the spec that we don't return actual full entity, property, or type objects in the suggest response's `result` field --- .../valid/example.json | 60 ++++++++++++---- .../valid/example.json | 72 ++++++++++++++++--- .../suggest-types-response/valid/example.json | 30 ++++++-- draft/index.html | 12 ++-- .../schemas/reconciliation-result-batch.json | 24 +------ draft/schemas/string-object.json | 19 +++++ draft/schemas/suggest-entities-response.json | 19 +++-- .../schemas/suggest-properties-response.json | 21 ++++-- draft/schemas/suggest-types-response.json | 24 ++++++- 9 files changed, 212 insertions(+), 69 deletions(-) create mode 100644 draft/schemas/string-object.json diff --git a/draft/examples/suggest-entities-response/valid/example.json b/draft/examples/suggest-entities-response/valid/example.json index 92b265b..b4e2f75 100644 --- a/draft/examples/suggest-entities-response/valid/example.json +++ b/draft/examples/suggest-entities-response/valid/example.json @@ -1,30 +1,62 @@ { "result": [ { - "name": "cumulonimbus", - "description": "genus of clouds, dense towering vertical cloud associated with thunderstorms and atmospheric instability", + "name": [ + { + "str": "cumulonimbus" + } + ], + "description": [ + { + "str": "genus of clouds, dense towering vertical cloud associated with thunderstorms and atmospheric instability" + } + ], "id": "Q182311", "notable": [ - { - "name": "cloud genera", - "id": "Q1840368" - } + { + "name": [ + { + "str": "cloud genera" + } + ], + "id": "Q1840368" + } ] }, { - "name": "Cumulopuntia", - "description": "genus of plants", + "name": [ + { + "str": "Cumulopuntia" + } + ], + "description": [ + { + "str": "genus of plants" + } + ], "id": "Q310599", "notable": [ - { - "name": "taxon", - "id": "Q16521" - } + { + "name": [ + { + "str": "taxon" + } + ], + "id": "Q16521" + } ] }, { - "name": "cumulonimbus incus", - "description": "variety of cloud", + "name": [ + { + "str": "cumulonimbus incus" + } + ], + "description": [ + { + "str": "variety of cloud" + } + ], "id": "Q1358304", "notable": [] } diff --git a/draft/examples/suggest-properties-response/valid/example.json b/draft/examples/suggest-properties-response/valid/example.json index 834393e..a1723b9 100644 --- a/draft/examples/suggest-properties-response/valid/example.json +++ b/draft/examples/suggest-properties-response/valid/example.json @@ -1,26 +1,78 @@ { "result": [ { - "name": "coordinate location", - "description": "geocoordinates of the subject. For Earth, please note that only WGS84 coordinating system is supported at the moment", + "name": [ + { + "str": "coordinate location" + } + ], + "description": [ + { + "str": "geocoordinates of the subject. For Earth, please note that only WGS84 coordinating system is supported at the moment" + } + ], "id": "P625", "matchQualifiers": [ - {"id": "ExactMatch", "name": "Exact match of the coordinates"}, - {"id": "DecimalPlaces-N", "name": "Match the coordinates with a precision of N decimal places"} + { + "id": "ExactMatch", + "name": [ + { + "str": "Exact match of the coordinates" + } + ] + }, + { + "id": "DecimalPlaces-N", + "name": [ + { + "str": "Match the coordinates with a precision of N decimal places" + } + ] + } ] }, { - "name": "place of birth", - "description": "most specific known (e.g. city instead of country, or hospital instead of city) birth location of a person, animal or fictional character", + "name": [ + { + "str": "place of birth" + } + ], + "description": [ + { + "str": "most specific known (e.g. city instead of country, or hospital instead of city) birth location of a person, animal or fictional character" + } + ], "id": "P19", "matchQualifiers": [ - {"id": "schema:containsPlace", "name": "Containment relation between a place and another that it contains"}, - {"id": "schema:containedInPlace", "name": "Containment relation between a place and another that contains it"} + { + "id": "schema:containsPlace", + "name": [ + { + "str": "Containment relation between a place and another that it contains" + } + ] + }, + { + "id": "schema:containedInPlace", + "name": [ + { + "str": "Containment relation between a place and another that contains it" + } + ] + } ] }, { - "name": "located in time zone", - "description": "time zone for this item", + "name": [ + { + "str": "located in time zone" + } + ], + "description": [ + { + "str": "time zone for this item" + } + ], "id": "P421" } ] diff --git a/draft/examples/suggest-types-response/valid/example.json b/draft/examples/suggest-types-response/valid/example.json index 75a2512..438d07d 100644 --- a/draft/examples/suggest-types-response/valid/example.json +++ b/draft/examples/suggest-types-response/valid/example.json @@ -2,25 +2,45 @@ "result": [ { "id": "Work", - "name": "Werk" + "name": [ + { + "str": "Werk" + } + ] }, { "id": "MusicalWork", - "name": "Werk der Musik", + "name": [ + { + "str": "Werk der Musik" + } + ], "broader": [ { "id": "Work", - "name": "Werk" + "name": [ + { + "str": "Werk" + } + ] } ] }, { "id": "BuildingOrMemorial", - "name": "Bauwerk oder Denkmal" + "name": [ + { + "str": "Bauwerk oder Denkmal" + } + ] }, { "id": "VersionOfAMusicalWork", - "name": "Fassung eines Werks der Musik" + "name": [ + { + "str": "Fassung eines Werks der Musik" + } + ] } ] } diff --git a/draft/index.html b/draft/index.html index f056527..1c1f42c 100644 --- a/draft/index.html +++ b/draft/index.html @@ -752,20 +752,20 @@

Suggest Responses

A response to a suggest query consists of the following fields:
result
-
An array of items, which can be entities, properties +
An array of items, which can represent entities, properties or types depending on which of these the service is provided for. Each such object can contain the following fields:
id
The identifier of the entity, property or type suggested;
name
-
Its corresponding human-readable name, to be displayed prominently to the user;
+
An array of string objects with its corresponding human-readable name, to be displayed prominently to the user;
description
-
An optional description which can be provided to disambiguate namesakes, providing more context. This could for instance be displayed underneath the name;
-
notable
-
When suggesting entities only, this field can be used to supply some important types (not necessarily all types) of the suggested entity. The value must be an array of either type identifiers (as strings) or type objects, containing an id and name field which represent the type.
+
An optional array of string objects with descriptions to disambiguate namesakes, providing more context. This could for instance be displayed underneath the name;
+
notable
+
When suggesting entities only, this field can be used to supply some important types (not necessarily all types) of the suggested entity. The value must be an array of either type identifiers (as strings) or type objects (each containing fields id, a string, and name, an array of string objects), which represent the type.
matchQualifiers
-
When suggesting properties only, an optional array of objects, each containing an id and name field, which represent the property's matchQualifiers supported in reconciliation queries.
+
When suggesting properties only, an optional array of objects (each containing fields id, a string, and name, an array of string objects), which represent the property's matchQualifiers supported in reconciliation queries.
diff --git a/draft/schemas/reconciliation-result-batch.json b/draft/schemas/reconciliation-result-batch.json index cd9c839..82332e7 100644 --- a/draft/schemas/reconciliation-result-batch.json +++ b/draft/schemas/reconciliation-result-batch.json @@ -3,26 +3,6 @@ "$id": "https://reconciliation-api.github.io/specs/draft/schemas/reconciliation-result-batch.json", "type": "object", "description": "This schema can be used to validate the JSON serialization of any reconciliation result batch.", - "definitions": { - "string_object": { - "type": "object", - "properties": { - "str": { - "type": "string" - }, - "lang": { - "type": "string" - }, - "dir": { - "type": "string" - } - }, - "required": [ - "str" - ], - "additionalProperties": false - } - }, "required": [ "results" ], @@ -46,14 +26,14 @@ "type": "array", "description": "Names for the candidate entity", "items": { - "$ref": "#/definitions/string_object" + "$ref": "string-object.json" } }, "description": { "type": "array", "description": "Optional descriptions of the candidate entity", "items": { - "$ref": "#/definitions/string_object" + "$ref": "string-object.json" } }, "score": { diff --git a/draft/schemas/string-object.json b/draft/schemas/string-object.json new file mode 100644 index 0000000..b07ae86 --- /dev/null +++ b/draft/schemas/string-object.json @@ -0,0 +1,19 @@ +{ + "$id": "https://reconciliation-api.github.io/specs/draft/schemas/string-object.json", + "type": "object", + "properties": { + "str": { + "type": "string" + }, + "lang": { + "type": "string" + }, + "dir": { + "type": "string" + } + }, + "required": [ + "str" + ], + "additionalProperties": false +} diff --git a/draft/schemas/suggest-entities-response.json b/draft/schemas/suggest-entities-response.json index 3b467ff..c81bdad 100644 --- a/draft/schemas/suggest-entities-response.json +++ b/draft/schemas/suggest-entities-response.json @@ -14,12 +14,18 @@ "description": "Identifier of the suggested entity" }, "name": { - "type": "string", - "description": "Name of the suggested entity" + "type": "array", + "description": "Name of the suggested entity", + "items": { + "$ref": "string-object.json" + } }, "description": { - "type": "string", - "description": "An optional description which can be provided to disambiguate namesakes, providing more context." + "type": "array", + "description": "An optional description which can be provided to disambiguate namesakes, providing more context.", + "items": { + "$ref": "string-object.json" + } }, "notable": { "type": "array", @@ -34,7 +40,10 @@ "type": "string" }, "name": { - "type": "string" + "type": "array", + "items": { + "$ref": "string-object.json" + } } }, "required": [ diff --git a/draft/schemas/suggest-properties-response.json b/draft/schemas/suggest-properties-response.json index 2e02b01..8ad371f 100644 --- a/draft/schemas/suggest-properties-response.json +++ b/draft/schemas/suggest-properties-response.json @@ -14,12 +14,18 @@ "description": "Identifier of the suggested property" }, "name": { - "type": "string", - "description": "Name of the suggested property" + "type": "array", + "description": "Name of the suggested property", + "items": { + "$ref": "string-object.json" + } }, "description": { - "type": "string", - "description": "An optional description which can be provided to disambiguate namesakes, providing more context." + "type": "array", + "description": "An optional description which can be provided to disambiguate namesakes, providing more context.", + "items": { + "$ref": "string-object.json" + } }, "matchQualifiers": { "type": "array", @@ -32,8 +38,11 @@ "description": "Identifier of the matchQualifier" }, "name": { - "type": "string", - "description": "Name of the matchQualifier" + "type": "array", + "description": "Name of the matchQualifier", + "items": { + "$ref": "string-object.json" + } } }, "required": [ diff --git a/draft/schemas/suggest-types-response.json b/draft/schemas/suggest-types-response.json index 6664af3..bd580dd 100644 --- a/draft/schemas/suggest-types-response.json +++ b/draft/schemas/suggest-types-response.json @@ -6,7 +6,29 @@ "properties": { "result": { "type": "array", - "items": { "$ref": "type.json" } + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Identifier of the suggested type" + }, + "name": { + "type": "array", + "description": "Name of the suggested type", + "items": { + "$ref": "string-object.json" + } + }, + "description": { + "type": "array", + "description": "An optional description which can be provided to disambiguate namesakes, providing more context.", + "items": { + "$ref": "string-object.json" + } + } + } + } } }, "required": [