From 580aa4514cc7d50089174b0fdae65ce7c3971794 Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Thu, 12 Sep 2024 17:02:23 +0200 Subject: [PATCH 1/6] Name the current draft 1.0-draft --- draft/index.html | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft/index.html b/draft/index.html index 521a0e4..aae013a 100644 --- a/draft/index.html +++ b/draft/index.html @@ -223,7 +223,7 @@

Have all URI templates follow the RFC6570 syntax @@ -354,7 +354,7 @@

Service Manifest

A service manifest consists of the following fields:
versions
-
The array of API versions supported by the endpoint, such as ["0.1", "0.2"]. Since this field did not exist in version 0.1, services which do not declare a versions field are expected to only support version 0.1.
+
The array of API versions supported by the endpoint, such as ["0.1", "0.2"]. Since this field did not exist in version 0.1, services which do not declare a versions field are expected to only support version 0.1. A service implementing the current draft should include 1.0-draft in the array.
name
A human-readable name for the service, generally the name of the database it exposes. In the case where multiple reconciliation services exist for the same database, it is in the interest of a service to bear a meaningful name which will help disambiguating it from others;
From 469447a2a4ee522a5fa2b99704a52a3f7021eff6 Mon Sep 17 00:00:00 2001 From: Antonin Delpeuch Date: Thu, 12 Sep 2024 17:03:36 +0200 Subject: [PATCH 2/6] Change URL from draft/ to 1.0-draft/ --- .../valid/example-full.json | 0 .../invalid/missing-properties.json | 0 .../valid/response.json | 0 .../valid/example-full.json | 0 .../valid/example-min.json | 0 .../invalid/wrong-properties.json | 0 .../valid/example-dir.json | 0 .../valid/example-full.json | 0 .../manifest/invalid/bad-authentication.json | 0 .../manifest/invalid/feature-view.json | 0 .../manifest/invalid/godot-missing-view.json | 0 .../manifest/invalid/missing-version.json | 0 .../manifest/invalid/old-version.json | 0 .../manifest/invalid/opencorporates.json | 0 .../invalid/ror-invalid-view-pattern.json | 0 .../slub-invalid-property-setting.json | 0 .../manifest/valid/authentication.json | 0 .../manifest/valid/codefork-viaf.json | 0 .../examples/manifest/valid/example-min.json | 0 .../examples/manifest/valid/feature-view.json | 0 .../manifest/valid/findthatcharity.json | 0 .../examples/manifest/valid/fundref.json | 0 .../manifest/valid/geocollider-sinatra.json | 0 .../examples/manifest/valid/getty.json | 0 .../examples/manifest/valid/kerameikos.json | 0 .../examples/manifest/valid/kew.json | 0 .../examples/manifest/valid/lobid-gnd.json | 0 .../examples/manifest/valid/nomisma.json | 0 .../examples/manifest/valid/occrp.json | 0 .../manifest/valid/ordnance-survey.json | 0 .../examples/manifest/valid/vivo-cornell.json | 0 .../examples/manifest/valid/wikidata.json | 0 .../preview-metadata/valid/example.json | 0 .../examples/preview-response/example.html | 0 .../valid/example.json | 0 .../invalid/empty-conditions.json | 0 .../invalid/empty-query.json | 0 .../invalid/misnamed-conditions.json | 0 .../invalid/missing-match-type.json | 0 .../invalid/multiple-types.json | 0 .../invalid/no-root-object.json | 0 .../invalid/old-format.json | 0 .../valid/example-full.json | 0 .../valid/example-min.json | 0 .../valid/multi-values.json | 0 .../valid/no-query-string.json | 0 .../valid/text-processing-language.json | 0 .../invalid/missing-id.json | 0 .../invalid/no-result.json | 0 .../invalid/root-array.json | 0 .../valid/example-full.json | 0 .../valid/minimal.json | 0 .../security-scheme/valid/api_key.json | 0 .../valid/http_basic_auth.json | 0 .../valid/example.json | 0 .../valid/example.json | 0 .../suggest-types-response/valid/example.json | 0 1.0-draft/index.html | 1138 ++++++++++++++++ .../data-extension-property-proposal.json | 0 .../schemas/data-extension-query.json | 0 .../schemas/data-extension-response.json | 0 {draft => 1.0-draft}/schemas/manifest.json | 0 {draft => 1.0-draft}/schemas/openapi.json | 0 .../schemas/reconciliation-query-batch.json | 0 .../schemas/reconciliation-result-batch.json | 0 .../schemas/suggest-entities-response.json | 0 .../schemas/suggest-properties-response.json | 0 .../schemas/suggest-types-response.json | 0 {draft => 1.0-draft}/schemas/type.json | 0 draft/index.html | 1149 +---------------- test.sh | 2 +- 71 files changed, 1152 insertions(+), 1137 deletions(-) rename {draft => 1.0-draft}/examples/data-extension-metadata/valid/example-full.json (100%) rename {draft => 1.0-draft}/examples/data-extension-property-proposal/invalid/missing-properties.json (100%) rename {draft => 1.0-draft}/examples/data-extension-property-proposal/valid/response.json (100%) rename {draft => 1.0-draft}/examples/data-extension-query/valid/example-full.json (100%) rename {draft => 1.0-draft}/examples/data-extension-query/valid/example-min.json (100%) rename {draft => 1.0-draft}/examples/data-extension-response/invalid/wrong-properties.json (100%) rename {draft => 1.0-draft}/examples/data-extension-response/valid/example-dir.json (100%) rename {draft => 1.0-draft}/examples/data-extension-response/valid/example-full.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/bad-authentication.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/feature-view.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/godot-missing-view.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/missing-version.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/old-version.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/opencorporates.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/ror-invalid-view-pattern.json (100%) rename {draft => 1.0-draft}/examples/manifest/invalid/slub-invalid-property-setting.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/authentication.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/codefork-viaf.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/example-min.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/feature-view.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/findthatcharity.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/fundref.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/geocollider-sinatra.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/getty.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/kerameikos.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/kew.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/lobid-gnd.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/nomisma.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/occrp.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/ordnance-survey.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/vivo-cornell.json (100%) rename {draft => 1.0-draft}/examples/manifest/valid/wikidata.json (100%) rename {draft => 1.0-draft}/examples/preview-metadata/valid/example.json (100%) rename {draft => 1.0-draft}/examples/preview-response/example.html (100%) rename {draft => 1.0-draft}/examples/reconciliation-candidate/valid/example.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/invalid/empty-conditions.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/invalid/empty-query.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/invalid/misnamed-conditions.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/invalid/missing-match-type.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/invalid/multiple-types.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/invalid/no-root-object.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/invalid/old-format.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/valid/example-full.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/valid/example-min.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/valid/multi-values.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/valid/no-query-string.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-query-batch/valid/text-processing-language.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-result-batch/invalid/missing-id.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-result-batch/invalid/no-result.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-result-batch/invalid/root-array.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-result-batch/valid/example-full.json (100%) rename {draft => 1.0-draft}/examples/reconciliation-result-batch/valid/minimal.json (100%) rename {draft => 1.0-draft}/examples/security-scheme/valid/api_key.json (100%) rename {draft => 1.0-draft}/examples/security-scheme/valid/http_basic_auth.json (100%) rename {draft => 1.0-draft}/examples/suggest-entities-response/valid/example.json (100%) rename {draft => 1.0-draft}/examples/suggest-properties-response/valid/example.json (100%) rename {draft => 1.0-draft}/examples/suggest-types-response/valid/example.json (100%) create mode 100644 1.0-draft/index.html rename {draft => 1.0-draft}/schemas/data-extension-property-proposal.json (100%) rename {draft => 1.0-draft}/schemas/data-extension-query.json (100%) rename {draft => 1.0-draft}/schemas/data-extension-response.json (100%) rename {draft => 1.0-draft}/schemas/manifest.json (100%) rename {draft => 1.0-draft}/schemas/openapi.json (100%) rename {draft => 1.0-draft}/schemas/reconciliation-query-batch.json (100%) rename {draft => 1.0-draft}/schemas/reconciliation-result-batch.json (100%) rename {draft => 1.0-draft}/schemas/suggest-entities-response.json (100%) rename {draft => 1.0-draft}/schemas/suggest-properties-response.json (100%) rename {draft => 1.0-draft}/schemas/suggest-types-response.json (100%) rename {draft => 1.0-draft}/schemas/type.json (100%) diff --git a/draft/examples/data-extension-metadata/valid/example-full.json b/1.0-draft/examples/data-extension-metadata/valid/example-full.json similarity index 100% rename from draft/examples/data-extension-metadata/valid/example-full.json rename to 1.0-draft/examples/data-extension-metadata/valid/example-full.json diff --git a/draft/examples/data-extension-property-proposal/invalid/missing-properties.json b/1.0-draft/examples/data-extension-property-proposal/invalid/missing-properties.json similarity index 100% rename from draft/examples/data-extension-property-proposal/invalid/missing-properties.json rename to 1.0-draft/examples/data-extension-property-proposal/invalid/missing-properties.json diff --git a/draft/examples/data-extension-property-proposal/valid/response.json b/1.0-draft/examples/data-extension-property-proposal/valid/response.json similarity index 100% rename from draft/examples/data-extension-property-proposal/valid/response.json rename to 1.0-draft/examples/data-extension-property-proposal/valid/response.json diff --git a/draft/examples/data-extension-query/valid/example-full.json b/1.0-draft/examples/data-extension-query/valid/example-full.json similarity index 100% rename from draft/examples/data-extension-query/valid/example-full.json rename to 1.0-draft/examples/data-extension-query/valid/example-full.json diff --git a/draft/examples/data-extension-query/valid/example-min.json b/1.0-draft/examples/data-extension-query/valid/example-min.json similarity index 100% rename from draft/examples/data-extension-query/valid/example-min.json rename to 1.0-draft/examples/data-extension-query/valid/example-min.json diff --git a/draft/examples/data-extension-response/invalid/wrong-properties.json b/1.0-draft/examples/data-extension-response/invalid/wrong-properties.json similarity index 100% rename from draft/examples/data-extension-response/invalid/wrong-properties.json rename to 1.0-draft/examples/data-extension-response/invalid/wrong-properties.json diff --git a/draft/examples/data-extension-response/valid/example-dir.json b/1.0-draft/examples/data-extension-response/valid/example-dir.json similarity index 100% rename from draft/examples/data-extension-response/valid/example-dir.json rename to 1.0-draft/examples/data-extension-response/valid/example-dir.json diff --git a/draft/examples/data-extension-response/valid/example-full.json b/1.0-draft/examples/data-extension-response/valid/example-full.json similarity index 100% rename from draft/examples/data-extension-response/valid/example-full.json rename to 1.0-draft/examples/data-extension-response/valid/example-full.json diff --git a/draft/examples/manifest/invalid/bad-authentication.json b/1.0-draft/examples/manifest/invalid/bad-authentication.json similarity index 100% rename from draft/examples/manifest/invalid/bad-authentication.json rename to 1.0-draft/examples/manifest/invalid/bad-authentication.json diff --git a/draft/examples/manifest/invalid/feature-view.json b/1.0-draft/examples/manifest/invalid/feature-view.json similarity index 100% rename from draft/examples/manifest/invalid/feature-view.json rename to 1.0-draft/examples/manifest/invalid/feature-view.json diff --git a/draft/examples/manifest/invalid/godot-missing-view.json b/1.0-draft/examples/manifest/invalid/godot-missing-view.json similarity index 100% rename from draft/examples/manifest/invalid/godot-missing-view.json rename to 1.0-draft/examples/manifest/invalid/godot-missing-view.json diff --git a/draft/examples/manifest/invalid/missing-version.json b/1.0-draft/examples/manifest/invalid/missing-version.json similarity index 100% rename from draft/examples/manifest/invalid/missing-version.json rename to 1.0-draft/examples/manifest/invalid/missing-version.json diff --git a/draft/examples/manifest/invalid/old-version.json b/1.0-draft/examples/manifest/invalid/old-version.json similarity index 100% rename from draft/examples/manifest/invalid/old-version.json rename to 1.0-draft/examples/manifest/invalid/old-version.json diff --git a/draft/examples/manifest/invalid/opencorporates.json b/1.0-draft/examples/manifest/invalid/opencorporates.json similarity index 100% rename from draft/examples/manifest/invalid/opencorporates.json rename to 1.0-draft/examples/manifest/invalid/opencorporates.json diff --git a/draft/examples/manifest/invalid/ror-invalid-view-pattern.json b/1.0-draft/examples/manifest/invalid/ror-invalid-view-pattern.json similarity index 100% rename from draft/examples/manifest/invalid/ror-invalid-view-pattern.json rename to 1.0-draft/examples/manifest/invalid/ror-invalid-view-pattern.json diff --git a/draft/examples/manifest/invalid/slub-invalid-property-setting.json b/1.0-draft/examples/manifest/invalid/slub-invalid-property-setting.json similarity index 100% rename from draft/examples/manifest/invalid/slub-invalid-property-setting.json rename to 1.0-draft/examples/manifest/invalid/slub-invalid-property-setting.json diff --git a/draft/examples/manifest/valid/authentication.json b/1.0-draft/examples/manifest/valid/authentication.json similarity index 100% rename from draft/examples/manifest/valid/authentication.json rename to 1.0-draft/examples/manifest/valid/authentication.json diff --git a/draft/examples/manifest/valid/codefork-viaf.json b/1.0-draft/examples/manifest/valid/codefork-viaf.json similarity index 100% rename from draft/examples/manifest/valid/codefork-viaf.json rename to 1.0-draft/examples/manifest/valid/codefork-viaf.json diff --git a/draft/examples/manifest/valid/example-min.json b/1.0-draft/examples/manifest/valid/example-min.json similarity index 100% rename from draft/examples/manifest/valid/example-min.json rename to 1.0-draft/examples/manifest/valid/example-min.json diff --git a/draft/examples/manifest/valid/feature-view.json b/1.0-draft/examples/manifest/valid/feature-view.json similarity index 100% rename from draft/examples/manifest/valid/feature-view.json rename to 1.0-draft/examples/manifest/valid/feature-view.json diff --git a/draft/examples/manifest/valid/findthatcharity.json b/1.0-draft/examples/manifest/valid/findthatcharity.json similarity index 100% rename from draft/examples/manifest/valid/findthatcharity.json rename to 1.0-draft/examples/manifest/valid/findthatcharity.json diff --git a/draft/examples/manifest/valid/fundref.json b/1.0-draft/examples/manifest/valid/fundref.json similarity index 100% rename from draft/examples/manifest/valid/fundref.json rename to 1.0-draft/examples/manifest/valid/fundref.json diff --git a/draft/examples/manifest/valid/geocollider-sinatra.json b/1.0-draft/examples/manifest/valid/geocollider-sinatra.json similarity index 100% rename from draft/examples/manifest/valid/geocollider-sinatra.json rename to 1.0-draft/examples/manifest/valid/geocollider-sinatra.json diff --git a/draft/examples/manifest/valid/getty.json b/1.0-draft/examples/manifest/valid/getty.json similarity index 100% rename from draft/examples/manifest/valid/getty.json rename to 1.0-draft/examples/manifest/valid/getty.json diff --git a/draft/examples/manifest/valid/kerameikos.json b/1.0-draft/examples/manifest/valid/kerameikos.json similarity index 100% rename from draft/examples/manifest/valid/kerameikos.json rename to 1.0-draft/examples/manifest/valid/kerameikos.json diff --git a/draft/examples/manifest/valid/kew.json b/1.0-draft/examples/manifest/valid/kew.json similarity index 100% rename from draft/examples/manifest/valid/kew.json rename to 1.0-draft/examples/manifest/valid/kew.json diff --git a/draft/examples/manifest/valid/lobid-gnd.json b/1.0-draft/examples/manifest/valid/lobid-gnd.json similarity index 100% rename from draft/examples/manifest/valid/lobid-gnd.json rename to 1.0-draft/examples/manifest/valid/lobid-gnd.json diff --git a/draft/examples/manifest/valid/nomisma.json b/1.0-draft/examples/manifest/valid/nomisma.json similarity index 100% rename from draft/examples/manifest/valid/nomisma.json rename to 1.0-draft/examples/manifest/valid/nomisma.json diff --git a/draft/examples/manifest/valid/occrp.json b/1.0-draft/examples/manifest/valid/occrp.json similarity index 100% rename from draft/examples/manifest/valid/occrp.json rename to 1.0-draft/examples/manifest/valid/occrp.json diff --git a/draft/examples/manifest/valid/ordnance-survey.json b/1.0-draft/examples/manifest/valid/ordnance-survey.json similarity index 100% rename from draft/examples/manifest/valid/ordnance-survey.json rename to 1.0-draft/examples/manifest/valid/ordnance-survey.json diff --git a/draft/examples/manifest/valid/vivo-cornell.json b/1.0-draft/examples/manifest/valid/vivo-cornell.json similarity index 100% rename from draft/examples/manifest/valid/vivo-cornell.json rename to 1.0-draft/examples/manifest/valid/vivo-cornell.json diff --git a/draft/examples/manifest/valid/wikidata.json b/1.0-draft/examples/manifest/valid/wikidata.json similarity index 100% rename from draft/examples/manifest/valid/wikidata.json rename to 1.0-draft/examples/manifest/valid/wikidata.json diff --git a/draft/examples/preview-metadata/valid/example.json b/1.0-draft/examples/preview-metadata/valid/example.json similarity index 100% rename from draft/examples/preview-metadata/valid/example.json rename to 1.0-draft/examples/preview-metadata/valid/example.json diff --git a/draft/examples/preview-response/example.html b/1.0-draft/examples/preview-response/example.html similarity index 100% rename from draft/examples/preview-response/example.html rename to 1.0-draft/examples/preview-response/example.html diff --git a/draft/examples/reconciliation-candidate/valid/example.json b/1.0-draft/examples/reconciliation-candidate/valid/example.json similarity index 100% rename from draft/examples/reconciliation-candidate/valid/example.json rename to 1.0-draft/examples/reconciliation-candidate/valid/example.json diff --git a/draft/examples/reconciliation-query-batch/invalid/empty-conditions.json b/1.0-draft/examples/reconciliation-query-batch/invalid/empty-conditions.json similarity index 100% rename from draft/examples/reconciliation-query-batch/invalid/empty-conditions.json rename to 1.0-draft/examples/reconciliation-query-batch/invalid/empty-conditions.json diff --git a/draft/examples/reconciliation-query-batch/invalid/empty-query.json b/1.0-draft/examples/reconciliation-query-batch/invalid/empty-query.json similarity index 100% rename from draft/examples/reconciliation-query-batch/invalid/empty-query.json rename to 1.0-draft/examples/reconciliation-query-batch/invalid/empty-query.json diff --git a/draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json b/1.0-draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json similarity index 100% rename from draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json rename to 1.0-draft/examples/reconciliation-query-batch/invalid/misnamed-conditions.json diff --git a/draft/examples/reconciliation-query-batch/invalid/missing-match-type.json b/1.0-draft/examples/reconciliation-query-batch/invalid/missing-match-type.json similarity index 100% rename from draft/examples/reconciliation-query-batch/invalid/missing-match-type.json rename to 1.0-draft/examples/reconciliation-query-batch/invalid/missing-match-type.json diff --git a/draft/examples/reconciliation-query-batch/invalid/multiple-types.json b/1.0-draft/examples/reconciliation-query-batch/invalid/multiple-types.json similarity index 100% rename from draft/examples/reconciliation-query-batch/invalid/multiple-types.json rename to 1.0-draft/examples/reconciliation-query-batch/invalid/multiple-types.json diff --git a/draft/examples/reconciliation-query-batch/invalid/no-root-object.json b/1.0-draft/examples/reconciliation-query-batch/invalid/no-root-object.json similarity index 100% rename from draft/examples/reconciliation-query-batch/invalid/no-root-object.json rename to 1.0-draft/examples/reconciliation-query-batch/invalid/no-root-object.json diff --git a/draft/examples/reconciliation-query-batch/invalid/old-format.json b/1.0-draft/examples/reconciliation-query-batch/invalid/old-format.json similarity index 100% rename from draft/examples/reconciliation-query-batch/invalid/old-format.json rename to 1.0-draft/examples/reconciliation-query-batch/invalid/old-format.json diff --git a/draft/examples/reconciliation-query-batch/valid/example-full.json b/1.0-draft/examples/reconciliation-query-batch/valid/example-full.json similarity index 100% rename from draft/examples/reconciliation-query-batch/valid/example-full.json rename to 1.0-draft/examples/reconciliation-query-batch/valid/example-full.json diff --git a/draft/examples/reconciliation-query-batch/valid/example-min.json b/1.0-draft/examples/reconciliation-query-batch/valid/example-min.json similarity index 100% rename from draft/examples/reconciliation-query-batch/valid/example-min.json rename to 1.0-draft/examples/reconciliation-query-batch/valid/example-min.json diff --git a/draft/examples/reconciliation-query-batch/valid/multi-values.json b/1.0-draft/examples/reconciliation-query-batch/valid/multi-values.json similarity index 100% rename from draft/examples/reconciliation-query-batch/valid/multi-values.json rename to 1.0-draft/examples/reconciliation-query-batch/valid/multi-values.json diff --git a/draft/examples/reconciliation-query-batch/valid/no-query-string.json b/1.0-draft/examples/reconciliation-query-batch/valid/no-query-string.json similarity index 100% rename from draft/examples/reconciliation-query-batch/valid/no-query-string.json rename to 1.0-draft/examples/reconciliation-query-batch/valid/no-query-string.json diff --git a/draft/examples/reconciliation-query-batch/valid/text-processing-language.json b/1.0-draft/examples/reconciliation-query-batch/valid/text-processing-language.json similarity index 100% rename from draft/examples/reconciliation-query-batch/valid/text-processing-language.json rename to 1.0-draft/examples/reconciliation-query-batch/valid/text-processing-language.json diff --git a/draft/examples/reconciliation-result-batch/invalid/missing-id.json b/1.0-draft/examples/reconciliation-result-batch/invalid/missing-id.json similarity index 100% rename from draft/examples/reconciliation-result-batch/invalid/missing-id.json rename to 1.0-draft/examples/reconciliation-result-batch/invalid/missing-id.json diff --git a/draft/examples/reconciliation-result-batch/invalid/no-result.json b/1.0-draft/examples/reconciliation-result-batch/invalid/no-result.json similarity index 100% rename from draft/examples/reconciliation-result-batch/invalid/no-result.json rename to 1.0-draft/examples/reconciliation-result-batch/invalid/no-result.json diff --git a/draft/examples/reconciliation-result-batch/invalid/root-array.json b/1.0-draft/examples/reconciliation-result-batch/invalid/root-array.json similarity index 100% rename from draft/examples/reconciliation-result-batch/invalid/root-array.json rename to 1.0-draft/examples/reconciliation-result-batch/invalid/root-array.json diff --git a/draft/examples/reconciliation-result-batch/valid/example-full.json b/1.0-draft/examples/reconciliation-result-batch/valid/example-full.json similarity index 100% rename from draft/examples/reconciliation-result-batch/valid/example-full.json rename to 1.0-draft/examples/reconciliation-result-batch/valid/example-full.json diff --git a/draft/examples/reconciliation-result-batch/valid/minimal.json b/1.0-draft/examples/reconciliation-result-batch/valid/minimal.json similarity index 100% rename from draft/examples/reconciliation-result-batch/valid/minimal.json rename to 1.0-draft/examples/reconciliation-result-batch/valid/minimal.json diff --git a/draft/examples/security-scheme/valid/api_key.json b/1.0-draft/examples/security-scheme/valid/api_key.json similarity index 100% rename from draft/examples/security-scheme/valid/api_key.json rename to 1.0-draft/examples/security-scheme/valid/api_key.json diff --git a/draft/examples/security-scheme/valid/http_basic_auth.json b/1.0-draft/examples/security-scheme/valid/http_basic_auth.json similarity index 100% rename from draft/examples/security-scheme/valid/http_basic_auth.json rename to 1.0-draft/examples/security-scheme/valid/http_basic_auth.json diff --git a/draft/examples/suggest-entities-response/valid/example.json b/1.0-draft/examples/suggest-entities-response/valid/example.json similarity index 100% rename from draft/examples/suggest-entities-response/valid/example.json rename to 1.0-draft/examples/suggest-entities-response/valid/example.json diff --git a/draft/examples/suggest-properties-response/valid/example.json b/1.0-draft/examples/suggest-properties-response/valid/example.json similarity index 100% rename from draft/examples/suggest-properties-response/valid/example.json rename to 1.0-draft/examples/suggest-properties-response/valid/example.json diff --git a/draft/examples/suggest-types-response/valid/example.json b/1.0-draft/examples/suggest-types-response/valid/example.json similarity index 100% rename from draft/examples/suggest-types-response/valid/example.json rename to 1.0-draft/examples/suggest-types-response/valid/example.json diff --git a/1.0-draft/index.html b/1.0-draft/index.html new file mode 100644 index 0000000..aae013a --- /dev/null +++ b/1.0-draft/index.html @@ -0,0 +1,1138 @@ + + + + + + + Reconciliation Service API + + +
+

+ This document describes the reconciliation service API, a protocol edited by the + W3C Entity Reconciliation Community Group. + It is intended as a comprehensive and definitive specification of this API in its given state. + Various aspects of this API need to be improved, as hinted by notes throughout this document. +

+
+
+

+ Members of the Community Group are encouraged to contribute to this document by + documenting the current behaviour of the reconciliation API. + The ReSpec Editor's Guide + can be used to learn more about the markup to use in this document. +

+
+
+

Introduction

+
+

Data Matching on the Web

+

+ Integrating data from sources which do not share common unique identifiers often requires matching (or reconciling, merging) records which refer to the same entities. + The promises of the Linked Open Data movement, the ability to mix up data from different publishers expressed in a common language (such as RDF) rely on being able to identify identities across services. + Due to the Web's decentralized nature, there is nothing preventing a service from publishing a new URI for a resource or concept which is +already expressed by another URI. +

+

+ Various mechanisms exist to state the equivalence between two URIs: for instance, such a correspondence can be stated with the owl:sameAs property [[owl-features]], or using looser notions equivalences defined in SKOS [[skos-primer]]. But such statements must in turn be themselves findable. + One can aggregate owl:sameAs statements from various sources to infer identities by transitivity, but this is a subtle art as some data sources can erroneously equate different concepts [[beek-2018]]. + After all, any quest towards building a universal identifier system which avoids duplicates is necessarily doomed. + Data publishers use different granularities to model the world. Concepts have fluctuating boundaries across languages, cultures and time. +

+

+ In practice, we can determine if two database records refer to the same entity by comparing their attributes. + For instance, two entries about cities bearing the same name, in the same country and with the same mayor are likely to refer to the same city. + The reconciliation API that we present here makes it easier to discover such matches. + It is a protocol that a data provider can implement, enabling its consumers to efficiently match their own data to the entities represented by the provider. +

+

+ By nature, reconciliation is a heuristic process. Different entities can have many identical characteristics, leading to false positives. + The same entity can be represented in different ways by two databases, for instance by spelling names differently, leading to false negatives. + This problem has been extensively studied and many heuristics have been proposed to tackle it [[christen-2012]]. + The reconciliation API is agnostic about the particulars of the heuristics involved: it lets data providers choose how + they want to determine which of their entities are good candidates for a particular query. What it provides + is a web API to let users obtain these candidate entities without having to implement the underlying reconciliation heuristics + themselves, nor download the entire contents of the target database. +

+
+
+

History of the Reconciliation API

+

+ This API was originally designed by Metaweb as a protocol used between Freebase and Gridworks (now known as OpenRefine). + Freebase was a free crowdsourced knowledge graph, storing data about a broad range of topics and exposed on the web as linked data. + OpenRefine is tool which was originally designed to help populate this knowledge graph by importing data into it. + It supports a range of operations which help the user reshape their data to prepare it for ingestion in a data model such as Freebase's. + One of these operations is reconciliation, which matches mentions of entities in the local dataset to records in the target database. The reconciliation API was initially introduced to specify how OpenRefine and Freebase could communicate during that process. +

+

+ The reconciliation API was then turned into a generic protocol that any database could implement. + This made it possible to register such a database into OpenRefine by adding it as a Standard Service. + This API was implemented by various services, either directly by the service provider itself (for instance the Crossref funder database, + Nomisma or the Getty thesaurus) or by a third party as a wrapper sitting on top of other existing web APIs for the service + (such as Wikidata or VIAF). + Software was also developed to expose a reconciliation endpoint out of any tabular file (reconcile-csv) or by wrapping a SPARQL endpoint (in the OpenRefine RDF extension). +

+

+ This API was documented on OpenRefine's wiki as a living document which evolved gradually, as OpenRefine improved. + In addition to its core feature, fetching reconciliation candidates matching a given query, services are optionally able + to implement additional endpoints which ease the integration of the service in OpenRefine's UI, by providing previews + for entities (with a Preview Service) and auto-completion for various inputs (with Suggest Services). + In 2018, a Data Extension Service was added, letting consumers pull data from the target database once they have reconciled + their records. +

+

+ In 2019 the W3C Entity Reconciliation Community Group was formed, + with the intention of promoting and improving this API outside the strict scope of the OpenRefine project. + This document is an attempt to better specify this API. +

+
+
+

External Resources

+

+ A list of known public endpoints is maintained by the community, where they can also be tried out interactively. OpenRefine's wiki also hosts a list of reconciliable data source which also includes non-hosted or discontinued services. + Existing clients to the API, such as OpenRefine or Cocoda can be used to interact with reconciliation services. +

+
+
+

Versions

+

+ This section summarizes the differences between successive versions of the API. +

+
+

0.1

+

Initial documentation of the reconciliation API as supported by OpenRefine 3.0 to 3.2.

+
+
+

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
    • +
+
+
+

This draft: 1.0-draft

+

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

+ +
+
+
+
+
+

Core Concepts

+

+ This section documents the data model behind the reconciliation API. + A reconciliation service lets users match their data against entities + exposed by the service. Matching can be refined by filtering by type + or properties with property values. + The purpose of this section is to define these notions. +

+
+

Entities

+

+ An entity is a record in the data source exposed by the service. + It comprises the following fields: +

+
id
+
an identifier, which is a non-empty string. This identifier must be unique among all entities;
+
name
+
a name, which is also a non-empty string;
+
description
+
an optional description as a human-readable string;
+
type
+
an array of types, possibly empty;
+
+ Moreover, for each property the entity contains a set of associated property values, possibly empty. +

+

+ Reconciliation services MUST define in their service manifest a URI template for entities, + as defined by [[RFC6570]]. This URI template builds a view URI for each entity, and has id as only variable. + For each entity, expanding the template with id being set to the entity's identifier + MUST result in a valid URI. +

+

+ For example, a service which uses Wikidata identifiers for its entities could use http://www.wikidata.org/entity/{id} + as URI template for entities. For an entity with identifier Q5, this would expand to http://www.wikidata.org/entity/Q5. + Services for which the entity's identifier is already a full URI can use the {+id} template, which disables the escaping of some characters + when inserting the identifier in the template. + See [[RFC6570]] for more examples of URI templates. +

+

+ Similarly, it is possible to associate to each matching feature a URL where documentation about + the feature is provided, by means of a URI template. Inserting any feature identifier in this template + generates the URL for the feature. +

+
+
+

Types

+

+ A type represents a category of entities. + It comprises the following fields: +

+
id
+
an identifier, which is a non-empty string. This identifier must be unique among all types;
+
name
+
a human-readable name, which is a non-empty string;
+
broader
+
an optional array of types, each representing a direct (i.e., immediate) broader [[skos-reference]] category of entities.
+
+

+
+
+

Properties

+

+ A property represents a type of attribute that entities can have in the data source. + It comprises the following fields: +

+
id
+
an identifier, which is a non-empty string. This identifier must be unique among all properties;
+
name
+
a human-readable name, which is a non-empty string.
+
+

+
+
+

Property Values

+

+ A property value can be any of the following: +

    +
  • A string;
    • +
  • A boolean;
    • +
  • An integer;
    • +
  • A floating-point value;
    • +
  • An entity.
    • +
+

+
+
+
+

Service Definition

+

+ This section documents how reconciliation services are exposed as HTTP(S) services and + how they can announce the features of the API they implement. +

+

+ The endpoint of a reconciliation service is a URL from which the reconciliation + service is offered. +

+
+

Service Manifest

+

+ When the reconciliation service endpoint is queried with a HTTP GET query without + parameters, the service manifest MUST be returned. +

+

+ A service manifest consists of the following fields: +

+
versions
+
The array of API versions supported by the endpoint, such as ["0.1", "0.2"]. Since this field did not exist in version 0.1, services which do not declare a versions field are expected to only support version 0.1. A service implementing the current draft should include 1.0-draft in the array.
+
name
+
A human-readable name for the service, generally the name of the database it exposes. In the case where multiple reconciliation services exist for the same database, it is in the interest of a service to bear a meaningful name which +will help disambiguating it from others;
+
defaultTypes
+
An array of types which are considered sensible default choices as types supplied in reconciliation queries. For services which do not rely on types, this MAY contain a single type with a generic name making it clear that all entities in the +database are instances of this type.
+
documentation
+
An optional URL with human-readable documentation about the service, for instance giving more information about the data it exposes;
+
logo
+
An optional URL of a square image which can be used as the service's logo;
+
serviceVersion
+
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;
+
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;
+
suggest
+
An optional object which may contain the following fields, depending on which suggest services are offered: +
+
entity
+
A boolean indicating if the service supports auto-suggestion of entities;
+
property
+
A boolean indicating if the service supports auto-suggestion of properties;
+
type
+
A boolean indicating if the service supports auto-suggestion of types;
+
+
+
extend
+
A data extension metadata, supplied if the service offers a data extension service.
+
batchSize
+
The maximum number of reconciliation queries in a single reconciliation query batch. The service MAY respond to batches larger than this number with a 413 HTTP error status code [[RFC7231]]
+
authentication
+
An security scheme, supplied if the service supports authentication.
+
lang
+
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: + 


+      

+      

+        A more complete example, with some optional services implemented:
+        

+      

+      

+      

+        
Overview of Possible Routes

+        

+          We give here an overview of the routes that reconciliation services MUST and MAY implement. They are all relative to the root endpoint, which we assume here to be /.
+        

+        

+        

+           
/

+           
The root endpoint, which supports the GET method and returns the service manifest. Services MUST support this route;

+           
/reconcile

+           
The route used to submit reconciliation query batches, with the POST method. Services MUST support this route;

+           
/suggest/entity

+           
The route used for auto-completion of entities, with the GET method. Services MAY support this route, as indicated  in their manifest;

+           
/suggest/property

+           
The route used for auto-completion of properties, with the GET method. Services MAY support this route, as indicated in their manifest;

+           
/suggest/type

+           
The route used for auto-completion of types, with the GET method. Services MAY support this route, as indicated in their manifest;

+           
/preview

+           
The route used to preview an entity, with the GET method. Services MAY support this route, depending on the presence of a preview metadata object in their manifest;

+           
/extend

+           
The route used to submit data extension queries, with the POST method. Services MAY support this route, depending on the presence of a data extension metadata object in their manifest;

+           
/extend/propose

+           
The route used to obtain data extension property proposals, with the GET method. Services MAY support this route, following what their data extension metadata object in their manifest indicates.

+        

+       

+      

+      

+        
HTTP(S) Access

+	

+	   In the interest of protecting the data sent as reconciliation queries, all endpoints of reconciliation
+	   services SHOULD be available over HTTPS [[RFC7230]] [[SECURING-WEB]]. This does not apply to locally hosted services.
+	

+      

+      

+        
Cross-Origin Access

+        

+           All HTTP(S) endpoints exposed by the service MUST enable access by CORS [[cors]] to enable
+           web-based clients to access the service from a different domain without exposing themselves to
+           untrusted third-party code.
+        

+        

+           Some clients might only require cross-origin access on some particular endpoints,
+	   which are called directly by a web UI.
+	   Since this depends on the architecture of the client, this cannot be relied upon
+	   and cross-origin access MUST be implemented for all endpoints in a uniform way.
+        

+      

+      

+        
Error Handling and Rate-limiting

+        

+           Services SHOULD use the broad spectrum of HTTP status codes [[RFC2616]] [[RFC6585]] to
+           expose errors, for instance due to malformed or too frequent queries.
+        

+        

+           The response body of such error responses is not specified so far.
+        

+      

+      
+        
Authentication

+        

+           Services MAY request users to provide an authentication token when making queries.
+           They can do so by adding a security scheme to their manifest. Security schemes are defined in [[OPENAPIS]] and
+           support authentication by API key, HTTP Authentication [[RFC7617]], OAuth 2 [[RFC6749]] and OpenID Connect.
+        

+        

+           For instance, the following security scheme indicates that basic HTTP authentication is required on this endpoint:
+           

+        

+        

+           Requiring an API key passed as a query parameter can be expressed as follows:
+           

+        

+        

+           If a security scheme is provided in the service manifest, all queries to the service MUST provide
+           the corresponding credentials, except for retrieving the service manifest itself.
+           When invalid authentication is supplied in any HTTP request, the service MUST return an HTTP 401 error.
+        

+      

+    
+    

+      
Reconciliation Queries

+      

+        This section specifies how clients can send reconciliation queries to services and
+        how services respond to them.
+      

+      

+        
Structure of a Reconciliation Query

+        

+          A reconciliation query consists of the following fields. 
+          

+	    
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
+	    	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

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

+          

+        

+        

+          A condition specifies a constraint that should be matched by the entities to return.
+                It is used to filter the set of candidates (similar to a WHERE clause in SQL),
+		by allowing clients to specify an attribute of entities that should match. It consists of:
+         

+            
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 matchType is property.

+            
v

+            
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). If omitted, the service SHOULD assume the requested value to be false;

+            
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). If omitted, the service SHOULD assume the requested value to be any;

+            
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 matchQualifier MUST return the supported matchQualifiers for each property
+              in their property suggest responses. If omitted, the matching behavior is up to the service.

+         

+        
+	    A reconciliation service that supports property assignments SHOULD provide a suggest service for discovering these properties.
+        

+        

+          A reconciliation query batch is an array of reconciliation queries.
+        

+        

+          Minimal example of a reconciliation query batch with mandatory fields only:
+          

+        

+        

+          Full example of a reconciliation query batch with all optional fields:
+          

+        

+	

+	  For a single property it is possible to provide multiple values as an array. The values provided do not need
+	  to have the same type. In the following example a string and a reconciled value are provided as values for the
+	  same property.
+	  

+	

+        

+          A JSON schema to validate the serialization of a query batch is available.
+        

+      

+      

+        
Reconciliation Query Responses

+        

+	  A reconciliation candidate represents an entity as a response to a reconciliation query.
+	  It is proposed to the client as a potential matching entity for this query. It contains the following fields:
+          

+	    
id

+	    
The identifier of the candidate entity;

+	    
name

+	    
The name of the candidate entity;

+	    
description

+	    
The entity description MAY optionally be included;

+	    
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. 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

+            
A boolean matching decision, which indicates whether the service considers this candidate good enough to be chosen as a correct match.

+          

+        

+        

+          A matching feature is a numerical or boolean value which can be used to determine how likely it is for the candidate to be the correct entity. It contains the following fields:
+          

+            
id

+            
A string which identifies the feature, such as "name_tfidf" or "pagerank". This id must be unique among all the matching features returned for a given candidate;

+            
name

+            
A human-readable name, which is a non-empty string.

+            
value

+            
The value of the feature for the candidate, which can be any boolean or numerical value.

+          

+         Multiple matching features are often used in combination to provide the final matching score (available
+in the score field). By exposing individual features in their responses, services make it possible for clients
+         to compute matching scores which fit their use cases better.
+        

+        

+          Example of a reconciliation candidate with all possible fields:
+          

+        

+        

+	  A reconciliation result is a set of reconciliation candidates. It is serialized in JSON
+	  as an object containing in the field candidates an array of such reconciliation candidate objects.
+        

+        

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

+        

+        

+          A JSON schema to validate the serialization of a reconciliation result batch is available.
+        

+      

+      

+        
Sending Reconciliation Queries to a Service

+        

+	  The primary role of a reconciliation service is to translate reconciliation query batches to
+	  reconciliation result batches over HTTP.
+	

+	

+          A reconciliation service MUST support HTTP POST requests at the route /reconcile (relative to its endpoint) with
+          application/json bodies containing a
+          reconciliation query batch.
+        

+        

+          
POST /reconcile <reconciliation query batch>

+        

+	

+	   The service returns the corresponding query batch serialized in JSON.
+	

+      

+      

+	
A Note on Candidate Retrieval and Scoring

+	

+	  The way candidates are retrieved from the underlying database and scored against the query is left
+	  entirely at the discretion of the service.
+	  However services should retrieve and score the candidates of each query in a batch independently
+	  of the other queries in the same batch, or in previous ones.
+          It is also expected that reconciliation queries where query matches exactly the name
+          of an entity in the database and with no other constraint should return at least this entity, unless
+          it is hidden by many namesakes. Similarly, supplying an entity identifier as query
+          should return the corresponding entity as a candidate, with a high score.
+	

+	

+	  Deciding on a scoring method is one of the main difficulties in developing a reconciliation service.
+          Depending on the use case, we might not want a score at all: in cases like geo containment (a place should be inside a specific area) or date ranges (a point in time should be inside a specific time range) the score is irrelevant, as candidates are either in or out. Thus the score attribute is optional.
+          Services are encouraged to expose as many matching features as they deem useful, in particular
+          features which require knowledge of global statistics on the database or other attributes. Examples include:
+          

+            
Name matching

+            
Similarity metrics to compare the entity name and the query;

+            
Entity popularity

+            
Metrics which predict how likely an entity is likely to be refered to, regardless of the query supplied;

+            
Comparison of attributes to query properties

+            
Obtained using similarity metrics to compare the supplied properties and measure their discriminative power;

+            
Type matching

+            
To quantify how well any type supplied in the query corresponds to the candidate's types.

+          

+	  By exposing such features, services make it possible for clients to use a wide range of data matching strategies [[christen-2012]]. This also makes the global candidate scores less opaque.
+	

+	

+	  Many open source reconciliation services are available and these might provide some inspiration
+	  concerning indexing and scoring methods when developing new services.
+	  See External Resources for some examples.
+	

+      

+    

+    

+      
Preview Service

+      

+        This section specifies how reconciliation services can provide embeddable HTML previews
+        of their entities, which clients can display in their user interface.
+      

+      

+      
Preview Metadata

+      
Reconciliation services MAY offer a preview service by providing the preview metadata as an object stored in the service manifest under the key preview. It consists of the following fields, all mandatory:
+        

+          
width

+          
The width in pixels of the viewport where to render an entity preview;

+          
height

+          
The height in pixels of the same viewport.

+        

+      

+      

+        For instance, a service may expose the following preview metadata:
+        

+      

+      

+      

+      
Preview Queries

+      
A preview service is queried by resolving the URI template /preview?id={id} relative to the reconciliation endpoint, where id is subsituted by the entity identifier. The URL must resolve to an HTML document,
+        which MUST be viewable in an HTML viewport whose dimensions are determined by the preview metadata.
+      

+      

+        For instance, assuming that the reconciliation API is running at /api and serves the example preview metadata above, the service could respond to a preview request as follows:
+       
+       

+      

+      

+    

+    

+      
Suggest Services

+      

+        This section specifies how reconciliation services can provide auto-complete
+        endpoints for their entities, properties and types.
+        A reconciliation service can offer a suggest service for any of these three classes. For instance, a service which only exposes a single type might not want to expose a suggest service for types.
+        These suggest services can be used by clients to let users select an entity, property or type manually, at various stages of their reconciliation workflows.
+        Suggest services for entities, properties and types are declared independently
+        in the service manifest.
+      

+      

+      
Suggest Endpoints

+      

+        When supported, the suggest endpoints are located at the following URIs, relative to the service's root endpoint:
+        

+          
/suggest/entity

+          
/suggest/property

+          
/suggest/type

+        

+      

+      

+      

+      
Suggest Queries

+        
A suggest service MUST accept GET queries with the following URL-encoded parameters:
+          

+            
prefix

+            
The string input by the user in the auto-suggest-enabled field;
+              depending on the data users are working with, they might want to select a suggestion from all available types, properties, or even entities;
+              to allow that, services MAY send all suggestions if the prefix is empty, and clients SHOULD provide a way to send the empty prefix;

+            
cursor

+            
An optional integer to specify the number of suggestions to skip: this can be used by clients to fetch more suggestions.

+          

+        

+      

+      

+        
Suggest Responses

+        

+          A response to a suggest query consists of the following fields:
+          

+            
result

+            
An array of items, which can be entities, properties
+            or types depending on which of these the service
+            is provided for. Each such object can contain the following fields:
+            

+              
id

+              
The identifier of the entity, property or type suggested;

+              
name

+              
Its corresponding human-readable name, to be displayed prominently to the user;

+              
description

+              
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.

+              
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.

+            

+            

+          

+        

+	

+          The key notable comes from a notion of notable types that existed in Freebase.
+	

+        

+          For instance, a suggest service for entities could return the following response:
+          

+        

+        

+          A suggest service for properties could return the following response:
+          

+        

+        

+          And a  suggest service for types could return the following response:
+          

+        

+	

+	  JSON schemas to validate suggest responses are available for entities, for properties and for types.
+	

+      

+      

+        
General Expectations about Suggest Services

+        

+          It is generally expected by users that an entity suggest query where prefix is the name of an entity should return this entity in the suggest response, unless that entity is hidden behind many other namesakes.
+          Similarly, supplying an entity identifier as prefix should return this entity in the suggest response. 
+          Analogous expectations apply for property and type suggest services.
+        

+        

+          As the prefix name suggests, suggest services are expected to perform prefix search on their database of records, such that a suggest service can be used to provide auto-completion as users type names or identifiers in a field.
+        

+      
      
+    

+    

+      
Data Extension Service

+      

+        This section specifies how reconciliation services can let clients fetch the values
+        of some properties on a selection of entities.
+      

+      

+        A data extension service MUST support data extension query requests.
+      

+      

+        A data extension service SHOULD provide data extension property proposals.
+      

+      

+        A data extension service MAY support data extension property settings.
+      

+      

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

+            
proposeProperties

+            
A boolean indicating if the service supports data extension property proposal;

+            
propertySettings

+            
An array of data extension property settings.

+          

+        

+        

+          A data extension property setting consists of:
+          

+	    
id

+            
A unique identifier for the setting;

+            
name

+	    
A human-readable name, 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 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;

+	    
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.

+          

+        

+        

+          Example of data extension metadata with all optional fields:
+          

+        

+      

+      

+        
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 parameter
+containing a type identifier.
+        

+        

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

+        

+          
GET /extend/propose?type=<type identifier>[&limit=<limit>]

+        

+        

+          A data extension property proposal response consists of:
+          

+            
properties

+            
An array of proposed properties. These properties are suggested as fields that could be potentially fetched via data extension for entities of the type provided in the query;

+            
type

+            
The type identifier supplied in the query;

+            
limit

+            
Optionally, an integer to indicate the requested limit;

+          

+        

+        

+          Example of a data extension property proposal response:
+          

+        

+      

+      

+        
Data Extension Query Requests

+        

+         A data extension query request lets clients fetch the values
+         of some properties on a selection of entities.
+        

+        

+          The fact that a reconciliation service offers data extension MUST be announced by including a data extension metadata in the extend field of the service manifest.
+        

+          A data extension service MUST support HTTP POST requests at /extend (relative to the reconciliation endpoint) with
+          application/json bodies containing a data extension query.
+        

+        

+          
POST /extend <data extension query>

+        

+        

+          A data extension query consists of:
+          

+        

+        

+          Example of a data extension query:
+          

+        

+      

+      

+        
Data Extension Responses

+        

+          A data extension response consists of metadata
+          and rows.
+        

+        

+          The metadata contains the properties used for data
+          extension, as requested in the data extension query. If properties have entities as values,
+          they MAY specify a type in the metadata.
+        

+        

+          The rows object contains, for each entity identifier in the
+          data extension query, for each property identifier in the
+          metadata, the property values of that property in that entity.
+          If the property values are entities, their identifiers are expected to be valid entities for the service at hand.
+          If that is not the case, the service MUST specify in the meta section the endpoint of another reconciliation service for which the entity identifiers are valid, i.e., inserting them into the entity view template of that other service yields valid URIs.
+          This endpoint is specified on a column-per-column basis.
+        

+        

+          Response example for the data extension query from the previous example:
+          

+        

+      

+    

+    

+      
Internationalization Considerations

+      
The following sections rely on terminology from the W3C internationalization best practices for spec developers,
+        in particular on the distinction of two types of language declaration:

+      

+        The language of the intended audience, also referred to as language metadata, is used to describe the language(s) of the intended audience of resources as a whole. In the context of reconciliation,
+        this is relevant e.g. for setting the user interface language in a reconciliation client, providing user-facing text in the user's preferred language.
+      

+      

+        The text-processing language on the other hand declares the single language in which a specific range of text is actually written in, to support features like text-to-speech, spell checking, or hyphenation.
+        In the context of reconciliation, this distinction is importat since the actual data being reconciled will often be in a different language than the client's user interface.
+      

+      

+        
Language of the intended audience

+        

+           Following [[RFC9110]], services SHOULD support the Accept-Language header to let clients specify the language of the intended audience in which user-facing text is returned.
+           If clients set the Accept-Language header, the requested language(s) MUST be provided as well-formed [[BCP 47]] language tags.
+           Services MAY use the Content-Language header in their responses to expose the language(s) of the intended audience(s) of each response.
+           If services set the Content-Language header, they MUST use valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] tags.
+        

+        

+          Examples of user-facing text in service responses are: the name of the service and the name of property configuration fields in the manifest, the name and description of entities, types and properties,
+          the contents of the entity preview pages, and the documentation linked in the manifest.
+        

+      

+      

+        
Text-processing language

+
+        
All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit text-processing language in a lang field.
+        The lang value MUST be a single valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] language tag. This text-processing language applies to the natural language fields of the object: name, description,
+        query (for reconciliation queries), v and str (for property values). Nested objects inherit the text-processing language of their parent, and can override it by setting their own lang value
+        (see example below). A default text-processing language for any natural language string returned or processed by a service MAY be set in the lang field of the service manifest.
+        Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.

+
+        
In the following example, we first set the text-processing language for a reconciliation query to en, which is inherited by the first property, and overridden in the second property with zh-Hant:

+
+        

+          

+        

+
+      

+      

+        
Text direction

+
+        
All objects returned by reconciliation services (entities, types, properties, candidates, features, etc.) MAY declare an explicit text 
+        base direction in a dir field. The dir value MUST be ltr for left-to-right, rtl for right-to-left, or auto for determining the direction by examining the content of each JSON field.
+        This base direction applies to the natural language fields of the object: name and description (for candidates etc.), v and str (for property values).
+        Nested objects inherit the base direction of their parent, and can override it by setting their own dir value. A default base direction for any natural language string returned or processed by a service MAY be set in the dir field of the
+        service manifest. If no explicit base direction is given, left-to-right is considered the default base direction. Clients SHOULD consider the base direction to ensure correct rendering of content, e.g. by setting corresponding dir attributes when rendering JSON responses in HTML.
+        For instance, rendering a Persian label for 'Yahoo!' like یاهو! right-to-left will correctly display as یاهو!.

+
+        
In the following example, we first set the base direction for a data extension response row to ltr, which is inherited by the first property, and overridden in the second property with rtl:

+
+        

+          

+        

+
+      

+    

+    

+      
Accessibility Considerations

+      

+        Reconciliation clients provide user interfaces for creating reconciliation queries and reviewing reconciliation candidates, including preview
+        and suggest services, as well as for interacting with data extension services, including property proposals 
+        and configuration of property settings. These user interfaces SHOULD be implemented ensuring [[accessibility]] for all people, whatever their hardware,
+        software, language, location, or ability.
+      

+      

+        
Visual rendering

+        

+          The preview service provides HTML content to reconciliation clients. Using HTML allows services to provide non-text alternatives for text content, as well as 
+          semantically rich content (structure, styled text, hyperlinks, etc). Reconciliation services SHOULD ensure [[accessibility]] of this HTML content (avoid fixed font sizes, provide alternative text for images etc).
+          The service's preview metadata contains the suggested width and height to display the preview content. Reconciliation clients SHOULD consider adjusting these values as required for supporting accessibility features like UI scaling.
+        

+        

+          Except for the preview content and size, all data involved in the reconciliation and data extension process is text-based and contains no specifics about visual rendering. Reconciliation clients SHOULD ensure [[accessibility]] for this text content
+          (font resizing, screen reader support etc.) based on the technology of the underlying platform, which will typically implement the details of visual text rendering and user interface customization.
+        

+      

+      

+        
Content semantics

+        

+          The main content presented to users is provided in reconciliation results and data extension responses. Both support name fields for all identifiable objects, in particular
+          entities, types, properties, and matching features. These SHOULD be used by reconciliation clients to provide useful labels for displaying and linking identifiable entities. 
+          The structural semantics of the content provided by reconciliation services allows different presentations (as pages, tables, etc.) in reconciliation clients. Being fully text- and JSON-based, content can 
+          be modified by third-party tools to enhance accessibility.
+        

+      

+    

+    

+      
Security Considerations

+
+      

+        
Preventing Abuse

+        
    
+          
  • Reconciliation services SHOULD guard against too frequent requests to prevent [[DoS]] attacks (see Error Handling and Rate-limiting).
    • 
+          
  • Reconciliation services SHOULD guard against malicious code when querying their underlying data store with data from reconciliation queries to avoid code [[injection]].
    • 
+          
  • Reconciliation services SHOULD NOT parse the JSON requests sent by clients using a code execution mechanism like JavaScript's eval(), since requests could contain malicious code.
    • 
+          
  • Reconciliation clients that display data from preview services SHOULD ensure that the data is encoded, sanitized, or isolated to prevent [[XSS]] and [[CSRF]] attacks.
    • 
+        

+      

+
+      

+        
Other considerations

+        
    
+          
  • Reconciliation services and clients MAY support user authentication (see authentication).
    • 
+          
  • Reconciliation features don't expose information about the underlying platform to clients or services, they don't allow clients or services to send data to the underlying platform, access other devices, device sensors, 
+            a user agent's native UI, or enable clients or services to downgrade default security protections.
+          
    • 
+        

+      

+
+    

+
+    

+      
Privacy Considerations

+
+      

+        
Network data

+        
    
+          
  • All data in reconciliation queries is visible to the reconciliation service, to be processed for returning reconciliation results to the client.
+            To prevent malicious actors from intercepting the data that is sent and received, services SHOULD provide secure HTTPS endpoints for reconciliation.
+          
    • 
+          
  • User selections of matching reconciliation candidates provide user-verified statements about the data. These selections are currently not sent back to the reconciliation service
+            (but that may change with #30).
+          
    • 
+        

+      

+
+      

+        
Persistent data

+        
    
+          
  • Reconciliation clients MAY introduce new state that persists across browsing sessions for persisting reconciliation queries,
+            the service's reconciliation results, and/or the user's selection of matches.
    • 
+          
  • Reconciliation clients implemented as browser extensions running in Private Browsing or Incognito mode SHOULD NOT store reconciliation queries,
+            the service's reconciliation results, or the user's selection of matches.
    • 
+          
  • Reconciliation services currently don't introduce new state that persists across browsing sessions (but that may change with #30).
    • 
+          
+        

+      

+
+    

+
+    

+      
JSON Schemas

+        

+          This appendix provides JSON schemas [[json-schema]] which can be used to validate the JSON serialization
+          of various elements as specified by these specifications.
+        

+      

+        
Manifest Schema

+        

+          The manifest schema can be used to validate a service manifest.
+        

+        
+      

+      

+        
Reconciliation Query Batch Schema

+	    

+	      The reconciliation query batch schema can be used to validate
+	      the JSON serialization of any reconciliation query batch, i.e. the payload of a GET/POST to the reconciliation endpoint.
+	   

+	   
+      

+      

+        
Reconciliation Result Batch Schema

+	    

+          The reconciliation result batch schema can be used to validate the JSON serialization of any reconciliation result batch.
+        

+        
+      

+      

+        
Suggest Entities Response Schema

+	

+          The suggest entities response schema can be used to validate the JSON serialization of any suggest response for entities.
+        

+        
+      

+      

+        
Suggest Properties Response Schema

+	

+          The suggest properties response schema can be used to validate the JSON serialization of any suggest response for properties.
+        

+        
+      

+      

+        
Suggest Types Response Schema

+	

+          The suggest types response schema can be used to validate the JSON serialization of any suggest response for types.
+        

+        
+      

+      

+        
Data Extension Property Proposal Schema

+        

+          The data extension query schema validates data extension property proposal responses.
+        

+        
+      

+      

+        
Data Extension Query Schema

+        

+          The data extension query schema validates data extension queries.
+        

+        
+      

+      

+        
Data Extension Response Schema

+        

+          The data extension response schema validates data extension responses.
+        

+        
+      

+    

+  
+
diff --git a/draft/schemas/data-extension-property-proposal.json b/1.0-draft/schemas/data-extension-property-proposal.json
similarity index 100%
rename from draft/schemas/data-extension-property-proposal.json
rename to 1.0-draft/schemas/data-extension-property-proposal.json
diff --git a/draft/schemas/data-extension-query.json b/1.0-draft/schemas/data-extension-query.json
similarity index 100%
rename from draft/schemas/data-extension-query.json
rename to 1.0-draft/schemas/data-extension-query.json
diff --git a/draft/schemas/data-extension-response.json b/1.0-draft/schemas/data-extension-response.json
similarity index 100%
rename from draft/schemas/data-extension-response.json
rename to 1.0-draft/schemas/data-extension-response.json
diff --git a/draft/schemas/manifest.json b/1.0-draft/schemas/manifest.json
similarity index 100%
rename from draft/schemas/manifest.json
rename to 1.0-draft/schemas/manifest.json
diff --git a/draft/schemas/openapi.json b/1.0-draft/schemas/openapi.json
similarity index 100%
rename from draft/schemas/openapi.json
rename to 1.0-draft/schemas/openapi.json
diff --git a/draft/schemas/reconciliation-query-batch.json b/1.0-draft/schemas/reconciliation-query-batch.json
similarity index 100%
rename from draft/schemas/reconciliation-query-batch.json
rename to 1.0-draft/schemas/reconciliation-query-batch.json
diff --git a/draft/schemas/reconciliation-result-batch.json b/1.0-draft/schemas/reconciliation-result-batch.json
similarity index 100%
rename from draft/schemas/reconciliation-result-batch.json
rename to 1.0-draft/schemas/reconciliation-result-batch.json
diff --git a/draft/schemas/suggest-entities-response.json b/1.0-draft/schemas/suggest-entities-response.json
similarity index 100%
rename from draft/schemas/suggest-entities-response.json
rename to 1.0-draft/schemas/suggest-entities-response.json
diff --git a/draft/schemas/suggest-properties-response.json b/1.0-draft/schemas/suggest-properties-response.json
similarity index 100%
rename from draft/schemas/suggest-properties-response.json
rename to 1.0-draft/schemas/suggest-properties-response.json
diff --git a/draft/schemas/suggest-types-response.json b/1.0-draft/schemas/suggest-types-response.json
similarity index 100%
rename from draft/schemas/suggest-types-response.json
rename to 1.0-draft/schemas/suggest-types-response.json
diff --git a/draft/schemas/type.json b/1.0-draft/schemas/type.json
similarity index 100%
rename from draft/schemas/type.json
rename to 1.0-draft/schemas/type.json
diff --git a/draft/index.html b/draft/index.html
index aae013a..43d4ba7 100644
--- a/draft/index.html
+++ b/draft/index.html
@@ -1,1138 +1,15 @@
-
+
 
-  
-    
-    
-    
-    Reconciliation Service API
-  
-  
-    

-      

-        This document describes the reconciliation service API, a protocol edited by the
-        W3C Entity Reconciliation Community Group.
-        It is intended as a comprehensive and definitive specification of this API in its given state.
-	Various aspects of this API need to be improved, as hinted by notes throughout this document.
-      

-    

-    

-      

-        Members of the Community Group are encouraged to contribute to this document by
-        documenting the current behaviour of the reconciliation API.
-        The ReSpec Editor's Guide
-        can be used to learn more about the markup to use in this document.
-      

-    

-    

-      
Introduction

-      

-        
Data Matching on the Web

-        

-          Integrating data from sources which do not share common unique identifiers often requires matching (or reconciling, merging) records which refer to the same entities.
-	  The promises of the Linked Open Data movement, the ability to mix up data from different publishers expressed in a common language (such as RDF) rely on being able to identify identities across services.
-	  Due to the Web's decentralized nature, there is nothing preventing a service from publishing a new URI for a resource or concept which is
-already expressed by another URI.
-        

-	

-	  Various mechanisms exist to state the equivalence between two URIs: for instance, such a correspondence can be stated with the owl:sameAs property [[owl-features]], or using looser notions equivalences defined in SKOS [[skos-primer]]. But such statements must in turn be themselves findable.
-          One can aggregate owl:sameAs statements from various sources to infer identities by transitivity, but this is a subtle art as some data sources can erroneously equate different concepts [[beek-2018]].
-          After all, any quest towards building a universal identifier system which avoids duplicates is necessarily doomed.
-          Data publishers use different granularities to model the world. Concepts have fluctuating boundaries across languages, cultures and time.
-        

-        

-          In practice, we can determine if two database records refer to the same entity by comparing their attributes.
-          For instance, two entries about cities bearing the same name, in the same country and with the same mayor are likely to refer to the same city.
-          The reconciliation API that we present here makes it easier to discover such matches.
-          It is a protocol that a data provider can implement, enabling its consumers to efficiently match their own data to the entities represented by the provider.
-        

-        

-          By nature, reconciliation is a heuristic process. Different entities can have many identical characteristics, leading to false positives.
-          The same entity can be represented in different ways by two databases, for instance by spelling names differently, leading to false negatives.
-          This problem has been extensively studied and many heuristics have been proposed to tackle it [[christen-2012]].
-	  The reconciliation API is agnostic about the particulars of the heuristics involved: it lets data providers choose how
-	  they want to determine which of their entities are good candidates for a particular query. What it provides
-	  is a web API to let users obtain these candidate entities without having to implement the underlying reconciliation heuristics
-	  themselves, nor download the entire contents of the target database.
-        

-      

-      

-        
History of the Reconciliation API

-        

-          This API was originally designed by Metaweb as a protocol used between Freebase and Gridworks (now known as OpenRefine).
-	  Freebase was a free crowdsourced knowledge graph, storing data about a broad range of topics and exposed on the web as linked data.
-	  OpenRefine is tool which was originally designed to help populate this knowledge graph by importing data into it.
-	  It supports a range of operations which help the user reshape their data to prepare it for ingestion in a data model such as Freebase's.
-	  One of these operations is reconciliation, which matches mentions of entities in the local dataset to records in the target database. The reconciliation API was initially introduced to specify how OpenRefine and Freebase could communicate during that process. 
-        

-	

-	  The reconciliation API was then turned into a generic protocol that any database could implement.
-	  This made it possible to register such a database into OpenRefine by adding it as a Standard Service.
-	  This API was implemented by various services, either directly by the service provider itself (for instance the Crossref funder database,
-	  Nomisma or the Getty thesaurus) or by a third party as a wrapper sitting on top of other existing web APIs for the service
-	  (such as Wikidata or VIAF).
-	  Software was also developed to expose a reconciliation endpoint out of any tabular file (reconcile-csv) or by wrapping a SPARQL endpoint (in the OpenRefine RDF extension).
-	

-	

-	This API was documented on OpenRefine's wiki as a living document which evolved gradually, as OpenRefine improved.
-	  In addition to its core feature, fetching reconciliation candidates matching a given query, services are optionally able
-	  to implement additional endpoints which ease the integration of the service in OpenRefine's UI, by providing previews
-	  for entities (with a Preview Service) and auto-completion for various inputs (with Suggest Services).
-	  In 2018, a Data Extension Service was added, letting consumers pull data from the target database once they have reconciled
-	  their records.
-        

-        

-          In 2019 the W3C Entity Reconciliation Community Group was formed,
-	  with the intention of promoting and improving this API outside the strict scope of the OpenRefine project.
-	  This document is an attempt to better specify this API.
-	

-      

-      

-        
External Resources

-        

-          A list of known public endpoints is maintained by the community, where they can also be tried out interactively. OpenRefine's wiki also hosts a list of reconciliable data source which also includes non-hosted or discontinued services.
-	  Existing clients to the API, such as OpenRefine or Cocoda can be used to interact with reconciliation services.
-        

-      

-      

-        
Versions

-        

-          This section summarizes the differences between successive versions of the API.
-        

-        

-          
0.1

-          
Initial documentation of the reconciliation API as supported by OpenRefine 3.0 to 3.2.

-        

-        

-          
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
    • 
-          

-        

-        

-          
This draft: 1.0-draft

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

-          
-        

-      

-      

-    

-    

-      
Core Concepts

-      

-        This section documents the data model behind the reconciliation API.
-        A reconciliation service lets users match their data against entities
-        exposed by the service. Matching can be refined by filtering by type
-        or properties with property values.
-        The purpose of this section is to define these notions.
-      

-      

-        
Entities

-        

-           An entity is a record in the data source exposed by the service.
-           It comprises the following fields:
-           

-	     
id

-             
an identifier, which is a non-empty string. This identifier must be unique among all entities;

-             
name

-             
a name, which is also a non-empty string;

-             
description

-             
an optional description as a human-readable string;

-             
type

-             
an array of types, possibly empty;

-           

-           Moreover, for each property the entity contains a set of associated property values, possibly empty.
-        

-        

-           Reconciliation services MUST define in their service manifest a URI template for entities,
-           as defined by [[RFC6570]]. This URI template builds a view URI for each entity, and has id as only variable.
-           For each entity, expanding the template with id being set to the entity's identifier
-           MUST result in a valid URI.
-        

-        

-           For example, a service which uses Wikidata identifiers for its entities could use http://www.wikidata.org/entity/{id}
-           as URI template for entities. For an entity with identifier Q5, this would expand to http://www.wikidata.org/entity/Q5.
-           Services for which the entity's identifier is already a full URI can use the {+id} template, which disables the escaping of some characters
-           when inserting the identifier in the template.
-           See [[RFC6570]] for more examples of URI templates.   
-        

-        

-           Similarly, it is possible to associate to each matching feature a URL where documentation about
-           the feature is provided, by means of a URI template. Inserting any feature identifier in this template
-           generates the URL for the feature.
-        

-      

-      

-        
Types

-        

-          A type represents a category of entities.
-          It comprises the following fields:
-          

-             
id

-             
an identifier, which is a non-empty string. This identifier must be unique among all types;

-             
name

-             
a human-readable name, which is a non-empty string;

-             
broader

-             
an optional array of types, each representing a direct (i.e., immediate) broader [[skos-reference]] category of entities.

-          

-        

-      

-      

-        
Properties

-        

-          A property represents a type of attribute that entities can have in the data source.
-          It comprises the following fields:
-          

-	    
id

-            
an identifier, which is a non-empty string. This identifier must be unique among all properties;

-	    
name

-            
a human-readable name, which is a non-empty string.

-          

-        

-      

-      

-        
Property Values

-        

-          A property value can be any of the following:
-          
    
-             
  • A string;
    • 
-             
  • A boolean;
    • 
-             
  • An integer;
    • 
-             
  • A floating-point value;
    • 
-             
  • An entity.
    • 
-          

-        

-      

-    

-    

-      
Service Definition

-      

-        This section documents how reconciliation services are exposed as HTTP(S) services and
-        how they can announce the features of the API they implement.
-      

-      

-        The endpoint of a reconciliation service is a URL from which the reconciliation
-        service is offered.
-      

-      

-        
Service Manifest

-        

-           When the reconciliation service endpoint is queried with a HTTP GET query without
-           parameters, the service manifest MUST be returned.
-        

-      

-        A service manifest consists of the following fields:
-        

-          
versions

-          
The array of API versions supported by the endpoint, such as ["0.1", "0.2"]. Since this field did not exist in version 0.1, services which do not declare a versions field are expected to only support version 0.1. A service implementing the current draft should include 1.0-draft in the array.

-          
name

-          
A human-readable name for the service, generally the name of the database it exposes. In the case where multiple reconciliation services exist for the same database, it is in the interest of a service to bear a meaningful name which
-will help disambiguating it from others;

-          
defaultTypes

-          
An array of types which are considered sensible default choices as types supplied in reconciliation queries. For services which do not rely on types, this MAY contain a single type with a generic name making it clear that all entities in the
-database are instances of this type.

-          
documentation

-          
An optional URL with human-readable documentation about the service, for instance giving more information about the data it exposes;

-          
logo

-          
An optional URL of a square image which can be used as the service's logo;

-          
serviceVersion

-          
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;

-          
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;

-          
suggest

-          
An optional object which may contain the following fields, depending on which suggest services are offered:
-            

-              
entity

-              
A boolean indicating if the service supports auto-suggestion of entities;

-              
property

-              
A boolean indicating if the service supports auto-suggestion of properties;

-              
type

-              
A boolean indicating if the service supports auto-suggestion of types;

-            

-          

-          
extend

-          
A data extension metadata, supplied if the service offers a data extension service.

-          
batchSize

-          
The maximum number of reconciliation queries in a single reconciliation query batch.  The service MAY respond to batches larger than this number with a 413 HTTP error status code [[RFC7231]]

-          
authentication

-          
An security scheme, supplied if the service supports authentication.

-          
lang

-          
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:
-        

-      

-      

-        A more complete example, with some optional services implemented:
-        

-      

-      

-      

-        
Overview of Possible Routes

-        

-          We give here an overview of the routes that reconciliation services MUST and MAY implement. They are all relative to the root endpoint, which we assume here to be /.
-        

-        

-        

-           
/

-           
The root endpoint, which supports the GET method and returns the service manifest. Services MUST support this route;

-           
/reconcile

-           
The route used to submit reconciliation query batches, with the POST method. Services MUST support this route;

-           
/suggest/entity

-           
The route used for auto-completion of entities, with the GET method. Services MAY support this route, as indicated  in their manifest;

-           
/suggest/property

-           
The route used for auto-completion of properties, with the GET method. Services MAY support this route, as indicated in their manifest;

-           
/suggest/type

-           
The route used for auto-completion of types, with the GET method. Services MAY support this route, as indicated in their manifest;

-           
/preview

-           
The route used to preview an entity, with the GET method. Services MAY support this route, depending on the presence of a preview metadata object in their manifest;

-           
/extend

-           
The route used to submit data extension queries, with the POST method. Services MAY support this route, depending on the presence of a data extension metadata object in their manifest;

-           
/extend/propose

-           
The route used to obtain data extension property proposals, with the GET method. Services MAY support this route, following what their data extension metadata object in their manifest indicates.

-        

-       

-      

-      

-        
HTTP(S) Access

-	

-	   In the interest of protecting the data sent as reconciliation queries, all endpoints of reconciliation
-	   services SHOULD be available over HTTPS [[RFC7230]] [[SECURING-WEB]]. This does not apply to locally hosted services.
-	

-      

-      

-        
Cross-Origin Access

-        

-           All HTTP(S) endpoints exposed by the service MUST enable access by CORS [[cors]] to enable
-           web-based clients to access the service from a different domain without exposing themselves to
-           untrusted third-party code.
-        

-        

-           Some clients might only require cross-origin access on some particular endpoints,
-	   which are called directly by a web UI.
-	   Since this depends on the architecture of the client, this cannot be relied upon
-	   and cross-origin access MUST be implemented for all endpoints in a uniform way.
-        

-      

-      

-        
Error Handling and Rate-limiting

-        

-           Services SHOULD use the broad spectrum of HTTP status codes [[RFC2616]] [[RFC6585]] to
-           expose errors, for instance due to malformed or too frequent queries.
-        

-        

-           The response body of such error responses is not specified so far.
-        

-      

-      
-        
Authentication

-        

-           Services MAY request users to provide an authentication token when making queries.
-           They can do so by adding a security scheme to their manifest. Security schemes are defined in [[OPENAPIS]] and
-           support authentication by API key, HTTP Authentication [[RFC7617]], OAuth 2 [[RFC6749]] and OpenID Connect.
-        

-        

-           For instance, the following security scheme indicates that basic HTTP authentication is required on this endpoint:
-           

-        

-        

-           Requiring an API key passed as a query parameter can be expressed as follows:
-           

-        

-        

-           If a security scheme is provided in the service manifest, all queries to the service MUST provide
-           the corresponding credentials, except for retrieving the service manifest itself.
-           When invalid authentication is supplied in any HTTP request, the service MUST return an HTTP 401 error.
-        

-      

-    
-    

-      
Reconciliation Queries

-      

-        This section specifies how clients can send reconciliation queries to services and
-        how services respond to them.
-      

-      

-        
Structure of a Reconciliation Query

-        

-          A reconciliation query consists of the following fields. 
-          

-	    
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
-	    	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

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

-          

-        

-        

-          A condition specifies a constraint that should be matched by the entities to return.
-                It is used to filter the set of candidates (similar to a WHERE clause in SQL),
-		by allowing clients to specify an attribute of entities that should match. It consists of:
-         

-            
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 matchType is property.

-            
v

-            
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). If omitted, the service SHOULD assume the requested value to be false;

-            
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). If omitted, the service SHOULD assume the requested value to be any;

-            
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 matchQualifier MUST return the supported matchQualifiers for each property
-              in their property suggest responses. If omitted, the matching behavior is up to the service.

-         

-        
-	    A reconciliation service that supports property assignments SHOULD provide a suggest service for discovering these properties.
-        

-        

-          A reconciliation query batch is an array of reconciliation queries.
-        

-        

-          Minimal example of a reconciliation query batch with mandatory fields only:
-          

-        

-        

-          Full example of a reconciliation query batch with all optional fields:
-          

-        

-	

-	  For a single property it is possible to provide multiple values as an array. The values provided do not need
-	  to have the same type. In the following example a string and a reconciled value are provided as values for the
-	  same property.
-	  

-	

-        

-          A JSON schema to validate the serialization of a query batch is available.
-        

-      

-      

-        
Reconciliation Query Responses

-        

-	  A reconciliation candidate represents an entity as a response to a reconciliation query.
-	  It is proposed to the client as a potential matching entity for this query. It contains the following fields:
-          

-	    
id

-	    
The identifier of the candidate entity;

-	    
name

-	    
The name of the candidate entity;

-	    
description

-	    
The entity description MAY optionally be included;

-	    
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. 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

-            
A boolean matching decision, which indicates whether the service considers this candidate good enough to be chosen as a correct match.

-          

-        

-        

-          A matching feature is a numerical or boolean value which can be used to determine how likely it is for the candidate to be the correct entity. It contains the following fields:
-          

-            
id

-            
A string which identifies the feature, such as "name_tfidf" or "pagerank". This id must be unique among all the matching features returned for a given candidate;

-            
name

-            
A human-readable name, which is a non-empty string.

-            
value

-            
The value of the feature for the candidate, which can be any boolean or numerical value.

-          

-         Multiple matching features are often used in combination to provide the final matching score (available
-in the score field). By exposing individual features in their responses, services make it possible for clients
-         to compute matching scores which fit their use cases better.
-        

-        

-          Example of a reconciliation candidate with all possible fields:
-          

-        

-        

-	  A reconciliation result is a set of reconciliation candidates. It is serialized in JSON
-	  as an object containing in the field candidates an array of such reconciliation candidate objects.
-        

-        

-          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:
-          

-        

-        

-          A JSON schema to validate the serialization of a reconciliation result batch is available.
-        

-      

-      

-        
Sending Reconciliation Queries to a Service

-        

-	  The primary role of a reconciliation service is to translate reconciliation query batches to
-	  reconciliation result batches over HTTP.
-	

-	

-          A reconciliation service MUST support HTTP POST requests at the route /reconcile (relative to its endpoint) with
-          application/json bodies containing a
-          reconciliation query batch.
-        

-        

-          
POST /reconcile <reconciliation query batch>

-        

-	

-	   The service returns the corresponding query batch serialized in JSON.
-	

-      

-      

-	
A Note on Candidate Retrieval and Scoring

-	

-	  The way candidates are retrieved from the underlying database and scored against the query is left
-	  entirely at the discretion of the service.
-	  However services should retrieve and score the candidates of each query in a batch independently
-	  of the other queries in the same batch, or in previous ones.
-          It is also expected that reconciliation queries where query matches exactly the name
-          of an entity in the database and with no other constraint should return at least this entity, unless
-          it is hidden by many namesakes. Similarly, supplying an entity identifier as query
-          should return the corresponding entity as a candidate, with a high score.
-	

-	

-	  Deciding on a scoring method is one of the main difficulties in developing a reconciliation service.
-          Depending on the use case, we might not want a score at all: in cases like geo containment (a place should be inside a specific area) or date ranges (a point in time should be inside a specific time range) the score is irrelevant, as candidates are either in or out. Thus the score attribute is optional.
-          Services are encouraged to expose as many matching features as they deem useful, in particular
-          features which require knowledge of global statistics on the database or other attributes. Examples include:
-          

-            
Name matching

-            
Similarity metrics to compare the entity name and the query;

-            
Entity popularity

-            
Metrics which predict how likely an entity is likely to be refered to, regardless of the query supplied;

-            
Comparison of attributes to query properties

-            
Obtained using similarity metrics to compare the supplied properties and measure their discriminative power;

-            
Type matching

-            
To quantify how well any type supplied in the query corresponds to the candidate's types.

-          

-	  By exposing such features, services make it possible for clients to use a wide range of data matching strategies [[christen-2012]]. This also makes the global candidate scores less opaque.
-	

-	

-	  Many open source reconciliation services are available and these might provide some inspiration
-	  concerning indexing and scoring methods when developing new services.
-	  See External Resources for some examples.
-	

-      

-    

-    

-      
Preview Service

-      

-        This section specifies how reconciliation services can provide embeddable HTML previews
-        of their entities, which clients can display in their user interface.
-      

-      

-      
Preview Metadata

-      
Reconciliation services MAY offer a preview service by providing the preview metadata as an object stored in the service manifest under the key preview. It consists of the following fields, all mandatory:
-        

-          
width

-          
The width in pixels of the viewport where to render an entity preview;

-          
height

-          
The height in pixels of the same viewport.

-        

-      

-      

-        For instance, a service may expose the following preview metadata:
-        

-      

-      

-      

-      
Preview Queries

-      
A preview service is queried by resolving the URI template /preview?id={id} relative to the reconciliation endpoint, where id is subsituted by the entity identifier. The URL must resolve to an HTML document,
-        which MUST be viewable in an HTML viewport whose dimensions are determined by the preview metadata.
-      

-      

-        For instance, assuming that the reconciliation API is running at /api and serves the example preview metadata above, the service could respond to a preview request as follows:
-       
-       

-      

-      

-    

-    

-      
Suggest Services

-      

-        This section specifies how reconciliation services can provide auto-complete
-        endpoints for their entities, properties and types.
-        A reconciliation service can offer a suggest service for any of these three classes. For instance, a service which only exposes a single type might not want to expose a suggest service for types.
-        These suggest services can be used by clients to let users select an entity, property or type manually, at various stages of their reconciliation workflows.
-        Suggest services for entities, properties and types are declared independently
-        in the service manifest.
-      

-      

-      
Suggest Endpoints

-      

-        When supported, the suggest endpoints are located at the following URIs, relative to the service's root endpoint:
-        

-          
/suggest/entity

-          
/suggest/property

-          
/suggest/type

-        

-      

-      

-      

-      
Suggest Queries

-        
A suggest service MUST accept GET queries with the following URL-encoded parameters:
-          

-            
prefix

-            
The string input by the user in the auto-suggest-enabled field;
-              depending on the data users are working with, they might want to select a suggestion from all available types, properties, or even entities;
-              to allow that, services MAY send all suggestions if the prefix is empty, and clients SHOULD provide a way to send the empty prefix;

-            
cursor

-            
An optional integer to specify the number of suggestions to skip: this can be used by clients to fetch more suggestions.

-          

-        

-      

-      

-        
Suggest Responses

-        

-          A response to a suggest query consists of the following fields:
-          

-            
result

-            
An array of items, which can be entities, properties
-            or types depending on which of these the service
-            is provided for. Each such object can contain the following fields:
-            

-              
id

-              
The identifier of the entity, property or type suggested;

-              
name

-              
Its corresponding human-readable name, to be displayed prominently to the user;

-              
description

-              
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.

-              
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.

-            

-            

-          

-        

-	

-          The key notable comes from a notion of notable types that existed in Freebase.
-	

-        

-          For instance, a suggest service for entities could return the following response:
-          

-        

-        

-          A suggest service for properties could return the following response:
-          

-        

-        

-          And a  suggest service for types could return the following response:
-          

-        

-	

-	  JSON schemas to validate suggest responses are available for entities, for properties and for types.
-	

-      

-      

-        
General Expectations about Suggest Services

-        

-          It is generally expected by users that an entity suggest query where prefix is the name of an entity should return this entity in the suggest response, unless that entity is hidden behind many other namesakes.
-          Similarly, supplying an entity identifier as prefix should return this entity in the suggest response. 
-          Analogous expectations apply for property and type suggest services.
-        

-        

-          As the prefix name suggests, suggest services are expected to perform prefix search on their database of records, such that a suggest service can be used to provide auto-completion as users type names or identifiers in a field.
-        

-      
      
-    

-    

-      
Data Extension Service

-      

-        This section specifies how reconciliation services can let clients fetch the values
-        of some properties on a selection of entities.
-      

-      

-        A data extension service MUST support data extension query requests.
-      

-      

-        A data extension service SHOULD provide data extension property proposals.
-      

-      

-        A data extension service MAY support data extension property settings.
-      

-      

-        
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:
-          

-            
proposeProperties

-            
A boolean indicating if the service supports data extension property proposal;

-            
propertySettings

-            
An array of data extension property settings.

-          

-        

-        

-          A data extension property setting consists of:
-          

-	    
id

-            
A unique identifier for the setting;

-            
name

-	    
A human-readable name, 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 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;

-	    
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.

-          

-        

-        

-          Example of data extension metadata with all optional fields:
-          

-        

-      

-      

-        
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 parameter
-containing a type identifier.
-        

-        

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

-        

-          
GET /extend/propose?type=<type identifier>[&limit=<limit>]

-        

-        

-          A data extension property proposal response consists of:
-          

-            
properties

-            
An array of proposed properties. These properties are suggested as fields that could be potentially fetched via data extension for entities of the type provided in the query;

-            
type

-            
The type identifier supplied in the query;

-            
limit

-            
Optionally, an integer to indicate the requested limit;

-          

-        

-        

-          Example of a data extension property proposal response:
-          

-        

-      

-      

-        
Data Extension Query Requests

-        

-         A data extension query request lets clients fetch the values
-         of some properties on a selection of entities.
-        

-        

-          The fact that a reconciliation service offers data extension MUST be announced by including a data extension metadata in the extend field of the service manifest.
-        

-          A data extension service MUST support HTTP POST requests at /extend (relative to the reconciliation endpoint) with
-          application/json bodies containing a data extension query.
-        

-        

-          
POST /extend <data extension query>

-        

-        

-          A data extension query consists of:
-          

-        

-        

-          Example of a data extension query:
-          

-        

-      

-      

-        
Data Extension Responses

-        

-          A data extension response consists of metadata
-          and rows.
-        

-        

-          The metadata contains the properties used for data
-          extension, as requested in the data extension query. If properties have entities as values,
-          they MAY specify a type in the metadata.
-        

-        

-          The rows object contains, for each entity identifier in the
-          data extension query, for each property identifier in the
-          metadata, the property values of that property in that entity.
-          If the property values are entities, their identifiers are expected to be valid entities for the service at hand.
-          If that is not the case, the service MUST specify in the meta section the endpoint of another reconciliation service for which the entity identifiers are valid, i.e., inserting them into the entity view template of that other service yields valid URIs.
-          This endpoint is specified on a column-per-column basis.
-        

-        

-          Response example for the data extension query from the previous example:
-          

-        

-      

-    

-    

-      
Internationalization Considerations

-      
The following sections rely on terminology from the W3C internationalization best practices for spec developers,
-        in particular on the distinction of two types of language declaration:

-      

-        The language of the intended audience, also referred to as language metadata, is used to describe the language(s) of the intended audience of resources as a whole. In the context of reconciliation,
-        this is relevant e.g. for setting the user interface language in a reconciliation client, providing user-facing text in the user's preferred language.
-      

-      

-        The text-processing language on the other hand declares the single language in which a specific range of text is actually written in, to support features like text-to-speech, spell checking, or hyphenation.
-        In the context of reconciliation, this distinction is importat since the actual data being reconciled will often be in a different language than the client's user interface.
-      

-      

-        
Language of the intended audience

-        

-           Following [[RFC9110]], services SHOULD support the Accept-Language header to let clients specify the language of the intended audience in which user-facing text is returned.
-           If clients set the Accept-Language header, the requested language(s) MUST be provided as well-formed [[BCP 47]] language tags.
-           Services MAY use the Content-Language header in their responses to expose the language(s) of the intended audience(s) of each response.
-           If services set the Content-Language header, they MUST use valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] tags.
-        

-        

-          Examples of user-facing text in service responses are: the name of the service and the name of property configuration fields in the manifest, the name and description of entities, types and properties,
-          the contents of the entity preview pages, and the documentation linked in the manifest.
-        

-      

-      

-        
Text-processing language

-
-        
All objects used in this protocol (entities, types, properties, queries, candidates, features, etc.) MAY declare an explicit text-processing language in a lang field.
-        The lang value MUST be a single valid (i.e. found in the [[IANA Language Subtag Registry]]) [[BCP 47]] language tag. This text-processing language applies to the natural language fields of the object: name, description,
-        query (for reconciliation queries), v and str (for property values). Nested objects inherit the text-processing language of their parent, and can override it by setting their own lang value
-        (see example below). A default text-processing language for any natural language string returned or processed by a service MAY be set in the lang field of the service manifest.
-        Client and service implementors SHOULD consider the text-processing language to ensure correct processing of natural language content.

-
-        
In the following example, we first set the text-processing language for a reconciliation query to en, which is inherited by the first property, and overridden in the second property with zh-Hant:

-
-        

-          

-        

-
-      

-      

-        
Text direction

-
-        
All objects returned by reconciliation services (entities, types, properties, candidates, features, etc.) MAY declare an explicit text 
-        base direction in a dir field. The dir value MUST be ltr for left-to-right, rtl for right-to-left, or auto for determining the direction by examining the content of each JSON field.
-        This base direction applies to the natural language fields of the object: name and description (for candidates etc.), v and str (for property values).
-        Nested objects inherit the base direction of their parent, and can override it by setting their own dir value. A default base direction for any natural language string returned or processed by a service MAY be set in the dir field of the
-        service manifest. If no explicit base direction is given, left-to-right is considered the default base direction. Clients SHOULD consider the base direction to ensure correct rendering of content, e.g. by setting corresponding dir attributes when rendering JSON responses in HTML.
-        For instance, rendering a Persian label for 'Yahoo!' like یاهو! right-to-left will correctly display as یاهو!.

-
-        
In the following example, we first set the base direction for a data extension response row to ltr, which is inherited by the first property, and overridden in the second property with rtl:

-
-        

-          

-        

-
-      

-    

-    

-      
Accessibility Considerations

-      

-        Reconciliation clients provide user interfaces for creating reconciliation queries and reviewing reconciliation candidates, including preview
-        and suggest services, as well as for interacting with data extension services, including property proposals 
-        and configuration of property settings. These user interfaces SHOULD be implemented ensuring [[accessibility]] for all people, whatever their hardware,
-        software, language, location, or ability.
-      

-      

-        
Visual rendering

-        

-          The preview service provides HTML content to reconciliation clients. Using HTML allows services to provide non-text alternatives for text content, as well as 
-          semantically rich content (structure, styled text, hyperlinks, etc). Reconciliation services SHOULD ensure [[accessibility]] of this HTML content (avoid fixed font sizes, provide alternative text for images etc).
-          The service's preview metadata contains the suggested width and height to display the preview content. Reconciliation clients SHOULD consider adjusting these values as required for supporting accessibility features like UI scaling.
-        

-        

-          Except for the preview content and size, all data involved in the reconciliation and data extension process is text-based and contains no specifics about visual rendering. Reconciliation clients SHOULD ensure [[accessibility]] for this text content
-          (font resizing, screen reader support etc.) based on the technology of the underlying platform, which will typically implement the details of visual text rendering and user interface customization.
-        

-      

-      

-        
Content semantics

-        

-          The main content presented to users is provided in reconciliation results and data extension responses. Both support name fields for all identifiable objects, in particular
-          entities, types, properties, and matching features. These SHOULD be used by reconciliation clients to provide useful labels for displaying and linking identifiable entities. 
-          The structural semantics of the content provided by reconciliation services allows different presentations (as pages, tables, etc.) in reconciliation clients. Being fully text- and JSON-based, content can 
-          be modified by third-party tools to enhance accessibility.
-        

-      

-    

-    

-      
Security Considerations

-
-      

-        
Preventing Abuse

-        
    
-          
  • Reconciliation services SHOULD guard against too frequent requests to prevent [[DoS]] attacks (see Error Handling and Rate-limiting).
    • 
-          
  • Reconciliation services SHOULD guard against malicious code when querying their underlying data store with data from reconciliation queries to avoid code [[injection]].
    • 
-          
  • Reconciliation services SHOULD NOT parse the JSON requests sent by clients using a code execution mechanism like JavaScript's eval(), since requests could contain malicious code.
    • 
-          
  • Reconciliation clients that display data from preview services SHOULD ensure that the data is encoded, sanitized, or isolated to prevent [[XSS]] and [[CSRF]] attacks.
    • 
-        

-      

-
-      

-        
Other considerations

-        
    
-          
  • Reconciliation services and clients MAY support user authentication (see authentication).
    • 
-          
  • Reconciliation features don't expose information about the underlying platform to clients or services, they don't allow clients or services to send data to the underlying platform, access other devices, device sensors, 
-            a user agent's native UI, or enable clients or services to downgrade default security protections.
-          
    • 
-        

-      

-
-    

-
-    

-      
Privacy Considerations

-
-      

-        
Network data

-        
    
-          
  • All data in reconciliation queries is visible to the reconciliation service, to be processed for returning reconciliation results to the client.
-            To prevent malicious actors from intercepting the data that is sent and received, services SHOULD provide secure HTTPS endpoints for reconciliation.
-          
    • 
-          
  • User selections of matching reconciliation candidates provide user-verified statements about the data. These selections are currently not sent back to the reconciliation service
-            (but that may change with #30).
-          
    • 
-        

-      

-
-      

-        
Persistent data

-        
    
-          
  • Reconciliation clients MAY introduce new state that persists across browsing sessions for persisting reconciliation queries,
-            the service's reconciliation results, and/or the user's selection of matches.
    • 
-          
  • Reconciliation clients implemented as browser extensions running in Private Browsing or Incognito mode SHOULD NOT store reconciliation queries,
-            the service's reconciliation results, or the user's selection of matches.
    • 
-          
  • Reconciliation services currently don't introduce new state that persists across browsing sessions (but that may change with #30).
    • 
-          
-        

-      

-
-    

-
-    

-      
JSON Schemas

-        

-          This appendix provides JSON schemas [[json-schema]] which can be used to validate the JSON serialization
-          of various elements as specified by these specifications.
-        

-      

-        
Manifest Schema

-        

-          The manifest schema can be used to validate a service manifest.
-        

-        
-      

-      

-        
Reconciliation Query Batch Schema

-	    

-	      The reconciliation query batch schema can be used to validate
-	      the JSON serialization of any reconciliation query batch, i.e. the payload of a GET/POST to the reconciliation endpoint.
-	   

-	   
-      

-      

-        
Reconciliation Result Batch Schema

-	    

-          The reconciliation result batch schema can be used to validate the JSON serialization of any reconciliation result batch.
-        

-        
-      

-      

-        
Suggest Entities Response Schema

-	

-          The suggest entities response schema can be used to validate the JSON serialization of any suggest response for entities.
-        

-        
-      

-      

-        
Suggest Properties Response Schema

-	

-          The suggest properties response schema can be used to validate the JSON serialization of any suggest response for properties.
-        

-        
-      

-      

-        
Suggest Types Response Schema

-	

-          The suggest types response schema can be used to validate the JSON serialization of any suggest response for types.
-        

-        
-      

-      

-        
Data Extension Property Proposal Schema

-        

-          The data extension query schema validates data extension property proposal responses.
-        

-        
-      

-      

-        
Data Extension Query Schema

-        

-          The data extension query schema validates data extension queries.
-        

-        
-      

-      

-        
Data Extension Response Schema

-        

-          The data extension response schema validates data extension responses.
-        

-        
-      

-    

-  
+	
+		
+		
+		Reconciliation Service API Specifications
+	
+	
+	
+		
+	
 
diff --git a/test.sh b/test.sh
index 100dbdb..b0ad27b 100755
--- a/test.sh
+++ b/test.sh
@@ -3,7 +3,7 @@
 set -e
 
 # Test JSON examples against schemas
-for version in "0.1" "0.2" "draft"; do
+for version in "0.1" "0.2" "1.0-draft"; do
 	echo "Testing version: $version"
 
 	for schema_file in `ls $version/schemas`; do

From 2ab0901bc63cca8e6b9ab4d6d248b7a4df6e33d4 Mon Sep 17 00:00:00 2001
From: Antonin Delpeuch 
Date: Thu, 12 Sep 2024 17:08:51 +0200
Subject: [PATCH 3/6] Update schema and examplees for 1.0-draft

---
 1.0-draft/examples/manifest/invalid/bad-authentication.json    | 3 ++-
 1.0-draft/examples/manifest/invalid/feature-view.json          | 3 ++-
 1.0-draft/examples/manifest/invalid/godot-missing-view.json    | 3 ++-
 1.0-draft/examples/manifest/invalid/opencorporates.json        | 3 ++-
 .../examples/manifest/invalid/ror-invalid-view-pattern.json    | 3 ++-
 .../manifest/invalid/slub-invalid-property-setting.json        | 3 ++-
 1.0-draft/examples/manifest/valid/authentication.json          | 2 +-
 1.0-draft/examples/manifest/valid/codefork-viaf.json           | 2 +-
 1.0-draft/examples/manifest/valid/example-min.json             | 2 +-
 1.0-draft/examples/manifest/valid/feature-view.json            | 2 +-
 1.0-draft/examples/manifest/valid/findthatcharity.json         | 2 +-
 1.0-draft/examples/manifest/valid/fundref.json                 | 2 +-
 1.0-draft/examples/manifest/valid/geocollider-sinatra.json     | 2 +-
 1.0-draft/examples/manifest/valid/getty.json                   | 2 +-
 1.0-draft/examples/manifest/valid/kerameikos.json              | 2 +-
 1.0-draft/examples/manifest/valid/kew.json                     | 2 +-
 1.0-draft/examples/manifest/valid/lobid-gnd.json               | 2 +-
 1.0-draft/examples/manifest/valid/nomisma.json                 | 2 +-
 1.0-draft/examples/manifest/valid/occrp.json                   | 2 +-
 1.0-draft/examples/manifest/valid/ordnance-survey.json         | 2 +-
 1.0-draft/examples/manifest/valid/vivo-cornell.json            | 2 +-
 1.0-draft/examples/manifest/valid/wikidata.json                | 2 +-
 1.0-draft/schemas/manifest.json                                | 2 +-
 23 files changed, 29 insertions(+), 23 deletions(-)

diff --git a/1.0-draft/examples/manifest/invalid/bad-authentication.json b/1.0-draft/examples/manifest/invalid/bad-authentication.json
index bc56792..6ed13d7 100644
--- a/1.0-draft/examples/manifest/invalid/bad-authentication.json
+++ b/1.0-draft/examples/manifest/invalid/bad-authentication.json
@@ -5,5 +5,6 @@
   },
   "authentication": {
      "foo": "bar"
-  }
+  },
+  "versions": ["1.0-draft"]
 }
diff --git a/1.0-draft/examples/manifest/invalid/feature-view.json b/1.0-draft/examples/manifest/invalid/feature-view.json
index bab29f7..fcaabfd 100644
--- a/1.0-draft/examples/manifest/invalid/feature-view.json
+++ b/1.0-draft/examples/manifest/invalid/feature-view.json
@@ -5,5 +5,6 @@
     },
     "featureView": {
         "url": "https://vocab.getty.edu/recon/features/"
-    }
+    },
+    "versions": ["1.0-draft"]
 }
diff --git a/1.0-draft/examples/manifest/invalid/godot-missing-view.json b/1.0-draft/examples/manifest/invalid/godot-missing-view.json
index 74b5c7c..e5c0c0c 100644
--- a/1.0-draft/examples/manifest/invalid/godot-missing-view.json
+++ b/1.0-draft/examples/manifest/invalid/godot-missing-view.json
@@ -8,5 +8,6 @@
   "name": "GODOT (Graph of Dated Objects and Texts) Reconciliation Service - Roman Consulates",
   "preview": {
     "url": "https://godot.date/reconcile/preview={id}"
-  }
+  },
+  "versions": ["1.0-draft"]
 }
diff --git a/1.0-draft/examples/manifest/invalid/opencorporates.json b/1.0-draft/examples/manifest/invalid/opencorporates.json
index 8bed8f9..990af5d 100644
--- a/1.0-draft/examples/manifest/invalid/opencorporates.json
+++ b/1.0-draft/examples/manifest/invalid/opencorporates.json
@@ -17,5 +17,6 @@
       "id": "/organization/organization",
       "name": "Organization"
     }
-  ]
+  ],
+  "versions": ["1.0-draft"]
 }
diff --git a/1.0-draft/examples/manifest/invalid/ror-invalid-view-pattern.json b/1.0-draft/examples/manifest/invalid/ror-invalid-view-pattern.json
index 9dbaf66..abc723b 100644
--- a/1.0-draft/examples/manifest/invalid/ror-invalid-view-pattern.json
+++ b/1.0-draft/examples/manifest/invalid/ror-invalid-view-pattern.json
@@ -16,5 +16,6 @@
     "width": 400,
     "height": 100,
     "url": "https://reconcile.ror.org/preview/{id}"
-  }
+  },
+  "versions": ["1.0-draft"]
 }
diff --git a/1.0-draft/examples/manifest/invalid/slub-invalid-property-setting.json b/1.0-draft/examples/manifest/invalid/slub-invalid-property-setting.json
index 323f061..72fd8c5 100644
--- a/1.0-draft/examples/manifest/invalid/slub-invalid-property-setting.json
+++ b/1.0-draft/examples/manifest/invalid/slub-invalid-property-setting.json
@@ -64,5 +64,6 @@
   },
   "view": {
     "url": "http://data.slub-dresden.de/{id}"
-  }
+  },
+  "versions": ["1.0-draft"]
 }
diff --git a/1.0-draft/examples/manifest/valid/authentication.json b/1.0-draft/examples/manifest/valid/authentication.json
index a7c7f4d..b1c5814 100644
--- a/1.0-draft/examples/manifest/valid/authentication.json
+++ b/1.0-draft/examples/manifest/valid/authentication.json
@@ -1,5 +1,5 @@
 {
-  "versions": [ "0.2" ],
+  "versions": [ "1.0-draft" ],
   "view": {
     "url": "http://vivo.med.cornell.edu/individual?uri={id}"
   },
diff --git a/1.0-draft/examples/manifest/valid/codefork-viaf.json b/1.0-draft/examples/manifest/valid/codefork-viaf.json
index 60cc6d8..0f47436 100644
--- a/1.0-draft/examples/manifest/valid/codefork-viaf.json
+++ b/1.0-draft/examples/manifest/valid/codefork-viaf.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "VIAF",
   "view": {
     "url": "http://viaf.org/viaf/{id}"
diff --git a/1.0-draft/examples/manifest/valid/example-min.json b/1.0-draft/examples/manifest/valid/example-min.json
index 0c123c1..c86e2a6 100644
--- a/1.0-draft/examples/manifest/valid/example-min.json
+++ b/1.0-draft/examples/manifest/valid/example-min.json
@@ -1,5 +1,5 @@
 {
-    "versions": ["0.2"],
+    "versions": ["1.0-draft"],
     "name": "VIAF",
     "view": {
         "url": "https://viaf.org/viaf/{id}"
diff --git a/1.0-draft/examples/manifest/valid/feature-view.json b/1.0-draft/examples/manifest/valid/feature-view.json
index 9c8309b..b11a664 100644
--- a/1.0-draft/examples/manifest/valid/feature-view.json
+++ b/1.0-draft/examples/manifest/valid/feature-view.json
@@ -1,5 +1,5 @@
 {
-    "versions": ["0.2"],
+    "versions": ["1.0-draft"],
     "name": "VIAF",
     "view": {
         "url": "https://viaf.org/viaf/{id}"
diff --git a/1.0-draft/examples/manifest/valid/findthatcharity.json b/1.0-draft/examples/manifest/valid/findthatcharity.json
index cdfdaaa..cb617e7 100644
--- a/1.0-draft/examples/manifest/valid/findthatcharity.json
+++ b/1.0-draft/examples/manifest/valid/findthatcharity.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "findthatcharity",
   "view": {
     "url": "https://findthatcharity.uk/charity/{id}"
diff --git a/1.0-draft/examples/manifest/valid/fundref.json b/1.0-draft/examples/manifest/valid/fundref.json
index b301d38..3975218 100644
--- a/1.0-draft/examples/manifest/valid/fundref.json
+++ b/1.0-draft/examples/manifest/valid/fundref.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "Open Funder Registry Reconciliation Service",
   "view": {
     "url": "{+id}"
diff --git a/1.0-draft/examples/manifest/valid/geocollider-sinatra.json b/1.0-draft/examples/manifest/valid/geocollider-sinatra.json
index 67ba9ca..883a6bf 100644
--- a/1.0-draft/examples/manifest/valid/geocollider-sinatra.json
+++ b/1.0-draft/examples/manifest/valid/geocollider-sinatra.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "Pleiades Reconciliation for OpenRefine",
   "view": {
     "url": "{+id}"
diff --git a/1.0-draft/examples/manifest/valid/getty.json b/1.0-draft/examples/manifest/valid/getty.json
index ad33716..6f4b553 100644
--- a/1.0-draft/examples/manifest/valid/getty.json
+++ b/1.0-draft/examples/manifest/valid/getty.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "defaultTypes": [
     {
       "id": "/ulan",
diff --git a/1.0-draft/examples/manifest/valid/kerameikos.json b/1.0-draft/examples/manifest/valid/kerameikos.json
index 70dfcb7..d5a2b58 100644
--- a/1.0-draft/examples/manifest/valid/kerameikos.json
+++ b/1.0-draft/examples/manifest/valid/kerameikos.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "Kerameikos.org",
   "view": {
     "url": "http://kerameikos.org/id/{id}"
diff --git a/1.0-draft/examples/manifest/valid/kew.json b/1.0-draft/examples/manifest/valid/kew.json
index 2f964ad..d78304b 100644
--- a/1.0-draft/examples/manifest/valid/kew.json
+++ b/1.0-draft/examples/manifest/valid/kew.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "IPNI Name Reconciliation Service",
   "view": {
     "url": "http://ipni.org/urn:lsid:ipni.org:names:{id}"
diff --git a/1.0-draft/examples/manifest/valid/lobid-gnd.json b/1.0-draft/examples/manifest/valid/lobid-gnd.json
index 9933596..d463d49 100644
--- a/1.0-draft/examples/manifest/valid/lobid-gnd.json
+++ b/1.0-draft/examples/manifest/valid/lobid-gnd.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "GND reconciliation for OpenRefine",
   "defaultTypes": [
     {
diff --git a/1.0-draft/examples/manifest/valid/nomisma.json b/1.0-draft/examples/manifest/valid/nomisma.json
index 2b76eda..e2cf9a1 100644
--- a/1.0-draft/examples/manifest/valid/nomisma.json
+++ b/1.0-draft/examples/manifest/valid/nomisma.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "Nomisma.org",
   "view": {
     "url": "http://nomisma.org/id/{id}"
diff --git a/1.0-draft/examples/manifest/valid/occrp.json b/1.0-draft/examples/manifest/valid/occrp.json
index 23f02e8..9287715 100644
--- a/1.0-draft/examples/manifest/valid/occrp.json
+++ b/1.0-draft/examples/manifest/valid/occrp.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "OCCRP Aleph",
   "view": {
     "url": "https://aleph.occrp.org/entities/{id}"
diff --git a/1.0-draft/examples/manifest/valid/ordnance-survey.json b/1.0-draft/examples/manifest/valid/ordnance-survey.json
index 948d7ad..04a9218 100644
--- a/1.0-draft/examples/manifest/valid/ordnance-survey.json
+++ b/1.0-draft/examples/manifest/valid/ordnance-survey.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "name": "Code-Point Open Reconciliation API",
   "view": {
     "url": "{+id}"
diff --git a/1.0-draft/examples/manifest/valid/vivo-cornell.json b/1.0-draft/examples/manifest/valid/vivo-cornell.json
index 913354e..230b0ff 100644
--- a/1.0-draft/examples/manifest/valid/vivo-cornell.json
+++ b/1.0-draft/examples/manifest/valid/vivo-cornell.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.2"],
+  "versions": ["1.0-draft"],
   "view": {
     "url": "http://vivo.med.cornell.edu/individual?uri={id}"
   },
diff --git a/1.0-draft/examples/manifest/valid/wikidata.json b/1.0-draft/examples/manifest/valid/wikidata.json
index 72470e9..66bf773 100644
--- a/1.0-draft/examples/manifest/valid/wikidata.json
+++ b/1.0-draft/examples/manifest/valid/wikidata.json
@@ -1,5 +1,5 @@
 {
-  "versions": ["0.1", "0.2"],
+  "versions": ["0.1", "0.2", "1.0-draft"],
   "name": "Wikidata (en)",
   "preview": {
     "width": 400,
diff --git a/1.0-draft/schemas/manifest.json b/1.0-draft/schemas/manifest.json
index ed34982..b63036a 100644
--- a/1.0-draft/schemas/manifest.json
+++ b/1.0-draft/schemas/manifest.json
@@ -11,7 +11,7 @@
         "type": "string"
       },
       "contains": {
-        "enum": ["0.2"]
+        "enum": ["1.0-draft"]
       }
     },
     "name": {

From 03f1f07b58e99823977ba9e9e37bc4a7132c65c6 Mon Sep 17 00:00:00 2001
From: Antonin Delpeuch 
Date: Fri, 13 Sep 2024 00:47:49 +0200
Subject: [PATCH 4/6] Update canonical URIs to point to /1.0-beta/

---
 1.0-draft/index.html | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/1.0-draft/index.html b/1.0-draft/index.html
index aae013a..8679ce6 100644
--- a/1.0-draft/index.html
+++ b/1.0-draft/index.html
@@ -13,8 +13,8 @@
         wg: "Entity Reconciliation Community Group",
         wgPublicList: "public-reconciliation",
         wgURI: "https://www.w3.org/community/reconciliation/",
-	canonicalURI: "https://reconciliation-api.github.io/specs/draft/",
-	edDraftURI: "https://reconciliation-api.github.io/specs/draft/",
+	canonicalURI: "https://reconciliation-api.github.io/specs/1.0-draft/",
+	edDraftURI: "https://reconciliation-api.github.io/specs/1.0-draft/",
         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",

From d4eaa9e1391e25654046c4cca510ef6821edaa3f Mon Sep 17 00:00:00 2001
From: Antonin Delpeuch 
Date: Fri, 13 Sep 2024 00:48:54 +0200
Subject: [PATCH 5/6] Update 1.0-draft/index.html

Co-authored-by: Thad Guidry 
---
 1.0-draft/index.html | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/1.0-draft/index.html b/1.0-draft/index.html
index 8679ce6..5ef775e 100644
--- a/1.0-draft/index.html
+++ b/1.0-draft/index.html
@@ -354,7 +354,7 @@ 
Service Manifest

         A service manifest consists of the following fields:
         

           
versions

-          
The array of API versions supported by the endpoint, such as ["0.1", "0.2"]. Since this field did not exist in version 0.1, services which do not declare a versions field are expected to only support version 0.1. A service implementing the current draft should include 1.0-draft in the array.

+          
The array of API versions supported by the endpoint, such as ["0.1", "0.2", "1.0-draft"]. Since this field did not exist in version 0.1, services which do not declare a versions field are expected to only support version 0.1. A service implementing the current draft should include 1.0-draft in the array.

           
name

           
A human-readable name for the service, generally the name of the database it exposes. In the case where multiple reconciliation services exist for the same database, it is in the interest of a service to bear a meaningful name which
 will help disambiguating it from others;


From c6bfcdf4927ea954df1099a1569310146f9ada40 Mon Sep 17 00:00:00 2001
From: Antonin Delpeuch 
Date: Mon, 16 Sep 2024 19:15:13 +0200
Subject: [PATCH 6/6] 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 43d4ba7..744fb17 100644
--- a/draft/index.html
+++ b/draft/index.html
@@ -2,7 +2,7 @@
 
 	
 		
-		
+		
 		Reconciliation Service API Specifications