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 @@
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
conditions
type
limit
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
match_quantifier
v
to match. MUST be "any" (equivalent to boolean OR), "all" (equivalent to boolean AND), or "none" (equivalent to boolean NOT);match_qualifier
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 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
name
or property
, depending on whether the condition relates to entity names or their properties.pid
match_type
is property
.v
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
match_quantifier
v
to match. MUST be any
(equivalent to boolean OR), all
(equivalent to boolean AND), or none
(equivalent to boolean NOT);match_qualifier
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 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 }