Change candidate name from string to array of objects (#138)

With required `str`, optional `lang` and `dir` fields
reconciliation-api · Jul 10, 2024 · 1e5ca4a · 1e5ca4a
1 parent ea08452
commit 1e5ca4a
Show file tree

Hide file tree

Showing 7 changed files with 95 additions and 20 deletions.
diff --git a/draft/examples/reconciliation-candidate/valid/example.json b/draft/examples/reconciliation-candidate/valid/example.json
@@ -1,6 +1,10 @@
 {
   "id": "1117582299",
-  "name": "Urbaniak, Hans-Eberhard",
+  "name": [
+    {
+      "str": "Urbaniak, Hans-Eberhard"
+    }
+  ],
   "score": 85.71888,
   "features": [
     {
@@ -41,4 +45,4 @@
       ]
     }
   ]
-}
+}
diff --git a/draft/examples/reconciliation-result-batch/invalid/missing-id.json b/draft/examples/reconciliation-result-batch/invalid/missing-id.json
@@ -3,7 +3,11 @@
     {
       "candidates": [
         {
-          "name": "Urbaniak, Regina",
+          "name": [
+            {
+              "str": "Urbaniak, Regina"
+            }
+          ],
           "score": 53.015232,
           "match": false,
           "type": [
@@ -20,4 +24,4 @@
       ]
     }
   ]
-}
+}
diff --git a/draft/examples/reconciliation-result-batch/invalid/root-array.json b/draft/examples/reconciliation-result-batch/invalid/root-array.json
@@ -3,7 +3,11 @@
     [
       {
         "id": "120333937",
-        "name": "Urbaniak, Regina",
+        "name": [
+          {
+            "str": "Urbaniak, Regina"
+          }
+        ],
         "score": 53.015232,
         "match": false,
         "type": [
@@ -19,7 +23,11 @@
       },
       {
         "id": "1127147390",
-        "name": "Urbaniak, Jan",
+        "name": [
+          {
+            "str": "Urbaniak, Jan"
+          }
+        ],
         "score": 52.357353,
         "match": false,
         "type": [
@@ -35,4 +43,4 @@
       }
     ]
   ]
-}
+}
diff --git a/draft/examples/reconciliation-result-batch/valid/example-full.json b/draft/examples/reconciliation-result-batch/valid/example-full.json
@@ -4,7 +4,13 @@
       "candidates": [
         {
           "id": "120333937",
-          "name": "Urbaniak, Regina",
+          "name": [
+            {
+              "str": "Urbaniak, Regina",
+              "lang": "de",
+              "dir": "auto"
+            }
+          ],
           "description": "1969-| Diss. Fachbereich Mathematik",
           "score": 53.015232,
           "match": false,
@@ -43,7 +49,13 @@
         },
         {
           "id": "1127147390",
-          "name": "Urbaniak, Jan",
+          "name": [
+            {
+              "str": "Urbaniak, Jan",
+              "lang": "de",
+              "dir": "auto"
+            }
+          ],
           "description": "Universität Wrocław, Niederlandestudien",
           "score": 52.357353,
           "match": false,
@@ -64,7 +76,13 @@
       "candidates": [
         {
           "id": "123064325",
-          "name": "Schwanhold, Ernst",
+          "name": [
+            {
+              "str": "Schwanhold, Ernst",
+              "lang": "de",
+              "dir": "auto"
+            }
+          ],
           "description": "1948-| Mitglied des Deutschen Bundestages, SPD (1993)",
           "score": 86.43497,
           "features": [
@@ -103,7 +121,13 @@
         },
         {
           "id": "116362988X",
-          "name": "Schwanhold, Nadine",
+          "name": [
+            {
+              "str": "Schwanhold, Nadine",
+              "lang": "de",
+              "dir": "auto"
+            }
+          ],
           "description": "Dissertation Potsdam, Universität, Mathematik-Naturwissenschaftliche Fakultät, 2017",
           "score": 62.04763,
           "match": false,
@@ -121,4 +145,4 @@
       ]
     }
   ]
-}
+}
diff --git a/draft/examples/reconciliation-result-batch/valid/minimal.json b/draft/examples/reconciliation-result-batch/valid/minimal.json
@@ -4,25 +4,41 @@
       "candidates": [
         {
           "id": "120333937",
-          "name": "Urbaniak, Regina"
+          "name": [
+            {
+              "str": "Urbaniak, Regina"
+            }
+          ]
         },
         {
           "id": "1127147390",
-          "name": "Urbaniak, Jan"
+          "name": [
+            {
+              "str": "Urbaniak, Jan"
+            }
+          ]
         }
       ]
     },
     {
       "candidates": [
         {
           "id": "123064325",
-          "name": "Schwanhold, Ernst"
+          "name": [
+            {
+              "str": "Schwanhold, Ernst"
+            }
+          ]
         },
         {
           "id": "116362988X",
-          "name": "Schwanhold, Nadine"
+          "name": [
+            {
+              "str": "Schwanhold, Nadine"
+            }
+          ]
         }
       ]
     }
   ]
-}
+}
diff --git a/draft/index.html b/draft/index.html
@@ -242,6 +242,7 @@ <h4>This Draft</h4>
             <li><a href="https://github.com/reconciliation-api/specs/pull/149">Move the <code>query</code> field of reconciliation queries inside <code>properties</code> to allow for queries which do not provide entity names</a></li>
             <li><a href="https://github.com/reconciliation-api/specs/pull/156">Add optional <code>standardizedScore</code> field to the manifest</a></li>
             <li><a href="https://github.com/reconciliation-api/specs/pull/166">Unify naming to camelCase convention</a></li>
+            <li><a href="https://github.com/reconciliation-api/specs/pull/176">Change candidate <code>name</code> from string to array of objects with required <code>str</code>, optional <code>lang</code> and <code>dir</code> fields</a></li>
           </ul>
         </section>
       </section>
@@ -566,7 +567,7 @@ <h3>Reconciliation Query Responses</h3>
 	    <dt><code>id</code></dt>
 	    <dd>The identifier of the candidate entity;</dd>
 	    <dt><code>name</code></dt>
-	    <dd>The name of the candidate entity;</dd>
+	    <dd>An array of objects representing names for the candidate entity. Each object MUST contain a string value in its <code>str</code> field, and MAY contain additional <a href="#text-processing-language">lang</a> and <a href="#text-direction">dir</a> fields;</dd>
 	    <dt><code>description</code></dt>
 	    <dd>The entity description MAY optionally be included;</dd>
 	    <dt><code>type</code></dt>

diff --git a/draft/schemas/reconciliation-result-batch.json b/draft/schemas/reconciliation-result-batch.json
@@ -23,8 +23,26 @@
                   "description": "Entity identifier of the candidate"
                 },
                 "name": {
-                  "type": "string",
-                  "description": "Entity name of the candidate"
+                  "type": "array",
+                  "description": "Names for the candidate entity",
+                  "items": {
+                      "type": "object",
+                      "properties": {
+                        "str": {
+                          "type": "string"
+                        },
+                        "lang": {
+                          "type": "string"
+                        },
+                        "dir": {
+                          "type": "string"
+                        }
+                      },
+                      "required": [
+                        "str"
+                      ],
+                      "additionalProperties": false
+                  }
                 },
                 "description": {
                   "type": "string",