Merge pull request #156 from reconciliation-api/147-standardizedScore

Add optional `standardizedScore` field in service manifest (#147)

draft/examples/manifest/valid/wikidata.json

@@ -82,5 +82,6 @@
     "type": true,
     "entity": true,
     "property": true
-  }
+  },
+  "standardizedScore": true
 }

draft/index.html

@@ -240,7 +240,7 @@ <h4>This Draft</h4>
             <li><a href="https://github.com/reconciliation-api/specs/pull/140">Remove <code>identifierSpace</code> and <code>schemaSpace</code> and make view templates mandatory</a></li>
             <li><a href="https://github.com/reconciliation-api/specs/pull/142">Remove support for JSONP</a></li>
             <li><a href="https://github.com/reconciliation-api/specs/pull/149">Move the <code>query</code> field of reconciliation queries inside <code>properties</code> to allow for queries which do not provide entity names</a></li>
-            <li><a href="https://github.com/reconciliation-api/specs/pull/166">Unify naming to camelCase convention</a></li>
+            <li><a href="https://github.com/reconciliation-api/specs/pull/156">Add optional <code>standardizedScore</code> field to the manifest</a></li>
           </ul>
         </section>
       </section>
@@ -393,6 +393,8 @@ <h3>Service Manifest</h3>
           <dd>An optional value for the default <a href="#text-processing-language">text-processing language</a> used by this service.</dd>
           <dt><code>dir</code></dt>
           <dd>An optional value for the default <a href="#text-direction">text direction</a> used by this service.</dd>
+          <dt><code>standardizedScore</code></dt>
+          <dd>An optional boolean indicating if the service returns values between 0 and 100 (inclusive) in the <code>score</code> field of <a>reconciliation candidates</a>. This enables clients to process and display candidates accordingly, e.g. with score percentages or visualizations.</dd>
         </dl>
       </p>
       <p>For instance, a service could expose the following minimal service manifest:
@@ -569,7 +571,7 @@ <h3>Reconciliation Query Responses</h3>
 	    <dt><code>type</code></dt>
 	    <dd>The types of the candidate entity;</dd>
 	    <dt><code>score</code></dt>
-	    <dd>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;</dt>
+	    <dd>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 <code>standardizedScore</code> is set to <code>true</code> in the <a>service manifest</a>, this value MUST be between 0 and 100 (inclusive);</dt>
             <dt><code>features</code></dt>
             <dd>An optional array of <a>matching features</a>;</dd>
 	    <dt><code>match</code></dt>

draft/schemas/manifest.json

@@ -254,6 +254,10 @@
           }
         }
       }
+    },
+    "standardizedScore": {
+      "type": "boolean",
+      "description": "Whether the service returns values between 0 and 100 (inclusive) in the score field of reconciliation candidates"
     }
   },
   "required": [