From 8524de9644577e3b3027be5716f017b4a08867f3 Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Thu, 14 Dec 2023 10:26:29 +0100 Subject: [PATCH 01/16] Move 'query' field inside 'properties' Closes #134. Closes #106. --- .../invalid/misnamed-property.json | 8 +++-- .../invalid/multiple-types.json | 11 ++++-- .../valid/example-full.json | 8 +++-- .../valid/example-min.json | 12 +++++-- .../valid/multi-values.json | 4 ++- .../valid/text-processing-language.json | 4 ++- draft/index.html | 34 +++++++++++-------- draft/schemas/reconciliation-query-batch.json | 29 +++------------- 8 files changed, 62 insertions(+), 48 deletions(-) diff --git a/draft/examples/reconciliation-query-batch/invalid/misnamed-property.json b/draft/examples/reconciliation-query-batch/invalid/misnamed-property.json index 5781c9a..f51e78e 100644 --- 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 index b2a0f8d..ee00a4e 100644 --- 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 index 5ddacf5..fc2c6fa 100644 --- 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 index 130e18b..785eda3 100644 --- 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 index aec03de..caaa898 100644 --- 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 index c16ce91..2f67c31 100644 --- 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 index 4fde551..9405e10 100644 --- a/draft/index.html +++ b/draft/index.html @@ -478,29 +478,35 @@

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.
+
properties
+
An array of property assignments (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 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 query 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 suggest service for discovering these properties;
+
An optional limit on the number of candidates to return, which must be a positive integer;

+

+ A property assignment 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: +

+
pid
+
A property 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.
+
v
+
one or more property values. +
+ + 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 suggest service for discovering these properties. +

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 b2c967e..a776908 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" @@ -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 } From 68186b00f9340777c7a7bc526d7b1e22ff5908e2 Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Mon, 26 Feb 2024 12:10:32 +0100 Subject: [PATCH 02/16] Introduce match_type as suggested by Osma --- ...-properties.json => empty-conditions.json} | 2 +- ...property.json => misnamed-conditions.json} | 0 .../invalid/missing-match-type.json | 18 +++++++++++ .../invalid/multiple-types.json | 3 +- .../invalid/no-root-object.json | 16 ++++++++-- .../valid/example-full.json | 10 +++++-- .../valid/example-min.json | 6 ++-- .../valid/multi-values.json | 4 ++- .../valid/no-query-string.json | 30 ++++++++++++++----- .../valid/text-processing-language.json | 5 +++- draft/index.html | 18 ++++++----- draft/schemas/reconciliation-query-batch.json | 21 +++++++++---- 12 files changed, 101 insertions(+), 32 deletions(-) rename draft/examples/reconciliation-query-batch/invalid/{empty-properties.json => empty-conditions.json} (60%) rename draft/examples/reconciliation-query-batch/invalid/{misnamed-property.json => misnamed-conditions.json} (100%) create mode 100644 draft/examples/reconciliation-query-batch/invalid/missing-match-type.json 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 100% rename from draft/examples/reconciliation-query-batch/invalid/misnamed-property.json rename to draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json 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 ee00a4e..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,9 @@ { "queries": [ { - "properties": [ + "conditions": [ { + "match_type": "name", "v": "Christel Hanewinckel" } ], 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 2e20c2a..6c61a09 100644 --- a/draft/examples/reconciliation-query-batch/valid/example-full.json +++ b/draft/examples/reconciliation-query-batch/valid/example-full.json @@ -3,11 +3,13 @@ { "type": "DifferentiatedPerson", "limit": 5, - "properties": [ + "conditions": [ { + "match_type": "name", "v": "Christel Hanewinckel" }, { + "match_type": "property", "pid": "professionOrOccupation", "v": "Politik*", "required": false, @@ -15,6 +17,7 @@ "match_qualifier": "WildcardMatch" }, { + "match_type": "property", "pid": "affiliation", "v": "http://d-nb.info/gnd/2022139-3", "required": false, @@ -26,11 +29,13 @@ { "type": "DifferentiatedPerson", "limit": 5, - "properties": [ + "conditions": [ { + "match_type": "name", "v": "Franz Thönnes" }, { + "match_type": "property", "pid": "professionOrOccupation", "v": "Politik*", "required": false, @@ -38,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 785eda3..8d5d776 100644 --- a/draft/examples/reconciliation-query-batch/valid/example-min.json +++ b/draft/examples/reconciliation-query-batch/valid/example-min.json @@ -1,15 +1,17 @@ { "queries": [ { - "properties": [ + "conditions": [ { + "match_type": "name", "v": "Hans-Eberhard Urbaniak" } ] }, { - "properties": [ + "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 caaa898..f4ba3b2 100644 --- a/draft/examples/reconciliation-query-batch/valid/multi-values.json +++ b/draft/examples/reconciliation-query-batch/valid/multi-values.json @@ -3,11 +3,13 @@ { "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 2f67c31..dda0f9b 100644 --- a/draft/examples/reconciliation-query-batch/valid/text-processing-language.json +++ b/draft/examples/reconciliation-query-batch/valid/text-processing-language.json @@ -2,15 +2,18 @@ "queries": [ { "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 19d0991..021f10b 100644 --- a/draft/index.html +++ b/draft/index.html @@ -482,8 +482,8 @@

Structure of a Reconciliation Query

A reconciliation query consists of the following fields.

-
properties
-
An array of property assignments (at least one).
+
conditions
+
An array of conditions (at least one).
type
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 @@ -495,16 +495,18 @@

Structure of a Reconciliation Query

- A property assignment 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), + 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 related to entity names or their properties.
pid
-
A property 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.
+
A property identifier, to be provided if and only if the match_type is property.
v
-
one or more property values. +
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);
diff --git a/draft/schemas/reconciliation-query-batch.json b/draft/schemas/reconciliation-query-batch.json index 03a4af6..7bfe4ae 100644 --- a/draft/schemas/reconciliation-query-batch.json +++ b/draft/schemas/reconciliation-query-batch.json @@ -55,19 +55,27 @@ "type": "string", "description": "The text-processing language for the query" }, - "properties": { + "conditions": { "type": "array", "minItems": 1, - "description": "A list of property mappings to select candidates", + "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. If absent, values will be matched against the entity names" + "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" @@ -82,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", @@ -99,6 +107,7 @@ } }, "required": [ + "match_type", "v" ] } @@ -114,7 +123,7 @@ } }, "required": [ - "properties" + "conditions" ], "additionalProperties": false } From 23ab4bbd67235bc6ebb6fbdf87013c1320ec371c Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Mon, 26 Feb 2024 12:21:52 +0100 Subject: [PATCH 03/16] Add netlify link, for #153 --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index b134fde..845f8b4 100644 --- a/README.md +++ b/README.md @@ -22,6 +22,8 @@ for editor metadata). This specification is developed using [ReSpec](https://github.com/w3c/respec) and help about its markup can be found in its [user guide](https://github.com/w3c/respec/wiki/ReSpec-Editor's-Guide). +Deploy previews on pull requests are provided by [Netlify](https://www.netlify.com/). + Local setup ----------- From c5a7bbb8301c80d1dc96661f60cf81a3a4ce496c Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Thu, 14 Mar 2024 11:53:05 +0100 Subject: [PATCH 04/16] Add optional `standardizedScore` field in service manifest (#147) --- draft/examples/manifest/valid/wikidata.json | 3 ++- draft/index.html | 4 +++- draft/schemas/manifest.json | 4 ++++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/draft/examples/manifest/valid/wikidata.json b/draft/examples/manifest/valid/wikidata.json index 536c05b..75b297f 100644 --- a/draft/examples/manifest/valid/wikidata.json +++ b/draft/examples/manifest/valid/wikidata.json @@ -82,5 +82,6 @@ "type": true, "entity": true, "property": true - } + }, + "standardizedScore": true } diff --git a/draft/index.html b/draft/index.html index d94a8f7..b80bdf7 100644 --- a/draft/index.html +++ b/draft/index.html @@ -382,6 +382,8 @@

Service Manifest

An optional value for the default text-processing language used by this service.
dir
An optional value for the default text direction used by this service.
+
standardizedScore
+
An optional boolean indicating if the service returns values between 0 and 100 (inclusive) in the score field of reconciliation candidates. This enables clients to process and display candidates accordingly, e.g. with score percentages or visualizations.

For instance, a service could expose the following minimal service manifest: @@ -554,7 +556,7 @@

Reconciliation Query Responses

type
The types of the candidate entity;
score
-
An optional numeral indicating how well this candidate entity matches the query: a higher score indicates a better match. If candidates are scored, the reconciliation service SHOULD sort candidates in decreasing score order; +
An optional numeral indicating how well this candidate entity matches the query: a higher score indicates a better match. If candidates are scored, the reconciliation service SHOULD sort candidates in decreasing score order. If standardizedScore is set to true in the service manifest, this value MUST be between 0 and 100 (inclusive);
features
An optional array of matching features;
match
diff --git a/draft/schemas/manifest.json b/draft/schemas/manifest.json index 934410a..e500a9d 100644 --- a/draft/schemas/manifest.json +++ b/draft/schemas/manifest.json @@ -254,6 +254,10 @@ } } } + }, + "standardizedScore": { + "type": "boolean", + "description": "Whether the service returns values between 0 and 100 (inclusive) in the score field of reconciliation candidates" } }, "required": [ From a2b49095e87f1b4a3cf4ef5ce894adba02a7de0c Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Thu, 14 Mar 2024 13:47:02 +0100 Subject: [PATCH 05/16] Update draft/index.html Co-authored-by: Fabian Steeg --- draft/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/index.html b/draft/index.html index 021f10b..a9923b4 100644 --- a/draft/index.html +++ b/draft/index.html @@ -500,7 +500,7 @@

Structure of a Reconciliation Query

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 related to entity names or their properties.
+
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
From 9db1fc4428a10d184bb8b8a1efc47bd00dd591c2 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Fri, 15 Mar 2024 14:43:17 +0800 Subject: [PATCH 06/16] removed history of API from README.md - history is already in the index.html file --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index 845f8b4..a2b7a19 100644 --- a/README.md +++ b/README.md @@ -8,12 +8,7 @@ https://reconciliation-api.github.io/specs/draft/ General discussion about this protocol can be held on the [`public-reconciliation@w3.org` mailing list](https://lists.w3.org/Archives/Public/public-reconciliation/). -Initially, the aim is to document the existing state of the API, -as witnessed by the existing clients and servers, and the [original documentation -on OpenRefine's wiki](https://github.com/OpenRefine/OpenRefine/wiki/Reconciliation-Service-API). -Once the existing API is documented to a satisfactory level, we will incorporate improvements -discussed in the [Community Group](https://www.w3.org/community/reconciliation/) in further versions -of the document. +Anyone can join our [W3C Entity Reconciliation Community Group](https://www.w3.org/community/reconciliation/) or read our past announcements. Feel free to contribute to this documentation effort by editing `draft/index.html`. Add yourself to the list of editors in the preamble of the document (see the [available options](https://github.com/w3c/respec/wiki/person) From 2355fb6adfe1363715d882e2733325f65536f588 Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Fri, 5 Apr 2024 15:07:40 +0200 Subject: [PATCH 07/16] Fix link to latest published version. Closes #161. --- draft/index.html | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/draft/index.html b/draft/index.html index a9923b4..28aa6ff 100644 --- a/draft/index.html +++ b/draft/index.html @@ -15,7 +15,8 @@ wgURI: "https://www.w3.org/community/reconciliation/", canonicalURI: "https://reconciliation-api.github.io/specs/draft/", edDraftURI: "https://reconciliation-api.github.io/specs/draft/", - prevRecURI: "https://reconciliation-api.github.io/specs/0.2/", + prevRecURI: "https://www.w3.org/community/reports/reconciliation/CG-FINAL-specs-0.2-20230410/", + latestVersion: "https://www.w3.org/community/reports/reconciliation/CG-FINAL-specs-0.2-20230410/", license: "w3c-software-doc", github: { repoURL: "https://github.com/reconciliation-api/specs", From 220b4dc0b2cd51f6ec051ef4dcd272eb65266f78 Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Fri, 5 Apr 2024 17:59:31 +0200 Subject: [PATCH 08/16] Update the description of changes in the current draft --- draft/index.html | 41 +++++++++++++++++++++++++---------------- 1 file changed, 25 insertions(+), 16 deletions(-) diff --git a/draft/index.html b/draft/index.html index 28aa6ff..59cbd4d 100644 --- a/draft/index.html +++ b/draft/index.html @@ -210,27 +210,36 @@

0.2

Initial improvements to the specifications made by our Community Group. Most of them are backwards-compatible, except for the requirement to support CORS for cross-origin access.

    -
  • Let manifests announce which versions of the protocol are supported by the service;
    • -
  • Make CORS support mandatory and JSONP support optional;
    • -
  • Add support for exposing type hierarchies;
    • -
  • Improve definition of schema space;
    • -
  • Establish the connection between properties in reconciliation queries and in data extension queries;
    • -
  • Make 'query' field of reconciliation queries optional;
    • -
  • Add support for returning matching features in reconciliation candidates;
    • -
  • Add support for authentication;
    • -
  • Add support for referencing other reconciliation services in reconciled values returned by data extension;
    • -
  • Add support for specifying the size of expected reconciliation batch sizes.
    • +
  • Let manifests announce which versions of the protocol are supported by the service
    • +
  • Make CORS support mandatory and JSONP support optional
    • +
  • Add support for exposing type hierarchies
    • +
  • Improve definition of schema space
    • +
  • Establish the connection between properties in reconciliation queries and in data extension queries
    • +
  • Make 'query' field of reconciliation queries optional
    • +
  • Add support for returning matching features in reconciliation candidates
    • +
  • Add support for authentication
    • +
  • Add support for referencing other reconciliation services in reconciled values returned by data extension
    • +
  • Add support for specifying the size of expected reconciliation batch sizes

This Draft

-

Collection of changes which make the API conform to the REST principles.

+

Collection of changes which make the API conform to the REST principles and follow the W3C's guidelines around accessibility, localization and security.

From 30c93d7f08be3e24f1c359f21c173d08eb10bc9e Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Sat, 6 Apr 2024 16:28:34 +0200 Subject: [PATCH 09/16] Fix inconsistent data extension metadata example The associated schema (in the manifest) is already up to date. --- .../examples/data-extension-metadata/valid/example-full.json | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/draft/examples/data-extension-metadata/valid/example-full.json b/draft/examples/data-extension-metadata/valid/example-full.json index d26b763..b0eb876 100644 --- a/draft/examples/data-extension-metadata/valid/example-full.json +++ b/draft/examples/data-extension-metadata/valid/example-full.json @@ -1,8 +1,5 @@ { - "propose_properties": { - "service_url": "https://lobid.org", - "service_path": "/gnd/reconcile/properties" - }, + "propose_properties": true, "property_settings": [ { "name": "limit", From 137e6408298a4bb6a5fb76ef30d9101f707daebc Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Thu, 11 Apr 2024 12:23:10 +0200 Subject: [PATCH 10/16] Fix typos in "This Draft" section (#162) --- draft/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft/index.html b/draft/index.html index 59cbd4d..f7e7799 100644 --- a/draft/index.html +++ b/draft/index.html @@ -228,7 +228,7 @@

This Draft

From b08f11a24577483e549bc7213ce0079b02213ae1 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Thu, 11 Apr 2024 20:56:55 +0800 Subject: [PATCH 12/16] Clarify data type as integer for `limit` parameter - Add data type 'integer' to the description for `limit`. - Also removes "string" in "query string parameter" which made it read and sound like the parameters' were sometimes String datatype. I hate English sometimes. --- draft/index.html | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/draft/index.html b/draft/index.html index 28aa6ff..4d3e597 100644 --- a/draft/index.html +++ b/draft/index.html @@ -830,11 +830,11 @@

Data Extension Property Proposals

A data extension property proposal service returns properties for a given type identifier.

- If the reconciliation service supports data extension property proposals, it MUST support HTTP GET requests to the endpoint /extend/propose (relative to the reconciliation endpoint) with a type query string parameter + If the reconciliation service supports data extension property proposals, it MUST support HTTP GET requests to the endpoint /extend/propose (relative to the reconciliation endpoint) with a type query parameter containing a type identifier.

- The service SHOULD support an optional limit query string parameter to control the number of proposed properties. + The service SHOULD support an optional limit query parameter to control the number of proposed properties. 

GET /extend/propose?type=<type identifier>[&limit=<limit>]
@@ -847,7 +847,7 @@

Data Extension Property Proposals

type
The type identifier supplied in the query;
limit
-
Optionally, the requested limit;
+
Optionally, an integer to control the number of proposed properties returned for the given type;

From cc59aae7e6148807a49d192e718228229d2b5d41 Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Thu, 11 Apr 2024 21:03:41 +0800 Subject: [PATCH 13/16] Fix small typo "gis" to "is" --- draft/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/index.html b/draft/index.html index 28aa6ff..98b92e3 100644 --- a/draft/index.html +++ b/draft/index.html @@ -810,7 +810,7 @@

Data Extension Metadata

label
A human-readable label, which is used when presenting the setting to the user in a form;
type
-
A data type, which can be one of the strings "number", "text", "checkbox", or "select". This determines which type of value the property setting gis expected to store: clients SHOULD render this setting with the corresponding HTML element; +
A data type, which can be one of the strings "number", "text", "checkbox", or "select". This determines which type of value the property setting is expected to store: clients SHOULD render this setting with the corresponding HTML element;
default
A default value for the setting, when not provided or left untouched by the user;
help_text
From b5922fd07c1c30ae1e869a3777a77931382aee2c Mon Sep 17 00:00:00 2001 From: Thad Guidry Date: Thu, 11 Apr 2024 21:07:22 +0800 Subject: [PATCH 14/16] Update draft/index.html Co-authored-by: Fabian Steeg --- draft/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/index.html b/draft/index.html index 4d3e597..fdaee8e 100644 --- a/draft/index.html +++ b/draft/index.html @@ -847,7 +847,7 @@

Data Extension Property Proposals

type
The type identifier supplied in the query;
limit
-
Optionally, an integer to control the number of proposed properties returned for the given type;
+
Optionally, an integer to indicate the requested limit;

From 6c058d3850e8564618bff1a754fd2455baa26618 Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Thu, 11 Apr 2024 17:29:24 +0200 Subject: [PATCH 15/16] Add standardizedScore change to "This Draft" section (#147) Remove camelCase entry, not merged yet, will add it back in #166 --- draft/index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft/index.html b/draft/index.html index 09d8e0e..4f9f1b2 100644 --- a/draft/index.html +++ b/draft/index.html @@ -240,7 +240,7 @@

This Draft

  • Remove identifierSpace and schemaSpace and make view templates mandatory
  • Remove support for JSONP
  • Move the query field of reconciliation queries inside properties to allow for queries which do not provide entity names
    • -
  • Unify naming to camelCase convention
    • +
  • Add optional standardizedScore field to the manifest
    • From 55ce38e75aded11752139323349347893d4de82e Mon Sep 17 00:00:00 2001 From: Fabian Steeg Date: Thu, 13 Jun 2024 16:17:18 +0200 Subject: [PATCH 16/16] Unify naming to camelCase convention (#150) (#166) * Unify naming to camelCase convention (#150) While snake_case took over in the draft, camelCase is the common convention in the manifest, so this seems to be the sensible choice * Update draft examples and schemas for removed fields Noticed while unifying naming for #150 * Update "This Draft" section for camelCase naming (#150, #162) --- .../valid/example-full.json | 8 +++--- .../manifest/invalid/feature-view.json | 2 +- .../manifest/invalid/opencorporates.json | 12 ++------ .../invalid/ror-invalid-view-pattern.json | 6 +--- .../slub-invalid-property-setting.json | 11 +++----- .../examples/manifest/valid/feature-view.json | 2 +- draft/examples/manifest/valid/lobid-gnd.json | 8 +++--- draft/examples/manifest/valid/wikidata.json | 12 ++++---- .../invalid/misnamed-conditions.json | 6 ++-- .../invalid/multiple-types.json | 2 +- .../invalid/no-root-object.json | 4 +-- .../valid/example-full.json | 28 +++++++++---------- .../valid/example-min.json | 4 +-- .../valid/multi-values.json | 4 +-- .../valid/no-query-string.json | 4 +-- .../valid/text-processing-language.json | 6 ++-- .../valid/example.json | 4 +-- draft/index.html | 25 +++++++++-------- draft/schemas/manifest.json | 14 +++++----- draft/schemas/reconciliation-query-batch.json | 19 ++++--------- .../schemas/suggest-properties-response.json | 8 +++--- 21 files changed, 82 insertions(+), 107 deletions(-) diff --git a/draft/examples/data-extension-metadata/valid/example-full.json b/draft/examples/data-extension-metadata/valid/example-full.json index b0eb876..f72ad17 100644 --- a/draft/examples/data-extension-metadata/valid/example-full.json +++ b/draft/examples/data-extension-metadata/valid/example-full.json @@ -1,19 +1,19 @@ { - "propose_properties": true, - "property_settings": [ + "proposeProperties": true, + "propertySettings": [ { "name": "limit", "label": "Limit", "type": "number", "default": 0, - "help_text": "Maximum number of values to return per row (0 for no limit)" + "helpText": "Maximum number of values to return per row (0 for no limit)" }, { "name": "content", "label": "Content", "type": "select", "default": "literal", - "help_text": "Content type: ID or literal", + "helpText": "Content type: ID or literal", "choices": [ { "value": "id", diff --git a/draft/examples/manifest/invalid/feature-view.json b/draft/examples/manifest/invalid/feature-view.json index 7166c6e..bab29f7 100644 --- a/draft/examples/manifest/invalid/feature-view.json +++ b/draft/examples/manifest/invalid/feature-view.json @@ -3,7 +3,7 @@ "view": { "url": "https://viaf.org/viaf/{id}" }, - "feature_view": { + "featureView": { "url": "https://vocab.getty.edu/recon/features/" } } diff --git a/draft/examples/manifest/invalid/opencorporates.json b/draft/examples/manifest/invalid/opencorporates.json index 06a9946..8bed8f9 100644 --- a/draft/examples/manifest/invalid/opencorporates.json +++ b/draft/examples/manifest/invalid/opencorporates.json @@ -9,16 +9,8 @@ "height": 300 }, "suggest": { - "entity": { - "service_url": "https://opencorporates.com", - "service_path": "/reconcile/suggest", - "flyout_service_path": "/reconcile/flyout" - }, - "property": { - "service_url": "https://opencorporates.com", - "service_path": "/reconcile/suggest/properties", - "flyout_service_path": "/reconcile/flyout/properties" - } + "entity": true, + "property": true }, "defaultTypes": [ { diff --git a/draft/examples/manifest/invalid/ror-invalid-view-pattern.json b/draft/examples/manifest/invalid/ror-invalid-view-pattern.json index 1d75cb7..9dbaf66 100644 --- a/draft/examples/manifest/invalid/ror-invalid-view-pattern.json +++ b/draft/examples/manifest/invalid/ror-invalid-view-pattern.json @@ -10,11 +10,7 @@ "url": "https://reconcile.ror.org/reconcile" }, "suggest": { - "entity": { - "flyout_service_path": "/flyout?id={id}", - "service_path": "/suggest", - "service_url": "https://reconcile.ror.org" - } + "entity": true }, "preview": { "width": 400, diff --git a/draft/examples/manifest/invalid/slub-invalid-property-setting.json b/draft/examples/manifest/invalid/slub-invalid-property-setting.json index 23d1648..fb50578 100644 --- a/draft/examples/manifest/invalid/slub-invalid-property-setting.json +++ b/draft/examples/manifest/invalid/slub-invalid-property-setting.json @@ -38,26 +38,23 @@ } ], "extend": { - "property_settings": [ + "propertySettings": [ { "default": 10, - "help_text": "Maximum number of values to return per row (maximum: 1000)", + "helpText": "Maximum number of values to return per row (maximum: 1000)", "label": "Limit", "name": "limit", "type": "number" }, { "default": "geo,organizations,slub-resources,persons,events,topics,works, ", - "help_text": "Which Entity-Type to use, allwed values: http://schema.org/CreativeWork, http://schema.org/Work, http://schema.org/Event, http://schema.org/Place, http://schema.org/Person, http://schema.org/Book, http://schema.org/Organization, http://schema.org/Topic, http://schema.org/CreativeWorkSeries", + "helpText": "Which Entity-Type to use, allwed values: http://schema.org/CreativeWork, http://schema.org/Work, http://schema.org/Event, http://schema.org/Place, http://schema.org/Person, http://schema.org/Book, http://schema.org/Organization, http://schema.org/Topic, http://schema.org/CreativeWorkSeries", "label": "Typ", "name": "type", "type": "string" } ], - "propose_properties": { - "service_path": "/reconcile/properties", - "service_url": "http://data.slub-dresden.de" - } + "proposeProperties": true }, "name": "SLUB LOD reconciliation for OpenRefine", "preview": { diff --git a/draft/examples/manifest/valid/feature-view.json b/draft/examples/manifest/valid/feature-view.json index fa43b45..9c8309b 100644 --- a/draft/examples/manifest/valid/feature-view.json +++ b/draft/examples/manifest/valid/feature-view.json @@ -4,7 +4,7 @@ "view": { "url": "https://viaf.org/viaf/{id}" }, - "feature_view": { + "featureView": { "url": "https://vocab.getty.edu/recon/features/{id}" } } diff --git a/draft/examples/manifest/valid/lobid-gnd.json b/draft/examples/manifest/valid/lobid-gnd.json index 82154f5..6dc9f5f 100644 --- a/draft/examples/manifest/valid/lobid-gnd.json +++ b/draft/examples/manifest/valid/lobid-gnd.json @@ -49,20 +49,20 @@ "width": 320 }, "extend": { - "property_settings": [ + "propertySettings": [ { "name": "limit", "label": "Limit", "type": "number", "default": 0, - "help_text": "Maximum number of values to return per row (0 for no limit)" + "helpText": "Maximum number of values to return per row (0 for no limit)" }, { "name": "content", "label": "Content", "type": "select", "default": "literal", - "help_text": "Content type: ID or literal", + "helpText": "Content type: ID or literal", "choices": [ { "value": "id", @@ -75,7 +75,7 @@ ] } ], - "propose_properties": true + "proposeProperties": true }, "suggest": { "property": true, diff --git a/draft/examples/manifest/valid/wikidata.json b/draft/examples/manifest/valid/wikidata.json index 75b297f..aad51ea 100644 --- a/draft/examples/manifest/valid/wikidata.json +++ b/draft/examples/manifest/valid/wikidata.json @@ -9,11 +9,11 @@ "logo": "https://tools.wmflabs.org/openrefine-wikidata/logo.png", "serviceVersion": "1.2.3", "extend": { - "property_settings": [ + "propertySettings": [ { "name": "limit", "label": "Limit", - "help_text": "Maximum number of values to return per row (0 for no limit)", + "helpText": "Maximum number of values to return per row (0 for no limit)", "type": "number", "default": 0 }, @@ -21,7 +21,7 @@ "name": "rank", "label": "Ranks", "type": "select", - "help_text": "Filter statements by rank", + "helpText": "Filter statements by rank", "choices": [ { "name": "Any rank", @@ -42,7 +42,7 @@ "name": "references", "label": "References", "type": "select", - "help_text": "Filter statements by their references", + "helpText": "Filter statements by their references", "choices": [ { "name": "Any statement", @@ -62,12 +62,12 @@ { "name": "count", "label": "Return counts instead of values", - "help_text": "The number of values will be returned.", + "helpText": "The number of values will be returned.", "type": "checkbox", "default": false } ], - "propose_properties": true + "proposeProperties": true }, "defaultTypes": [ { diff --git a/draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json b/draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json index f51e78e..534b72c 100644 --- a/draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json +++ b/draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json @@ -15,8 +15,7 @@ "pid": "affiliation", "v": "http://d-nb.info/gnd/2022139-3" } - ], - "type_strict": "should" + ] }, { "type": "DifferentiatedPerson", @@ -33,8 +32,7 @@ "pid": "affiliation", "v": "http://d-nb.info/gnd/2022139-3" } - ], - "type_strict": "should" + ] } ] } diff --git a/draft/examples/reconciliation-query-batch/invalid/multiple-types.json b/draft/examples/reconciliation-query-batch/invalid/multiple-types.json index d2f3fb7..7b94166 100644 --- a/draft/examples/reconciliation-query-batch/invalid/multiple-types.json +++ b/draft/examples/reconciliation-query-batch/invalid/multiple-types.json @@ -3,7 +3,7 @@ { "conditions": [ { - "match_type": "name", + "matchType": "name", "v": "Christel Hanewinckel" } ], 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 143d568..d5ae45f 100644 --- a/draft/examples/reconciliation-query-batch/invalid/no-root-object.json +++ b/draft/examples/reconciliation-query-batch/invalid/no-root-object.json @@ -2,7 +2,7 @@ { "conditions": [ { - "match_type": "property", + "matchType": "property", "pid": "uid", "v": "27eb892afbb2" } @@ -11,7 +11,7 @@ { "conditions": [ { - "match_type": "property", + "matchType": "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 6c61a09..7827095 100644 --- a/draft/examples/reconciliation-query-batch/valid/example-full.json +++ b/draft/examples/reconciliation-query-batch/valid/example-full.json @@ -5,24 +5,24 @@ "limit": 5, "conditions": [ { - "match_type": "name", + "matchType": "name", "v": "Christel Hanewinckel" }, { - "match_type": "property", + "matchType": "property", "pid": "professionOrOccupation", "v": "Politik*", "required": false, - "match_quantifier": "any", - "match_qualifier": "WildcardMatch" + "matchQuantifier": "any", + "matchQualifier": "WildcardMatch" }, { - "match_type": "property", + "matchType": "property", "pid": "affiliation", "v": "http://d-nb.info/gnd/2022139-3", "required": false, - "match_quantifier": "any", - "match_qualifier": "ExactMatch" + "matchQuantifier": "any", + "matchQualifier": "ExactMatch" } ] }, @@ -31,24 +31,24 @@ "limit": 5, "conditions": [ { - "match_type": "name", + "matchType": "name", "v": "Franz Thönnes" }, { - "match_type": "property", + "matchType": "property", "pid": "professionOrOccupation", "v": "Politik*", "required": false, - "match_quantifier": "any", - "match_qualifier": "WildcardMatch" + "matchQuantifier": "any", + "matchQualifier": "WildcardMatch" }, { - "match_type": "property", + "matchType": "property", "pid": "affiliation", "v": "http://d-nb.info/gnd/2022139-3", "required": false, - "match_quantifier": "any", - "match_qualifier": "ExactMatch" + "matchQuantifier": "any", + "matchQualifier": "ExactMatch" } ] } diff --git a/draft/examples/reconciliation-query-batch/valid/example-min.json b/draft/examples/reconciliation-query-batch/valid/example-min.json index 8d5d776..0dff82f 100644 --- a/draft/examples/reconciliation-query-batch/valid/example-min.json +++ b/draft/examples/reconciliation-query-batch/valid/example-min.json @@ -3,7 +3,7 @@ { "conditions": [ { - "match_type": "name", + "matchType": "name", "v": "Hans-Eberhard Urbaniak" } ] @@ -11,7 +11,7 @@ { "conditions": [ { - "match_type": "name", + "matchType": "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 f4ba3b2..c0acdbf 100644 --- a/draft/examples/reconciliation-query-batch/valid/multi-values.json +++ b/draft/examples/reconciliation-query-batch/valid/multi-values.json @@ -5,11 +5,11 @@ "limit": 5, "conditions": [ { - "match_type": "name", + "matchType": "name", "v": "Christel Hanewinckel" }, { - "match_type": "property", + "matchType": "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 ee78785..daae16d 100644 --- a/draft/examples/reconciliation-query-batch/valid/no-query-string.json +++ b/draft/examples/reconciliation-query-batch/valid/no-query-string.json @@ -3,7 +3,7 @@ { "conditions": [ { - "match_type": "property", + "matchType": "property", "pid": "uid", "v": "27eb892afbb2" } @@ -12,7 +12,7 @@ { "conditions": [ { - "match_type": "property", + "matchType": "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 dda0f9b..27fbea1 100644 --- a/draft/examples/reconciliation-query-batch/valid/text-processing-language.json +++ b/draft/examples/reconciliation-query-batch/valid/text-processing-language.json @@ -4,16 +4,16 @@ "lang": "en", "conditions": [ { - "match_type": "name", + "matchType": "name", "v": "Deng Shuping" }, { - "match_type": "property", + "matchType": "property", "pid": "professionOrOccupation", "v": "art historian" }, { - "match_type": "property", + "matchType": "property", "pid": "variantName", "v": "鄧淑蘋", "lang": "zh-Hant" diff --git a/draft/examples/suggest-properties-response/valid/example.json b/draft/examples/suggest-properties-response/valid/example.json index b093ac8..834393e 100644 --- a/draft/examples/suggest-properties-response/valid/example.json +++ b/draft/examples/suggest-properties-response/valid/example.json @@ -4,7 +4,7 @@ "name": "coordinate location", "description": "geocoordinates of the subject. For Earth, please note that only WGS84 coordinating system is supported at the moment", "id": "P625", - "match_qualifiers": [ + "matchQualifiers": [ {"id": "ExactMatch", "name": "Exact match of the coordinates"}, {"id": "DecimalPlaces-N", "name": "Match the coordinates with a precision of N decimal places"} ] @@ -13,7 +13,7 @@ "name": "place of birth", "description": "most specific known (e.g. city instead of country, or hospital instead of city) birth location of a person, animal or fictional character", "id": "P19", - "match_qualifiers": [ + "matchQualifiers": [ {"id": "schema:containsPlace", "name": "Containment relation between a place and another that it contains"}, {"id": "schema:containedInPlace", "name": "Containment relation between a place and another that contains it"} ] diff --git a/draft/index.html b/draft/index.html index 4f9f1b2..2325c82 100644 --- a/draft/index.html +++ b/draft/index.html @@ -241,6 +241,7 @@

    This Draft

  • Remove support for JSONP
  • Move the query field of reconciliation queries inside properties to allow for queries which do not provide entity names
  • Add optional standardizedScore field to the manifest
    • +
  • Unify naming to camelCase convention
    • @@ -368,7 +369,7 @@

    Service Manifest

    An optional string which describes the version of the software exposing this service. This is not to be confused with versions which is about the versions of the reconciliation API supported by the service;
    view
    An object which contains a single field url. Its value is a URI template for entities;
    -
    feature_view
    +
    featureView
    An optional object which contains a single field url. Its value is a URI template for matching features;
    preview
    A preview metadata object, supplied if the service offers a preview service;
    @@ -512,24 +513,24 @@

    Structure of a Reconciliation Query

    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
    +
    matchType
    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.
    +
    A property identifier, to be provided if and only if the matchType is property.
    v
    -
    one or more property values. If match_type is name, then this value is to +
    one or more property values. If matchType 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
    +
    matchQuantifier
    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
    +
    matchQualifier
    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 + To allow discovery of supported qualifiers by clients, services that support matchQualifier MUST return the supported matchQualifiers for each property in their property suggest responses.

    @@ -751,8 +752,8 @@

    Suggest Responses

    An optional description which can be provided to disambiguate namesakes, providing more context. This could for instance be displayed underneath the name;
    notable
    When suggesting entities only, this field can be used to supply some important types (not necessarily all types) of the suggested entity. The value must be an array of either type identifiers (as strings) or type objects, containing an id and name field which represent the type.
    -
    match_qualifiers
    -
    When suggesting properties only, an optional array of objects, each containing an id and name field, which represent the property's match_qualifiers supported in reconciliation queries.
    +
    matchQualifiers
    +
    When suggesting properties only, an optional array of objects, each containing an id and name field, which represent the property's matchQualifiers supported in reconciliation queries.
    @@ -808,9 +809,9 @@

    Data Extension Metadata

    The data extension metadata is an object stored in the service manifest in the extend field. It consists of the following settings, all optional:

    -
    propose_properties
    +
    proposeProperties
    A boolean indicating if the service supports data extension property proposal;
    -
    property_settings
    +
    propertySettings
    An array of data extension property settings.

    @@ -825,7 +826,7 @@

    Data Extension Metadata

    A data type, which can be one of the strings "number", "text", "checkbox", or "select". This determines which type of value the property setting is expected to store: clients SHOULD render this setting with the corresponding HTML element;
    default
    A default value for the setting, when not provided or left untouched by the user;
    -
    help_text
    +
    helpText
    A help text, which describes the meaning of the field to the user. This is meant to be a short string that can be displayed alongside the corresponding form field;
    choices
    If type is select, an array of property setting choices.
    diff --git a/draft/schemas/manifest.json b/draft/schemas/manifest.json index e500a9d..03fc9a3 100644 --- a/draft/schemas/manifest.json +++ b/draft/schemas/manifest.json @@ -46,7 +46,7 @@ "url" ] }, - "feature_view": { + "featureView": { "type": "object", "properties": { "url": { @@ -106,11 +106,11 @@ "type": "object", "description": "Settings for the data extension protocol, to fetch property values", "properties": { - "propose_properties": { + "proposeProperties": { "type": "boolean", "description": "Whether the service supports property proposals" }, - "property_settings": { + "propertySettings": { "type": "array", "description": "Definition of the settings configurable by the user when fetching a property", "items": { @@ -134,7 +134,7 @@ "name": { "type": "string" }, - "help_text": { + "helpText": { "type": "string" } }, @@ -163,7 +163,7 @@ "name": { "type": "string" }, - "help_text": { + "helpText": { "type": "string" } }, @@ -192,7 +192,7 @@ "name": { "type": "string" }, - "help_text": { + "helpText": { "type": "string" } }, @@ -221,7 +221,7 @@ "name": { "type": "string" }, - "help_text": { + "helpText": { "type": "string" }, "choices": { diff --git a/draft/schemas/reconciliation-query-batch.json b/draft/schemas/reconciliation-query-batch.json index 7bfe4ae..ad8c7a8 100644 --- a/draft/schemas/reconciliation-query-batch.json +++ b/draft/schemas/reconciliation-query-batch.json @@ -62,7 +62,7 @@ "items": { "type": "object", "properties": { - "match_type": { + "matchType": { "type": "string", "description": "A string to indicate whether to match the supplied value to entity names or property values", "enum": [ @@ -72,7 +72,7 @@ }, "pid": { "type": "string", - "description": "The identifier of the property, whose values will be compared to the values supplied. Required if 'match_type' is 'property'." + "description": "The identifier of the property, whose values will be compared to the values supplied. Required if 'matchType' is 'property'." }, "v": { "description": "A value (or array of values) to match against the entity names or property values associated with the property on each candidate", @@ -92,7 +92,7 @@ "type": "boolean", "description": "A boolean indicating if a match of this condition is required for an entity to enter the list of candidates" }, - "match_quantifier": { + "matchQuantifier": { "type": "string", "description": "A string to indicate which of the values in v to match", "enum": [ @@ -101,25 +101,16 @@ "none" ] }, - "match_qualifier": { + "matchQualifier": { "type": "string", "description": "A string to indicate how to match the values in v" } }, "required": [ - "match_type", + "matchType", "v" ] } - }, - "type_strict": { - "type": "string", - "description": "A classification of the type matching strategy when multiple types are supplied", - "enum": [ - "any", - "should", - "all" - ] } }, "required": [ diff --git a/draft/schemas/suggest-properties-response.json b/draft/schemas/suggest-properties-response.json index cd16f5c..2e02b01 100644 --- a/draft/schemas/suggest-properties-response.json +++ b/draft/schemas/suggest-properties-response.json @@ -21,19 +21,19 @@ "type": "string", "description": "An optional description which can be provided to disambiguate namesakes, providing more context." }, - "match_qualifiers": { + "matchQualifiers": { "type": "array", - "description": "An optional array of objects representing the match_qualifiers supported for the suggested property", + "description": "An optional array of objects representing the matchQualifiers supported for the suggested property", "items": { "type": "object", "properties": { "id": { "type": "string", - "description": "Identifier of the match_qualifier" + "description": "Identifier of the matchQualifier" }, "name": { "type": "string", - "description": "Name of the match_qualifier" + "description": "Name of the matchQualifier" } }, "required": [