From b11a5f03bc451f41031d7a817a4adab033b5ddd4 Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Thu, 10 Nov 2022 15:46:23 +0100 Subject: [PATCH] Change the format of reconciliation queries, responses and data extension responses (#92) * Change the format of reconciliation queries, responses and data extension responses. This removes the use of arbitrary keys in JSON objects. As a result we are no longer using "patternProperties" in our own JSON schemas. Closes #33. * Reformat wront-properties.json * Avoid JSON responses with a root array: wrap them in an object * Rename 'result' field to 'candidates' in reconciliation response --- .../invalid/wrong-properties.json | 46 ++-- .../valid/example-full.json | 112 +++++---- .../invalid/empty-properties.json | 8 +- .../invalid/empty-query.json | 8 +- .../invalid/misnamed-property.json | 68 +++--- .../invalid/no-root-object.json | 8 + .../invalid/old-format.json | 11 + .../valid/example-full.json | 68 +++--- .../valid/example-min.json | 16 +- .../valid/multi-values.json | 38 +-- .../valid/no-query-string.json | 8 +- .../invalid/missing-id.json | 40 ++-- .../invalid/no-result.json | 4 +- .../invalid/root-array.json | 68 +++--- .../valid/example-full.json | 226 +++++++++--------- latest/index.html | 7 +- latest/schemas/data-extension-response.json | 173 ++++++++------ .../schemas/reconciliation-query-batch.json | 161 +++++++------ .../schemas/reconciliation-result-batch.json | 179 +++++++------- 19 files changed, 680 insertions(+), 569 deletions(-) create mode 100644 latest/examples/reconciliation-query-batch/invalid/no-root-object.json create mode 100644 latest/examples/reconciliation-query-batch/invalid/old-format.json diff --git a/latest/examples/data-extension-response/invalid/wrong-properties.json b/latest/examples/data-extension-response/invalid/wrong-properties.json index 993d9f4..caffc8d 100644 --- a/latest/examples/data-extension-response/invalid/wrong-properties.json +++ b/latest/examples/data-extension-response/invalid/wrong-properties.json @@ -17,26 +17,38 @@ } } ], - "rows": { - "10662041X": { - "variantName": [ + "rows": [ + { + "id": "10662041X", + "properties": [ { - "label": "Stryi-Leitgeb, Gerda" - } - ], - "geographicAreaCode": [ + "id": "variantName", + "values": [ + { + "label": "Stryi-Leitgeb, Gerda" + } + ] + }, { - "str": "http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE", - "label": "Deutschland" - } - ], - "professionOrOccupation": [ + "id": "geographicAreaCode", + "values": [ + { + "str": "http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE", + "label": "Deutschland" + } + ] + }, { - "id": "4037223-6", - "name": "Malerin", - "type": "Person" + "id": "professionOrOccupation", + "values": [ + { + "id": "4037223-6", + "name": "Malerin", + "type": "Person" + } + ] } ] } - } -} \ No newline at end of file + ] +} diff --git a/latest/examples/data-extension-response/valid/example-full.json b/latest/examples/data-extension-response/valid/example-full.json index bd5ed82..8d03205 100644 --- a/latest/examples/data-extension-response/valid/example-full.json +++ b/latest/examples/data-extension-response/valid/example-full.json @@ -22,60 +22,90 @@ "service": "https://www.wikidata.org/api/reconcile" } ], - "rows": { - "10662041X": { - "variantName": [ + "rows": [ + { + "id": "10662041X", + "properties": [ { - "str": "Stryi-Leitgeb, Gerda" + "id": "variantName", + "values": [ + { + "str": "Stryi-Leitgeb, Gerda" + }, + { + "str": "Leitgeb, Gerda Stryi-" + } + ] }, { - "str": "Leitgeb, Gerda Stryi-" - } - ], - "geographicAreaCode": [ - { - "str": "http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE" - } - ], - "professionOrOccupation": [ - { - "id": "4037223-6", - "name": "Malerin", - "description": "Beruf" + "id": "geographicAreaCode", + "values": [ + { + "str": "http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE" + } + ] }, { - "id": "4033430-2", - "name": "Künstlerin" - } - ], - "wikidataId": [ + "id": "professionOrOccupation", + "values": [ + { + "id": "4037223-6", + "name": "Malerin", + "description": "Beruf" + }, + { + "id": "4033430-2", + "name": "Künstlerin" + } + ] + }, { - "id": "Q3874347", - "name": "Gerda Stryi-Leitgeb" + "id": "wikidataId", + "values": [ + { + "id": "Q3874347", + "name": "Gerda Stryi-Leitgeb" + } + ] } ] }, - "1064905412": { - "variantName": [ - {} - ], - "geographicAreaCode": [ + { + "id": "1064905412", + "properties": [ { - "str": "http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE" - } - ], - "professionOrOccupation": [ + "id": "variantName", + "values": [ + {} + ] + }, { - "id": "4002844-6", - "name": "Architekt" - } - ], - "wikidataId": [ + "id": "geographicAreaCode", + "values": [ + { + "str": "http://d-nb.info/standards/vocab/gnd/geographic-area-code#XA-DE" + } + ] + }, + { + "id": "professionOrOccupation", + "values": [ + { + "id": "4002844-6", + "name": "Architekt" + } + ] + }, { - "id": "Q3874347", - "name": "Gerda Stryi-Leitgeb" + "id": "wikidataId", + "values": [ + { + "id": "Q3874347", + "name": "Gerda Stryi-Leitgeb" + } + ] } ] } - } + ] } diff --git a/latest/examples/reconciliation-query-batch/invalid/empty-properties.json b/latest/examples/reconciliation-query-batch/invalid/empty-properties.json index 2607452..c2c6072 100644 --- a/latest/examples/reconciliation-query-batch/invalid/empty-properties.json +++ b/latest/examples/reconciliation-query-batch/invalid/empty-properties.json @@ -1,5 +1,7 @@ { - "q1": { - "properties": [] - } + "queries": [ + { + "properties": [] + } + ] } diff --git a/latest/examples/reconciliation-query-batch/invalid/empty-query.json b/latest/examples/reconciliation-query-batch/invalid/empty-query.json index ad3f0d4..56adf75 100644 --- a/latest/examples/reconciliation-query-batch/invalid/empty-query.json +++ b/latest/examples/reconciliation-query-batch/invalid/empty-query.json @@ -1,5 +1,7 @@ { - "q1": { - "limit": 1 - } + "queries": [ + { + "limit": 1 + } + ] } diff --git a/latest/examples/reconciliation-query-batch/invalid/misnamed-property.json b/latest/examples/reconciliation-query-batch/invalid/misnamed-property.json index cbdae5f..5781c9a 100644 --- a/latest/examples/reconciliation-query-batch/invalid/misnamed-property.json +++ b/latest/examples/reconciliation-query-batch/invalid/misnamed-property.json @@ -1,34 +1,36 @@ { - "q0": { - "query": "Christel Hanewinckel", - "type": "DifferentiatedPerson", - "limit": 5, - "props": [ - { - "pid": "professionOrOccupation", - "v": "Politik*" - }, - { - "pid": "affiliation", - "v": "http://d-nb.info/gnd/2022139-3" - } - ], - "type_strict": "should" - }, - "q1": { - "query": "Franz Thönnes", - "type": "DifferentiatedPerson", - "limit": 5, - "props": [ - { - "pid": "professionOrOccupation", - "v": "Politik*" - }, - { - "pid": "affiliation", - "v": "http://d-nb.info/gnd/2022139-3" - } - ], - "type_strict": "should" - } -} \ No newline at end of file + "queries": [ + { + "query": "Christel Hanewinckel", + "type": "DifferentiatedPerson", + "limit": 5, + "props": [ + { + "pid": "professionOrOccupation", + "v": "Politik*" + }, + { + "pid": "affiliation", + "v": "http://d-nb.info/gnd/2022139-3" + } + ], + "type_strict": "should" + }, + { + "query": "Franz Thönnes", + "type": "DifferentiatedPerson", + "limit": 5, + "props": [ + { + "pid": "professionOrOccupation", + "v": "Politik*" + }, + { + "pid": "affiliation", + "v": "http://d-nb.info/gnd/2022139-3" + } + ], + "type_strict": "should" + } + ] +} diff --git a/latest/examples/reconciliation-query-batch/invalid/no-root-object.json b/latest/examples/reconciliation-query-batch/invalid/no-root-object.json new file mode 100644 index 0000000..0435777 --- /dev/null +++ b/latest/examples/reconciliation-query-batch/invalid/no-root-object.json @@ -0,0 +1,8 @@ +[ + { + "properties": [{"pid":"uid", "v": "27eb892afbb2"}] + }, + { + "properties": [{"pid":"uid", "v": "ab09da9dd37e"}] + } +] diff --git a/latest/examples/reconciliation-query-batch/invalid/old-format.json b/latest/examples/reconciliation-query-batch/invalid/old-format.json new file mode 100644 index 0000000..521b0e7 --- /dev/null +++ b/latest/examples/reconciliation-query-batch/invalid/old-format.json @@ -0,0 +1,11 @@ +{ + "q0": { + "query": "Christel Hanewinckel", + "limit": 5 + }, + "q1": { + "query": "Franz Thönnes", + "type": "DifferentiatedPerson", + "limit": 5 + } +} diff --git a/latest/examples/reconciliation-query-batch/valid/example-full.json b/latest/examples/reconciliation-query-batch/valid/example-full.json index 9da0b7f..4d36190 100644 --- a/latest/examples/reconciliation-query-batch/valid/example-full.json +++ b/latest/examples/reconciliation-query-batch/valid/example-full.json @@ -1,34 +1,36 @@ { - "q0": { - "query": "Christel Hanewinckel", - "type": "DifferentiatedPerson", - "limit": 5, - "properties": [ - { - "pid": "professionOrOccupation", - "v": "Politik*" - }, - { - "pid": "affiliation", - "v": "http://d-nb.info/gnd/2022139-3" - } - ], - "type_strict": "should" - }, - "q1": { - "query": "Franz Thönnes", - "type": "DifferentiatedPerson", - "limit": 5, - "properties": [ - { - "pid": "professionOrOccupation", - "v": "Politik*" - }, - { - "pid": "affiliation", - "v": "http://d-nb.info/gnd/2022139-3" - } - ], - "type_strict": "should" - } -} \ No newline at end of file + "queries": [ + { + "query": "Christel Hanewinckel", + "type": "DifferentiatedPerson", + "limit": 5, + "properties": [ + { + "pid": "professionOrOccupation", + "v": "Politik*" + }, + { + "pid": "affiliation", + "v": "http://d-nb.info/gnd/2022139-3" + } + ], + "type_strict": "should" + }, + { + "query": "Franz Thönnes", + "type": "DifferentiatedPerson", + "limit": 5, + "properties": [ + { + "pid": "professionOrOccupation", + "v": "Politik*" + }, + { + "pid": "affiliation", + "v": "http://d-nb.info/gnd/2022139-3" + } + ], + "type_strict": "should" + } + ] +} diff --git a/latest/examples/reconciliation-query-batch/valid/example-min.json b/latest/examples/reconciliation-query-batch/valid/example-min.json index 715732d..130e18b 100644 --- a/latest/examples/reconciliation-query-batch/valid/example-min.json +++ b/latest/examples/reconciliation-query-batch/valid/example-min.json @@ -1,8 +1,10 @@ { - "q1": { - "query": "Hans-Eberhard Urbaniak" - }, - "q2": { - "query": "Ernst Schwanhold" - } -} \ No newline at end of file + "queries": [ + { + "query": "Hans-Eberhard Urbaniak" + }, + { + "query": "Ernst Schwanhold" + } + ] +} diff --git a/latest/examples/reconciliation-query-batch/valid/multi-values.json b/latest/examples/reconciliation-query-batch/valid/multi-values.json index 57564e6..654a085 100644 --- a/latest/examples/reconciliation-query-batch/valid/multi-values.json +++ b/latest/examples/reconciliation-query-batch/valid/multi-values.json @@ -1,20 +1,22 @@ { - "q0": { - "query": "Christel Hanewinckel", - "type": "DifferentiatedPerson", - "limit": 5, - "properties": [ - { - "pid": "professionOrOccupation", - "v": [ - "Politik*", - { - "id": "wissenschaftler", - "name": "Wissenschaftler(in)" - } - ] - } - ], - "type_strict": "should" - } + "queries": [ + { + "query": "Christel Hanewinckel", + "type": "DifferentiatedPerson", + "limit": 5, + "properties": [ + { + "pid": "professionOrOccupation", + "v": [ + "Politik*", + { + "id": "wissenschaftler", + "name": "Wissenschaftler(in)" + } + ] + } + ], + "type_strict": "should" + } + ] } diff --git a/latest/examples/reconciliation-query-batch/valid/no-query-string.json b/latest/examples/reconciliation-query-batch/valid/no-query-string.json index 46be918..eb027b4 100644 --- a/latest/examples/reconciliation-query-batch/valid/no-query-string.json +++ b/latest/examples/reconciliation-query-batch/valid/no-query-string.json @@ -1,8 +1,8 @@ -{ - "q1": { +{"queries":[ + { "properties": [{"pid":"uid", "v": "27eb892afbb2"}] }, - "q2": { + { "properties": [{"pid":"uid", "v": "ab09da9dd37e"}] } -} +]} diff --git a/latest/examples/reconciliation-result-batch/invalid/missing-id.json b/latest/examples/reconciliation-result-batch/invalid/missing-id.json index 1cd68b2..f801187 100644 --- a/latest/examples/reconciliation-result-batch/invalid/missing-id.json +++ b/latest/examples/reconciliation-result-batch/invalid/missing-id.json @@ -1,21 +1,23 @@ { - "q1": { - "result": [ - { - "name": "Urbaniak, Regina", - "score": 53.015232, - "match": false, - "type": [ - { - "id": "AuthorityResource", - "name": "Normdatenressource" - }, - { - "id": "DifferentiatedPerson", - "name": "Individualisierte Person" - } - ] - } - ] - } + "results": [ + { + "candidates": [ + { + "name": "Urbaniak, Regina", + "score": 53.015232, + "match": false, + "type": [ + { + "id": "AuthorityResource", + "name": "Normdatenressource" + }, + { + "id": "DifferentiatedPerson", + "name": "Individualisierte Person" + } + ] + } + ] + } + ] } diff --git a/latest/examples/reconciliation-result-batch/invalid/no-result.json b/latest/examples/reconciliation-result-batch/invalid/no-result.json index c1be025..abc2f79 100644 --- a/latest/examples/reconciliation-result-batch/invalid/no-result.json +++ b/latest/examples/reconciliation-result-batch/invalid/no-result.json @@ -1,3 +1,5 @@ { - "q0": {} + "results": [ + {} + ] } diff --git a/latest/examples/reconciliation-result-batch/invalid/root-array.json b/latest/examples/reconciliation-result-batch/invalid/root-array.json index 68d6239..c21935e 100644 --- a/latest/examples/reconciliation-result-batch/invalid/root-array.json +++ b/latest/examples/reconciliation-result-batch/invalid/root-array.json @@ -1,36 +1,38 @@ { - "q1": [ - { - "id": "120333937", - "name": "Urbaniak, Regina", - "score": 53.015232, - "match": false, - "type": [ - { - "id": "AuthorityResource", - "name": "Normdatenressource" - }, - { - "id": "DifferentiatedPerson", - "name": "Individualisierte Person" - } - ] - }, - { - "id": "1127147390", - "name": "Urbaniak, Jan", - "score": 52.357353, - "match": false, - "type": [ - { - "id": "AuthorityResource", - "name": "Normdatenressource" - }, - { - "id": "DifferentiatedPerson", - "name": "Individualisierte Person" - } - ] - } + "results": [ + [ + { + "id": "120333937", + "name": "Urbaniak, Regina", + "score": 53.015232, + "match": false, + "type": [ + { + "id": "AuthorityResource", + "name": "Normdatenressource" + }, + { + "id": "DifferentiatedPerson", + "name": "Individualisierte Person" + } + ] + }, + { + "id": "1127147390", + "name": "Urbaniak, Jan", + "score": 52.357353, + "match": false, + "type": [ + { + "id": "AuthorityResource", + "name": "Normdatenressource" + }, + { + "id": "DifferentiatedPerson", + "name": "Individualisierte Person" + } + ] + } + ] ] } diff --git a/latest/examples/reconciliation-result-batch/valid/example-full.json b/latest/examples/reconciliation-result-batch/valid/example-full.json index 2a8855e..e0c422d 100644 --- a/latest/examples/reconciliation-result-batch/valid/example-full.json +++ b/latest/examples/reconciliation-result-batch/valid/example-full.json @@ -1,114 +1,116 @@ { - "q1": { - "result": [ - { - "id": "120333937", - "name": "Urbaniak, Regina", - "description": "1969-| Diss. Fachbereich Mathematik", - "score": 53.015232, - "match": false, - "features": [ - { - "id": "name_tfidf", - "value": 378.239 - }, - { - "id": "pagerank", - "value": -3.1209 - }, - { - "id": "type_match", - "value": 10.329 - }, - { - "id": "deprecated", - "value": false - } - ], - "type": [ - { - "id": "AuthorityResource", - "name": "Normdatenressource" - }, - { - "id": "DifferentiatedPerson", - "name": "Individualisierte Person" - } - ] - }, - { - "id": "1127147390", - "name": "Urbaniak, Jan", - "description": "Universität Wrocław, Niederlandestudien", - "score": 52.357353, - "match": false, - "type": [ - { - "id": "AuthorityResource", - "name": "Normdatenressource" - }, - { - "id": "DifferentiatedPerson", - "name": "Individualisierte Person" - } - ] - } - ] - }, - "q2": { - "result": [ - { - "id": "123064325", - "name": "Schwanhold, Ernst", - "description": "1948-| Mitglied des Deutschen Bundestages, SPD (1993)", - "score": 86.43497, - "features": [ - { - "id": "name_tfidf", - "value": 334.188 - }, - { - "id": "pagerank", - "value": -4.1581 - }, - { - "id": "type_match", - "value": 13.78 - }, - { - "id": "deprecated", - "value": false - } - ], - "match": true, - "type": [ - { - "id": "AuthorityResource", - "name": "Normdatenressource" - }, - { - "id": "DifferentiatedPerson", - "name": "Individualisierte Person" - } - ] - }, - { - "id": "116362988X", - "name": "Schwanhold, Nadine", - "description": "Dissertation Potsdam, Universität, Mathematik-Naturwissenschaftliche Fakultät, 2017", - "score": 62.04763, - "match": false, - "type": [ - { - "id": "AuthorityResource", - "name": "Normdatenressource" - }, - { - "id": "DifferentiatedPerson", - "name": "Individualisierte Person" - } - ] - } - ] - } + "results": [ + { + "candidates": [ + { + "id": "120333937", + "name": "Urbaniak, Regina", + "description": "1969-| Diss. Fachbereich Mathematik", + "score": 53.015232, + "match": false, + "features": [ + { + "id": "name_tfidf", + "value": 378.239 + }, + { + "id": "pagerank", + "value": -3.1209 + }, + { + "id": "type_match", + "value": 10.329 + }, + { + "id": "deprecated", + "value": false + } + ], + "type": [ + { + "id": "AuthorityResource", + "name": "Normdatenressource" + }, + { + "id": "DifferentiatedPerson", + "name": "Individualisierte Person" + } + ] + }, + { + "id": "1127147390", + "name": "Urbaniak, Jan", + "description": "Universität Wrocław, Niederlandestudien", + "score": 52.357353, + "match": false, + "type": [ + { + "id": "AuthorityResource", + "name": "Normdatenressource" + }, + { + "id": "DifferentiatedPerson", + "name": "Individualisierte Person" + } + ] + } + ] + }, + { + "candidates": [ + { + "id": "123064325", + "name": "Schwanhold, Ernst", + "description": "1948-| Mitglied des Deutschen Bundestages, SPD (1993)", + "score": 86.43497, + "features": [ + { + "id": "name_tfidf", + "value": 334.188 + }, + { + "id": "pagerank", + "value": -4.1581 + }, + { + "id": "type_match", + "value": 13.78 + }, + { + "id": "deprecated", + "value": false + } + ], + "match": true, + "type": [ + { + "id": "AuthorityResource", + "name": "Normdatenressource" + }, + { + "id": "DifferentiatedPerson", + "name": "Individualisierte Person" + } + ] + }, + { + "id": "116362988X", + "name": "Schwanhold, Nadine", + "description": "Dissertation Potsdam, Universität, Mathematik-Naturwissenschaftliche Fakultät, 2017", + "score": 62.04763, + "match": false, + "type": [ + { + "id": "AuthorityResource", + "name": "Normdatenressource" + }, + { + "id": "DifferentiatedPerson", + "name": "Individualisierte Person" + } + ] + } + ] + } + ] } diff --git a/latest/index.html b/latest/index.html index e4ab0d6..672ddc9 100644 --- a/latest/index.html +++ b/latest/index.html @@ -496,7 +496,7 @@

Structure of a Reconciliation Query

- A reconciliation query batch is a set of reconciliation queries indexed by string identifiers. + A reconciliation query batch is an array of reconciliation queries.

Minimal example of a reconciliation query batch with mandatory fields only: @@ -560,10 +560,11 @@

Reconciliation Query Responses

A reconciliation result is a set of reconciliation candidates. It is serialized in JSON - as an array of such reconciliation candidate objects. This array SHOULD be sorted by decreasing score. + as an object containing in the field candidates an array of such reconciliation candidate objects. This array SHOULD be sorted by decreasing score.

- A reconciliation result batch is a set of reconciliation results indexed by string identifiers of the corresponding reconciliation query batch. + A reconciliation result batch is an array of reconciliation results given in the same order as in the corresponding reconciliation query batch. + When serialized in JSON, it is wrapped in an object under the results field.

Full example of a reconciliation result batch: diff --git a/latest/schemas/data-extension-response.json b/latest/schemas/data-extension-response.json index 3dfe3a8..49a20c8 100644 --- a/latest/schemas/data-extension-response.json +++ b/latest/schemas/data-extension-response.json @@ -42,89 +42,104 @@ } }, "rows": { - "type": "object", - "patternProperties": { - ".*": { - "type": "object", - "patternProperties": { - ".*": { - "type": "array", - "items": { - "oneOf": [ - { - "type": "object", - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "id": { - "type": "string" + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "An entity identifier supplied in the query" + }, + "properties": { + "type": "array", + "description": "The list of property values for this entity", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "A property identifier supplied in the query" + }, + "values": { + "type": "array", + "items": { + "oneOf": [ + { + "type": "object", + "additionalProperties": false }, - "name": { - "type": "string" + { + "type": "object", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + }, + "description": { + "type": "string" + } + }, + "required": [ + "id", + "name" + ], + "additionalProperties": false }, - "description": { - "type": "string" - } - }, - "required": [ - "id", - "name" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "str": { - "type": "string" - } - }, - "required": [ - "str" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "float": { - "type": "number" - } - }, - "required": [ - "float" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "int": { - "type": "integer" - } - }, - "required": [ - "int" - ], - "additionalProperties": false - }, - { - "type": "object", - "properties": { - "date": { - "type": "string", - "description": "Date and time formatted in ISO format", - "pattern": "^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]+)?(Z|[+-](?:2[0-3]|[01][0-9]):[0-5][0-9])?$" + { + "type": "object", + "properties": { + "str": { + "type": "string" + } + }, + "required": [ + "str" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "float": { + "type": "number" + } + }, + "required": [ + "float" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "int": { + "type": "integer" + } + }, + "required": [ + "int" + ], + "additionalProperties": false + }, + { + "type": "object", + "properties": { + "date": { + "type": "string", + "description": "Date and time formatted in ISO format", + "pattern": "^(-?(?:[1-9][0-9]*)?[0-9]{4})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])T(2[0-3]|[01][0-9]):([0-5][0-9]):([0-5][0-9])(\\.[0-9]+)?(Z|[+-](?:2[0-3]|[01][0-9]):[0-5][0-9])?$" + } + }, + "required": [ + "date" + ], + "additionalProperties": false } - }, - "required": [ - "date" - ], - "additionalProperties": false + ] } - ] + } } } } diff --git a/latest/schemas/reconciliation-query-batch.json b/latest/schemas/reconciliation-query-batch.json index dc332b9..92f6545 100644 --- a/latest/schemas/reconciliation-query-batch.json +++ b/latest/schemas/reconciliation-query-batch.json @@ -2,7 +2,7 @@ "$schema": "http://json-schema.org/schema#", "$id": "https://reconciliation-api.github.io/specs/latest/schemas/reconciliation-query.json", "type": "object", - "description": "This schema validates the JSON serialization of any reconciliation query batch, i.e. the payload of a GET/POST to a reconciliation endpoint.", + "description": "This schema validates the JSON serialization of any reconciliation query batch, i.e. the payload of a POST to a reconciliation endpoint.", "definitions": { "property_value": { "oneOf": [ @@ -33,92 +33,99 @@ ] } }, - "patternProperties": { - "^.*$": { - "type": "object", - "properties": { - "query": { - "type": "string", - "description": "A string to be matched against the name of the entities" - }, - "type": { - "description": "Either a single type identifier or a list of type identifiers", - "oneOf": [ - { - "type": "string" - }, - { - "type": "array", - "items": { - "type": "string" - } - } - ] - }, - "limit": { - "type": "number", - "description": "The maximum number of candidates to return" - }, + "required": [ + "queries" + ], + "properties": { + "queries": { + "type": "array", + "description": "A list of queries to be processed by the service", + "items": { + "type": "object", "properties": { - "type": "array", - "description": "An optional list of property mappings to refine the query", - "items": { - "type": "object", - "properties": { - "pid": { - "type": "string", - "description": "The identifier of the property, whose values will be compared to the values supplied" + "query": { + "type": "string", + "description": "A string to be matched against the name of the entities" + }, + "type": { + "description": "Either a single type identifier or a list of type identifiers", + "oneOf": [ + { + "type": "string" }, - "v": { - "description": "A value (or array of values) to match against the property values associated with the property on each candidate", - "oneOf": [ - { - "$ref": "#/definitions/property_value" - }, - { - "type": "array", - "items": { + { + "type": "array", + "items": { + "type": "string" + } + } + ] + }, + "limit": { + "type": "number", + "description": "The maximum number of candidates to return" + }, + "properties": { + "type": "array", + "description": "An optional list of property mappings to refine the query", + "items": { + "type": "object", + "properties": { + "pid": { + "type": "string", + "description": "The identifier of the property, whose values will be compared to the values supplied" + }, + "v": { + "description": "A value (or array of values) to match against the property values associated with the property on each candidate", + "oneOf": [ + { "$ref": "#/definitions/property_value" + }, + { + "type": "array", + "items": { + "$ref": "#/definitions/property_value" + } } - } - ] - } - }, - "required": [ - "pid", - "v" + ] + } + }, + "required": [ + "pid", + "v" + ] + } + }, + "type_strict": { + "type": "string", + "description": "A classification of the type matching strategy when multiple types are supplied", + "enum": [ + "any", + "should", + "all" ] } }, - "type_strict": { - "type": "string", - "description": "A classification of the type matching strategy when multiple types are supplied", - "enum": [ - "any", - "should", - "all" - ] - } - }, - "anyOf": [ - { - "required": [ - "query" - ] - }, - { - "required": [ - "properties" - ], - "properties": { + "anyOf": [ + { + "required": [ + "query" + ] + }, + { + "required": [ + "properties" + ], "properties": { - "type": "array", - "minItems": 1 + "properties": { + "type": "array", + "minItems": 1 + } } } - } - ], - "additionalProperties": false + ], + "additionalProperties": false + } } } } diff --git a/latest/schemas/reconciliation-result-batch.json b/latest/schemas/reconciliation-result-batch.json index 5c4e558..427a813 100644 --- a/latest/schemas/reconciliation-result-batch.json +++ b/latest/schemas/reconciliation-result-batch.json @@ -3,98 +3,105 @@ "$id": "https://reconciliation-api.github.io/specs/latest/schemas/reconciliation-result-batch.json", "type": "object", "description": "This schema can be used to validate the JSON serialization of any reconciliation result batch.", - "patternProperties": { - "^.*$": { - "type": "object", - "properties": { - "result": { - "type": "array", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "Entity identifier of the candidate" - }, - "name": { - "type": "string", - "description": "Entity name of the candidate" - }, - "description": { - "type": "string", - "description": "Optional description of the candidate entity" - }, - "score": { - "type": "number", - "description": "Number indicating how likely it is that the candidate matches the query" - }, - "features": { - "type": "array", - "description": "A list of features which can be used to derive a matching score", - "items": { - "type": "object", - "properties": { - "id": { - "type": "string", - "description": "A unique string identifier for the feature" - }, - "value": { - "description": "The value of the feature for this reconciliation candidate", - "oneOf": [ - { - "type": "boolean" - }, - { - "type": "number" - } - ] + "required": [ + "results" + ], + "properties": { + "results": { + "type": "array", + "description": "The list of candidates for each reconciliation query, in the same order", + "items": { + "type": "object", + "properties": { + "candidates": { + "type": "array", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "Entity identifier of the candidate" + }, + "name": { + "type": "string", + "description": "Entity name of the candidate" + }, + "description": { + "type": "string", + "description": "Optional description of the candidate entity" + }, + "score": { + "type": "number", + "description": "Number indicating how likely it is that the candidate matches the query" + }, + "features": { + "type": "array", + "description": "A list of features which can be used to derive a matching score", + "items": { + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "A unique string identifier for the feature" + }, + "value": { + "description": "The value of the feature for this reconciliation candidate", + "oneOf": [ + { + "type": "boolean" + }, + { + "type": "number" + } + ] + } } } - } - }, - "match": { - "type": "boolean", - "description": "Boolean value indicating whether the candiate is a certain match or not." - }, - "type": { - "type": "array", - "description": "Types the candidate entity belongs to", - "items": { - "oneOf": [ - { - "type": "object", - "description": "A type can be given by id and name", - "properties": { - "id": { - "type": "string" + }, + "match": { + "type": "boolean", + "description": "Boolean value indicating whether the candiate is a certain match or not." + }, + "type": { + "type": "array", + "description": "Types the candidate entity belongs to", + "items": { + "oneOf": [ + { + "type": "object", + "description": "A type can be given by id and name", + "properties": { + "id": { + "type": "string" + }, + "name": { + "type": "string" + } }, - "name": { - "type": "string" - } + "required": [ + "id" + ] }, - "required": [ - "id" - ] - }, - { - "type": "string", - "description": "Alternatively, if only a string is given, it is treated as the id" - } - ] + { + "type": "string", + "description": "Alternatively, if only a string is given, it is treated as the id" + } + ] + } } - } - }, - "required": [ - "id", - "name", - "score" - ] + }, + "required": [ + "id", + "name", + "score" + ] + } } - } - }, - "required": [ - "result" - ] + }, + "required": [ + "candidates" + ] + } } } }