diff --git a/draft/examples/reconciliation-query-batch/invalid/empty-properties.json b/draft/examples/reconciliation-query-batch/invalid/empty-conditions.json similarity index 60% rename from draft/examples/reconciliation-query-batch/invalid/empty-properties.json rename to draft/examples/reconciliation-query-batch/invalid/empty-conditions.json index c2c6072..e60930d 100644 --- a/draft/examples/reconciliation-query-batch/invalid/empty-properties.json +++ b/draft/examples/reconciliation-query-batch/invalid/empty-conditions.json @@ -1,7 +1,7 @@ { "queries": [ { - "properties": [] + "conditions": [] } ] } diff --git a/draft/examples/reconciliation-query-batch/invalid/misnamed-property.json b/draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json similarity index 85% rename from draft/examples/reconciliation-query-batch/invalid/misnamed-property.json rename to draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json index 5781c9a..f51e78e 100644 --- a/draft/examples/reconciliation-query-batch/invalid/misnamed-property.json +++ b/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*" diff --git a/draft/examples/reconciliation-query-batch/invalid/missing-match-type.json b/draft/examples/reconciliation-query-batch/invalid/missing-match-type.json new file mode 100644 index 0000000..843c25c --- /dev/null +++ b/draft/examples/reconciliation-query-batch/invalid/missing-match-type.json @@ -0,0 +1,18 @@ +{ + "queries": [ + { + "conditions": [ + { + "v": "Hans-Eberhard Urbaniak" + } + ] + }, + { + "conditions": [ + { + "v": "Ernst Schwanhold" + } + ] + } + ] +} diff --git a/draft/examples/reconciliation-query-batch/invalid/multiple-types.json b/draft/examples/reconciliation-query-batch/invalid/multiple-types.json index b2a0f8d..d2f3fb7 100644 --- a/draft/examples/reconciliation-query-batch/invalid/multiple-types.json +++ b/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 } ] diff --git a/draft/examples/reconciliation-query-batch/invalid/no-root-object.json b/draft/examples/reconciliation-query-batch/invalid/no-root-object.json index 0435777..143d568 100644 --- a/draft/examples/reconciliation-query-batch/invalid/no-root-object.json +++ b/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" + } + ] } ] diff --git a/draft/examples/reconciliation-query-batch/valid/example-full.json b/draft/examples/reconciliation-query-batch/valid/example-full.json index eb3b33f..6c61a09 100644 --- a/draft/examples/reconciliation-query-batch/valid/example-full.json +++ b/draft/examples/reconciliation-query-batch/valid/example-full.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*", "required": false, @@ -13,6 +17,7 @@ "match_qualifier": "WildcardMatch" }, { + "match_type": "property", "pid": "affiliation", "v": "http://d-nb.info/gnd/2022139-3", "required": false, @@ -22,11 +27,15 @@ ] }, { - "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, @@ -34,6 +43,7 @@ "match_qualifier": "WildcardMatch" }, { + "match_type": "property", "pid": "affiliation", "v": "http://d-nb.info/gnd/2022139-3", "required": false, diff --git a/draft/examples/reconciliation-query-batch/valid/example-min.json b/draft/examples/reconciliation-query-batch/valid/example-min.json index 130e18b..8d5d776 100644 --- a/draft/examples/reconciliation-query-batch/valid/example-min.json +++ b/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" + } + ] } ] } diff --git a/draft/examples/reconciliation-query-batch/valid/multi-values.json b/draft/examples/reconciliation-query-batch/valid/multi-values.json index aec03de..f4ba3b2 100644 --- a/draft/examples/reconciliation-query-batch/valid/multi-values.json +++ b/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*", diff --git a/draft/examples/reconciliation-query-batch/valid/no-query-string.json b/draft/examples/reconciliation-query-batch/valid/no-query-string.json index eb027b4..ee78785 100644 --- a/draft/examples/reconciliation-query-batch/valid/no-query-string.json +++ b/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" + } + ] + } + ] +} diff --git a/draft/examples/reconciliation-query-batch/valid/text-processing-language.json b/draft/examples/reconciliation-query-batch/valid/text-processing-language.json index c16ce91..dda0f9b 100644 --- a/draft/examples/reconciliation-query-batch/valid/text-processing-language.json +++ b/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" diff --git a/draft/index.html b/draft/index.html index d94a8f7..a9923b4 100644 --- a/draft/index.html +++ b/draft/index.html @@ -481,42 +481,46 @@

Reconciliation Queries

Structure of a Reconciliation Query

A reconciliation query consists of the following fields. - At least one of query or properties must be supplied, but all other - fields are optional.

-
query
-
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.
+
conditions
+
An array of conditions (at least one).
type
-
A type identifier. Supplying such a type allows users to restrict +
An optional type 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;
limit
-
A limit on the number of candidates to return, which must be a positive integer;
-
properties
-

An array of objects, where each object maps a property identifier (in the pid field) to one or more property values (in the v 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 query field. - A reconciliation service that supports properties SHOULD provide a suggest service for discovering these properties.

-

In addition to pid and v, 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.

-
-
required
-
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);
-
match_quantifier
-
A string to indicate which of the values in v to match. MUST be "any" (equivalent to boolean OR), "all" (equivalent to boolean AND), or "none" (equivalent to boolean NOT);
-
match_qualifier
-
A string to indicate how to match the values in v. - 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 match_qualifier MUST return the supported match_qualifiers for each property - in their property suggest responses.

-
-
-
+
An optional limit on the number of candidates to return, which must be a positive integer;
+ +

+

+ A condition 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: +

+
match_type
+
Either name or property, depending on whether the condition relates to entity names or their properties.
+
pid
+
A property identifier, to be provided if and only if the match_type is property.
+
v
+
one or more property values. If match_type is name, then this value is to + be matched to entity names, otherwise to the property values via the supplied pid. The specifics of how this similarity + is defined are determined by the service.
+
required
+
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);
+
match_quantifier
+
An optional string to indicate which of the values in v to match. MUST be any (equivalent to boolean OR), all (equivalent to boolean AND), or none (equivalent to boolean NOT);
+
match_qualifier
+
An optional string to indicate how to match the values in v. + 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 match_qualifier MUST return the supported match_qualifiers for each property + in their property suggest responses.

+
+ + A reconciliation service that supports property assignments SHOULD provide a suggest service 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.

A reconciliation query batch is an array of reconciliation queries. diff --git a/draft/schemas/reconciliation-query-batch.json b/draft/schemas/reconciliation-query-batch.json index daedf37..7bfe4ae 100644 --- 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" @@ -59,18 +55,27 @@ "type": "string", "description": "The text-processing language for the query" }, - "properties": { + "conditions": { "type": "array", - "description": "An optional list of property mappings to refine the query", + "minItems": 1, + "description": "A list of conditions to select candidates", "items": { "type": "object", "properties": { + "match_type": { + "type": "string", + "description": "A string to indicate whether to match the supplied value to entity names or property values", + "enum": [ + "name", + "property" + ] + }, "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. Required if 'match_type' is 'property'." }, "v": { - "description": "A value (or array of values) to match against the property values associated with the property on each candidate", + "description": "A value (or array of values) to match against the entity names or property values associated with the property on each candidate", "oneOf": [ { "$ref": "#/definitions/property_value" @@ -85,7 +90,7 @@ }, "required": { "type": "boolean", - "description": "A boolean indicating if a match for the property is required for an entity to enter the list of candidates" + "description": "A boolean indicating if a match of this condition is required for an entity to enter the list of candidates" }, "match_quantifier": { "type": "string", @@ -102,7 +107,7 @@ } }, "required": [ - "pid", + "match_type", "v" ] } @@ -117,23 +122,8 @@ ] } }, - "anyOf": [ - { - "required": [ - "query" - ] - }, - { - "required": [ - "properties" - ], - "properties": { - "properties": { - "type": "array", - "minItems": 1 - } - } - } + "required": [ + "conditions" ], "additionalProperties": false }