Move 'query' field inside 'properties'

Closes #134. Closes #106.
reconciliation-api · Dec 14, 2023 · 8524de9 · 8524de9
1 parent d61ba9e
commit 8524de9
Show file tree

Hide file tree

Showing 8 changed files with 62 additions and 48 deletions.
diff --git a/draft/examples/reconciliation-query-batch/invalid/misnamed-property.json b/draft/examples/reconciliation-query-batch/invalid/misnamed-property.json
@@ -1,10 +1,12 @@
 {
   "queries": [
     {
-      "query": "Christel Hanewinckel",
       "type": "DifferentiatedPerson",
       "limit": 5,
       "props": [
+        {
+          "v": "Christel Hanewinckel"
+        },
         {
           "pid": "professionOrOccupation",
           "v": "Politik*"
@@ -17,10 +19,12 @@
       "type_strict": "should"
     },
     {
-      "query": "Franz Thönnes",
       "type": "DifferentiatedPerson",
       "limit": 5,
       "props": [
+        {
+          "v": "Franz Thönnes"
+        },
         {
           "pid": "professionOrOccupation",
           "v": "Politik*"

diff --git a/draft/examples/reconciliation-query-batch/invalid/multiple-types.json b/draft/examples/reconciliation-query-batch/invalid/multiple-types.json
@@ -1,8 +1,15 @@
 {
   "queries": [
     {
-      "query": "Christel Hanewinckel",
-      "type": ["DifferentiatedPerson", "FictionalCharacter"],
+      "properties": [
+        {
+          "v": "Christel Hanewinckel"
+        }
+      ],
+      "type": [
+        "DifferentiatedPerson",
+        "FictionalCharacter"
+      ],
       "limit": 5
     }
   ]

diff --git a/draft/examples/reconciliation-query-batch/valid/example-full.json b/draft/examples/reconciliation-query-batch/valid/example-full.json
@@ -1,10 +1,12 @@
 {
   "queries": [
     {
-      "query": "Christel Hanewinckel",
       "type": "DifferentiatedPerson",
       "limit": 5,
       "properties": [
+        {
+          "v": "Christel Hanewinckel"
+        },
         {
           "pid": "professionOrOccupation",
           "v": "Politik*"
@@ -16,10 +18,12 @@
       ]
     },
     {
-      "query": "Franz Thönnes",
       "type": "DifferentiatedPerson",
       "limit": 5,
       "properties": [
+        {
+          "v": "Franz Thönnes"
+        },
         {
           "pid": "professionOrOccupation",
           "v": "Politik*"

diff --git a/draft/examples/reconciliation-query-batch/valid/example-min.json b/draft/examples/reconciliation-query-batch/valid/example-min.json
@@ -1,10 +1,18 @@
 {
   "queries": [
     {
-      "query": "Hans-Eberhard Urbaniak"
+      "properties": [
+        {
+          "v": "Hans-Eberhard Urbaniak"
+        }
+      ]
     },
     {
-      "query": "Ernst Schwanhold"
+      "properties": [
+        {
+          "v": "Ernst Schwanhold"
+        }
+      ]
     }
   ]
 }
diff --git a/draft/examples/reconciliation-query-batch/valid/multi-values.json b/draft/examples/reconciliation-query-batch/valid/multi-values.json
@@ -1,10 +1,12 @@
 {
   "queries": [
     {
-      "query": "Christel Hanewinckel",
       "type": "DifferentiatedPerson",
       "limit": 5,
       "properties": [
+        {
+          "v": "Christel Hanewinckel"
+        },
         {
           "pid": "professionOrOccupation",
           "v": [

diff --git a/draft/examples/reconciliation-query-batch/valid/text-processing-language.json b/draft/examples/reconciliation-query-batch/valid/text-processing-language.json
@@ -1,9 +1,11 @@
 {
   "queries": [
     {
-      "query": "Deng Shuping",
       "lang": "en",
       "properties": [
+        {
+          "v": "Deng Shuping"
+        },
         {
           "pid": "professionOrOccupation",
           "v": "art historian"

diff --git a/draft/index.html b/draft/index.html
@@ -478,29 +478,35 @@ <h2>Reconciliation Queries</h2>
         <h3>Structure of a Reconciliation Query</h3>
         <p>
           A <dfn>reconciliation query</dfn> consists of the following fields. 
-	  At least one of <code>query</code> or <code>properties</code> must be supplied, but all other
-	  fields are optional.
           <dl>
-	    <dt><code>query</code></dt>
-            <dd>A query string, consisting of a non-empty string.
-	    	By supplying such a string, a client intends to search for entities with similar
-	    	names. The specifics of how this similarity is defined are determined by the service.</dd>
+	    <dt><code>properties</code></dt>
+	    <dd>An array of <a>property assignments</a> (at least one).</dd>
 	    <dt><code>type</code></dt>
-            <dd>A <a>type</a> identifier. Supplying such a type allows users to restrict
+            <dd>An optional <a>type</a> identifier. Supplying such a type allows users to restrict
 	    	the search to entities which bear this type. Whether this restriction should be a
 	    	hard constraint or simply induce a change on the reconciliation scores can be
 	    	determined by the service. In particular, services MAY return candidates which
 	    	do not belong to the supplied type;</dd>
 	    <dt><code>limit</code></dt>
-            <dd>A limit on the number of candidates to return, which must be a positive integer;</dd>
-	    <dt><code>properties</code></dt>
-	    <dd>An array of objects, where each object maps a <a href='#properties'>property</a> identifier (in the <code>pid</code> field) 
-        to one or more <a>property values</a> (in the <code>v</code> field). These are used to further filter the set of candidates (similar to a WHERE clause in SQL),
-		by allowing clients to specify other attributes of entities that should match, beyond their name in the <code>query</code> field.
-		How reconciliation services handle this further restriction ("must match all properties" or "should match some") and how it affects the score, is up to the service.
-		A reconciliation service that supports properties SHOULD provide a <a>suggest service</a> for discovering these properties;</dd>
+            <dd>An optional limit on the number of candidates to return, which must be a positive integer;</dd>
           </dl>
         </p>
+        <p>
+          A <dfn>property assignment</dfn> specifies the expected value of a property on the entities to match.
+                These are used to filter the set of candidates (similar to a WHERE clause in SQL),
+		by allowing clients to specify an attribute of entities that should match. It consists of:
+         <dl>
+            <dt><code>pid</code></dt>
+            <dd>A <a href='#properties'>property</a> identifier. If this is not provided, then this signals that
+                the client intends to search for entities with similar names. The specifics of how this similarity
+                is defined are determined by the service.</dd> 
+            <dt><code>v</code></dt>
+            <dd>one or more <a>property values</a>.
+         </dl>
+
+        How reconciliation services handle this further restriction ("must match all properties" or "should match some") and how it affects the score, is up to the service.
+	A reconciliation service that supports properties SHOULD provide a <a>suggest service</a> for discovering these properties.
+        </p>
         <p>
           A <dfn>reconciliation query batch</dfn> is an array of <a>reconciliation queries</a>.
         </p>

diff --git a/draft/schemas/reconciliation-query-batch.json b/draft/schemas/reconciliation-query-batch.json
@@ -43,10 +43,6 @@
       "items": {
         "type": "object",
         "properties": {
-          "query": {
-            "type": "string",
-            "description": "A string to be matched against the name of the entities"
-          },
           "type": {
             "description": "A type identifier indicating which class of entities to restrict the search to",
             "type": "string"
@@ -61,13 +57,14 @@
           },
           "properties": {
             "type": "array",
-            "description": "An optional list of property mappings to refine the query",
+            "minItems": 1,
+            "description": "A list of property mappings to select candidates",
             "items": {
               "type": "object",
               "properties": {
                 "pid": {
                   "type": "string",
-                  "description": "The identifier of the property, whose values will be compared to the values supplied"
+                  "description": "The identifier of the property, whose values will be compared to the values supplied. If absent, values will be matched against the entity names"
                 },
                 "v": {
                   "description": "A value (or array of values) to match against the property values associated with the property on each candidate",
@@ -85,7 +82,6 @@
                 }
               },
               "required": [
-                "pid",
                 "v"
               ]
             }
@@ -100,23 +96,8 @@
             ]
           }
         },
-        "anyOf": [
-          {
-            "required": [
-              "query"
-            ]
-          },
-          {
-            "required": [
-              "properties"
-            ],
-            "properties": {
-              "properties": {
-                "type": "array",
-                "minItems": 1
-              }
-            }
-          }
+        "required": [
+          "properties"
         ],
         "additionalProperties": false
       }