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
reconciliation-api · Oct 9, 2024 · f85a9c3 · f85a9c3
1 parent 42bdcbc
commit f85a9c3
Show file tree

Hide file tree

Showing 9 changed files with 212 additions and 69 deletions.
diff --git 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
@@ -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
@@ -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
@@ -752,20 +752,20 @@ <h3>Suggest Responses</h3>
           A response to a suggest query consists of the following fields:
           <dl>
             <dt><code>result</code></dt>
-            <dd>An array of items, which can be <a>entities</a>, <a>properties</a>
+            <dd>An array of items, which can represent <a>entities</a>, <a>properties</a>
             or <a>types</a> depending on which of these the service
             is provided for. Each such object can contain the following fields:
             <dl>
               <dt><code>id</code></dt>
               <dd>The identifier of the entity, property or type suggested;</dd>
               <dt><code>name</code></dt>
-              <dd>Its corresponding human-readable name, to be displayed prominently to the user;</dd>
+              <dd>An array of <a>string objects</a> with its corresponding human-readable name, to be displayed prominently to the user;</dd>
               <dt><code>description</code></dt>
-              <dd>An optional description which can be provided to disambiguate namesakes, providing more context. This could for instance be displayed underneath the <code>name</code>;</dd>
-	      <dt><code>notable</code></dt>
-	      <dd>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 <code>id</code> and <code>name</code> field which represent the type.</dd>
+              <dd>An optional array of <a>string objects</a> with descriptions to disambiguate namesakes, providing more context. This could for instance be displayed underneath the <code>name</code>;</dd>
+              <dt><code>notable</code></dt>
+              <dd>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 <code>id</code>, a string, and <code>name</code>, an array of <a>string objects</a>), which represent the type.</dd>
               <dt><code>matchQualifiers</code></dt>
-              <dd>When suggesting properties only, an optional array of objects, each containing an <code>id</code> and <code>name</code> field, which represent the property's <code>matchQualifiers</code> supported in <a>reconciliation queries</a>.</dd>
+              <dd>When suggesting properties only, an optional array of objects (each containing fields <code>id</code>, a string, and <code>name</code>, an array of <a>string objects</a>), which represent the property's <code>matchQualifiers</code> supported in <a>reconciliation queries</a>.</dd>
             </dl>
             </dd>
           </dl>

diff --git 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
@@ -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
@@ -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
@@ -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": [