Merge pull request #149 from reconciliation-api/134-query-to-property

Move 'query' field inside 'properties'

draft/examples/reconciliation-query-batch/invalid/empty-properties.json → draft/examples/reconciliation-query-batch/invalid/empty-conditions.json

@@ -1,7 +1,7 @@
 {
   "queries": [
     {
-      "properties": []
+      "conditions": []
     }
   ]
 }

draft/examples/reconciliation-query-batch/invalid/misnamed-property.json → draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.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*"

draft/examples/reconciliation-query-batch/invalid/missing-match-type.json

@@ -0,0 +1,18 @@
+{
+  "queries": [
+    {
+      "conditions": [
+        {
+          "v": "Hans-Eberhard Urbaniak"
+        }
+      ]
+    },
+    {
+      "conditions": [
+        {
+          "v": "Ernst Schwanhold"
+        }
+      ]
+    }
+  ]
+}

draft/examples/reconciliation-query-batch/invalid/multiple-types.json

@@ -1,8 +1,16 @@
 {
   "queries": [
     {
-      "query": "Christel Hanewinckel",
-      "type": ["DifferentiatedPerson", "FictionalCharacter"],
+      "conditions": [
+        {
+          "match_type": "name",
+          "v": "Christel Hanewinckel"
+        }
+      ],
+      "type": [
+        "DifferentiatedPerson",
+        "FictionalCharacter"
+      ],
       "limit": 5
     }
   ]

draft/examples/reconciliation-query-batch/invalid/no-root-object.json

@@ -1,8 +1,20 @@
 [
   {
-    "properties": [{"pid":"uid", "v": "27eb892afbb2"}]
+    "conditions": [
+      {
+        "match_type": "property",
+        "pid": "uid",
+        "v": "27eb892afbb2"
+      }
+    ]
   },
   {
-    "properties": [{"pid":"uid", "v": "ab09da9dd37e"}]
+    "conditions": [
+      {
+        "match_type": "property",
+        "pid": "uid",
+        "v": "ab09da9dd37e"
+      }
+    ]
   }
 ]

draft/examples/reconciliation-query-batch/valid/example-full.json

@@ -1,18 +1,23 @@
 {
   "queries": [
     {
-      "query": "Christel Hanewinckel",
       "type": "DifferentiatedPerson",
       "limit": 5,
-      "properties": [
+      "conditions": [
         {
+          "match_type": "name",
+          "v": "Christel Hanewinckel"
+        },
+        {
+          "match_type": "property",
           "pid": "professionOrOccupation",
           "v": "Politik*",
           "required": false,
           "match_quantifier": "any",
           "match_qualifier": "WildcardMatch"
         },
         {
+          "match_type": "property",
           "pid": "affiliation",
           "v": "http://d-nb.info/gnd/2022139-3",
           "required": false,
@@ -22,18 +27,23 @@
       ]
     },
     {
-      "query": "Franz Thönnes",
       "type": "DifferentiatedPerson",
       "limit": 5,
-      "properties": [
+      "conditions": [
+        {
+          "match_type": "name",
+          "v": "Franz Thönnes"
+        },
         {
+          "match_type": "property",
           "pid": "professionOrOccupation",
           "v": "Politik*",
           "required": false,
           "match_quantifier": "any",
           "match_qualifier": "WildcardMatch"
         },
         {
+          "match_type": "property",
           "pid": "affiliation",
           "v": "http://d-nb.info/gnd/2022139-3",
           "required": false,

draft/examples/reconciliation-query-batch/valid/example-min.json

@@ -1,10 +1,20 @@
 {
   "queries": [
     {
-      "query": "Hans-Eberhard Urbaniak"
+      "conditions": [
+        {
+          "match_type": "name",
+          "v": "Hans-Eberhard Urbaniak"
+        }
+      ]
     },
     {
-      "query": "Ernst Schwanhold"
+      "conditions": [
+        {
+          "match_type": "name",
+          "v": "Ernst Schwanhold"
+        }
+      ]
     }
   ]
 }

draft/examples/reconciliation-query-batch/valid/multi-values.json

@@ -1,11 +1,15 @@
 {
   "queries": [
     {
-      "query": "Christel Hanewinckel",
       "type": "DifferentiatedPerson",
       "limit": 5,
-      "properties": [
+      "conditions": [
         {
+          "match_type": "name",
+          "v": "Christel Hanewinckel"
+        },
+        {
+          "match_type": "property",
           "pid": "professionOrOccupation",
           "v": [
             "Politik*",

draft/examples/reconciliation-query-batch/valid/no-query-string.json

@@ -1,8 +1,22 @@
-{"queries":[
-  {
-    "properties": [{"pid":"uid", "v": "27eb892afbb2"}]
-  },
-  {
-    "properties": [{"pid":"uid", "v": "ab09da9dd37e"}]
-  }
-]}
+{
+  "queries": [
+    {
+      "conditions": [
+        {
+          "match_type": "property",
+          "pid": "uid",
+          "v": "27eb892afbb2"
+        }
+      ]
+    },
+    {
+      "conditions": [
+        {
+          "match_type": "property",
+          "pid": "uid",
+          "v": "ab09da9dd37e"
+        }
+      ]
+    }
+  ]
+}

draft/examples/reconciliation-query-batch/valid/text-processing-language.json

@@ -1,14 +1,19 @@
 {
   "queries": [
     {
-      "query": "Deng Shuping",
       "lang": "en",
-      "properties": [
+      "conditions": [
         {
+          "match_type": "name",
+          "v": "Deng Shuping"
+        },
+        {
+          "match_type": "property",
           "pid": "professionOrOccupation",
           "v": "art historian"
         },
         {
+          "match_type": "property",
           "pid": "variantName",
           "v": "鄧淑蘋",
           "lang": "zh-Hant"

draft/index.html

@@ -481,42 +481,46 @@ <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>conditions</code></dt>
+	    <dd>An array of <a>conditions</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><p>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 refine the list of candidates by allowing clients to specify other attributes of entities, beyond their name in the <code>query</code> field.
-        A reconciliation service that supports properties SHOULD provide a <a>suggest service</a> for discovering these properties.</p>
-        <p>In addition to <code>pid</code> and <code>v</code>, services MAY support the following optional fields that allow clients to specify the effect of each property on the resulting list of candidates.
-          If these fields are omitted, the exact behavior ("must match all", "should match some", etc.) is up to the service.</p>
-        <dl>
-          <dt><code>required</code></dt>
-          <dd>A boolean indicating if a match for the property is required for an entity to enter the list of candidates (i.e. acting like a filter or a WHERE clause in SQL)
-            or optional (i.e. only effecting the entity's rank in the list of candidates);</dd>
-          <dt><code>match_quantifier</code></dt>
-          <dd>A string to indicate which of the values in <code>v</code> to match. MUST be "any" (equivalent to boolean OR), "all" (equivalent to boolean AND), or "none" (equivalent to boolean NOT);</dd>
-          <dt><code>match_qualifier</code></dt>
-          <dd>A string to indicate how to match the values in <code>v</code>.
-            This can be used for general matching relations like "skos:exactMatch", "skos:closeMatch", etc. or for specific features like spatial matching with geo data
-            (e.g. containment search with "schema:containsPlace" etc.) or custom matching on date fields (e.g. services supporting the [[EDTF]] specification could use "EDTF:Level-0" etc.
-            To allow discovery of supported qualifiers by clients, services that support <code>match_qualifier</code> MUST return the supported <code>match_qualifiers</code> for each property
-            in their property <a href='#suggest-responses'>suggest responses</a>.</p></dd>
-        </dl>
-        </dd>
-        </dl>
+            <dd>An optional limit on the number of candidates to return, which must be a positive integer;</dd>
+          </dl>
+        </p>
+        <p>
+          A <dfn>condition</dfn> specifies a constraint that should be matched by the entities to return.
+                It is 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>match_type</code></dt>
+            <dd>Either <code>name</code> or <code>property</code>, depending on whether the condition relates to entity names or their properties.</dd>
+            <dt><code>pid</code></dt>
+            <dd>A <a href='#properties'>property</a> identifier, to be provided if and only if the <code>match_type</code> is <code>property</code>.</dd>
+            <dt><code>v</code></dt>
+            <dd>one or more <a>property values</a>. If <code>match_type</code> is <code>name</code>, then this value is to
+                be matched to entity names, otherwise to the property values via the supplied <code>pid</code>. The specifics of how this similarity
+                is defined are determined by the service.</dd> 
+            <dt><code>required</code></dt>
+            <dd>An optional boolean indicating if a match for the property is required for an entity to enter the list of candidates (i.e. acting like a filter or a WHERE clause in SQL)
+              or optional (i.e. only effecting the entity's rank in the list of candidates);</dd>
+            <dt><code>match_quantifier</code></dt>
+            <dd>An optional string to indicate which of the values in <code>v</code> to match. MUST be <code>any</code> (equivalent to boolean OR), <code>all</code> (equivalent to boolean AND), or <code>none</code> (equivalent to boolean NOT);</dd>
+            <dt><code>match_qualifier</code></dt>
+            <dd>An optional string to indicate how to match the values in <code>v</code>.
+              This can be used for general matching relations like "skos:exactMatch", "skos:closeMatch", etc. or for specific features like spatial matching with geo data
+              (e.g. containment search with "schema:containsPlace" etc.) or custom matching on date fields (e.g. services supporting the [[EDTF]] specification could use "EDTF:Level-0" etc.
+              To allow discovery of supported qualifiers by clients, services that support <code>match_qualifier</code> MUST return the supported <code>match_qualifiers</code> for each property
+              in their property <a href='#suggest-responses'>suggest responses</a>.</p></dd>
+         </dl>
+
+	    A reconciliation service that supports property assignments SHOULD provide a <a>suggest service</a> for discovering these properties. If the optional fields are omitted, the exact behavior ("must match all", "should match some", etc.) is up to the service.
         </p>
         <p>
           A <dfn>reconciliation query batch</dfn> is an array of <a>reconciliation queries</a>.