Extract string_object definition from candidate name (#138)

And use for candidate `description`
reconciliation-api · Jul 10, 2024 · 42bdcbc · 42bdcbc
1 parent 1e5ca4a
commit 42bdcbc
Show file tree

Hide file tree

Showing 3 changed files with 60 additions and 25 deletions.
diff --git a/draft/examples/reconciliation-result-batch/valid/example-full.json b/draft/examples/reconciliation-result-batch/valid/example-full.json
@@ -11,7 +11,11 @@
               "dir": "auto"
             }
           ],
-          "description": "1969-| Diss. Fachbereich Mathematik",
+          "description": [
+            {
+              "str": "1969-| Diss. Fachbereich Mathematik"
+            }
+          ],
           "score": 53.015232,
           "match": false,
           "features": [
@@ -56,7 +60,11 @@
               "dir": "auto"
             }
           ],
-          "description": "Universität Wrocław, Niederlandestudien",
+          "description": [
+            {
+              "str": "Universität Wrocław, Niederlandestudien"
+            }
+          ],
           "score": 52.357353,
           "match": false,
           "type": [
@@ -83,7 +91,11 @@
               "dir": "auto"
             }
           ],
-          "description": "1948-| Mitglied des Deutschen Bundestages, SPD (1993)",
+          "description": [
+            {
+              "str": "1948-| Mitglied des Deutschen Bundestages, SPD (1993)"
+            }
+          ],
           "score": 86.43497,
           "features": [
             {
@@ -128,7 +140,11 @@
               "dir": "auto"
             }
           ],
-          "description": "Dissertation Potsdam, Universität, Mathematik-Naturwissenschaftliche Fakultät, 2017",
+          "description": [
+            {
+              "str": "Dissertation Potsdam, Universität, Mathematik-Naturwissenschaftliche Fakultät, 2017"
+            }
+          ],
           "score": 62.04763,
           "match": false,
           "type": [

diff --git a/draft/index.html b/draft/index.html
@@ -242,7 +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>
+            <li><a href="https://github.com/reconciliation-api/specs/pull/176">Change candidate <code>name</code> and <code>description</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>
@@ -567,9 +567,9 @@ <h3>Reconciliation Query Responses</h3>
 	    <dt><code>id</code></dt>
 	    <dd>The identifier of the candidate entity;</dd>
 	    <dt><code>name</code></dt>
-	    <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>
+	    <dd>An array of <a>string objects</a> with names for the candidate entity;</dd>
 	    <dt><code>description</code></dt>
-	    <dd>The entity description MAY optionally be included;</dd>
+	    <dd>An optional array of <a>string objects</a> with descriptions for the candidate entity;</dd>
 	    <dt><code>type</code></dt>
 	    <dd>The types of the candidate entity;</dd>
 	    <dt><code>score</code></dt>
@@ -580,6 +580,17 @@ <h3>Reconciliation Query Responses</h3>
             <dd>A boolean matching decision, which indicates whether the service considers this candidate good enough to be chosen as a correct match.</dd>
           </dl>
         </p>
+        <p>
+          A <dfn>string object</dfn> contains the following fields:
+          <dl>
+            <dt><code>str</code></dt>
+            <dd>The string value;</dd>
+            <dt><code>lang</code></dt>
+            <dd>Optionally, the <a href="#text-processing-language">text-processing language</a> of the string;</dd>
+            <dt><code>dir</code></dt>
+            <dd>Optionally, the <a href="#text-direction">text direction</a> of the string.</dd>
+          </dl>
+        </p>
         <p>
           A <dfn>matching feature</dfn> is a numerical or boolean value which can be used to determine how likely it is for the candidate to be the correct entity. It contains the following fields:
           <dl>

diff --git a/draft/schemas/reconciliation-result-batch.json b/draft/schemas/reconciliation-result-batch.json
@@ -3,6 +3,26 @@
   "$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"
   ],
@@ -26,27 +46,15 @@
                   "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
+                    "$ref": "#/definitions/string_object"
                   }
                 },
                 "description": {
-                  "type": "string",
-                  "description": "Optional description of the candidate entity"
+                  "type": "array",
+                  "description": "Optional descriptions of the candidate entity",
+                  "items": {
+                    "$ref": "#/definitions/string_object"
+                  }
                 },
                 "score": {
                   "type": "number",