Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Remove identifierSpace and schemaSpace; make view templates mandatory #140

Merged
merged 1 commit into from
Nov 9, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions draft/examples/manifest/invalid/bad-authentication.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
{
"name": "OpenCorporates Reconciliation Service",
"identifierSpace": "http://rdf.freebase.com/ns/type.object.id",
"schemaSpace": "http://rdf.freebase.com/ns/type.object.id",
"view": {
"url": "{+id}"
},
"authentication": {
"foo": "bar"
}
Expand Down
5 changes: 3 additions & 2 deletions draft/examples/manifest/invalid/feature-view.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,8 @@
{
"name": "VIAF",
"identifierSpace": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes",
"schemaSpace": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD",
"view": {
"url": "https://viaf.org/viaf/{id}"
},
"feature_view": {
"url": "https://vocab.getty.edu/recon/features/"
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,5 @@
"name": "GODOT (Graph of Dated Objects and Texts) Reconciliation Service - Roman Consulates",
"preview": {
"url": "https://godot.date/reconcile/preview={id}"
},
"view": {
"url": "https://godot.date/id/{id}"
}
}
5 changes: 3 additions & 2 deletions draft/examples/manifest/invalid/missing-version.json
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
{
"name": "VIAF",
"identifierSpace": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes",
"schemaSpace": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD"
"view": {
"url": "https://viaf.org/viaf/{id}"
}
}
5 changes: 3 additions & 2 deletions draft/examples/manifest/invalid/old-version.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"versions": ["0.1"],
"name": "VIAF",
"identifierSpace": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes",
"schemaSpace": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD"
"view": {
"url": "https://viaf.org/viaf/{id}"
}
}
2 changes: 0 additions & 2 deletions draft/examples/manifest/invalid/opencorporates.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
{
"name": "OpenCorporates Reconciliation Service",
"identifierSpace": "http://rdf.freebase.com/ns/type.object.id",
"schemaSpace": "http://rdf.freebase.com/ns/type.object.id",
"view": {
"url": "https://opencorporates.com{id}"
},
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/invalid/ror-invalid-view-pattern.json
Original file line number Diff line number Diff line change
@@ -1,7 +1,5 @@
{
"name": "ROR Reconciliation Service",
"identifierSpace": "http://ror.org/organization",
"schemaSpace": "http://ror.org/ns/type.object.id",
"defaultTypes": [
{
"id": "/ror/organization",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -59,14 +59,12 @@
"service_url": "http://data.slub-dresden.de"
}
},
"identifierSpace": "http://data.slub-dresden.de",
"name": "SLUB LOD reconciliation for OpenRefine",
"preview": {
"height": 100,
"url": "http://data.slub-dresden.de/{id}.preview",
"width": 320
},
"schemaSpace": "http://schema.org",
"view": {
"url": "http://data.slub-dresden.de/{id}"
}
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/authentication.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,7 @@
"view": {
"url": "http://vivo.med.cornell.edu/individual?uri={id}"
},
"identifierSpace": "http://vivo.med.cornell.edu/individual/",
"name": "VIVO Reconciliation Service",
"schemaSpace": "http://vivo.med.cornell.edu/individual/",
"authentication": {
"type": "apiKey",
"description": "Vivo API key",
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/codefork-viaf.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
{
"versions": ["0.2"],
"name": "VIAF",
"identifierSpace": "http://rdf.freebase.com/ns/user/hangy/viaf",
"schemaSpace": "http://rdf.freebase.com/ns/type.object.id",
"view": {
"url": "http://viaf.org/viaf/{id}"
},
Expand Down
5 changes: 3 additions & 2 deletions draft/examples/manifest/valid/example-min.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
{
"versions": ["0.2"],
"name": "VIAF",
"identifierSpace": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes",
"schemaSpace": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD"
"view": {
"url": "https://viaf.org/viaf/{id}"
}
}
5 changes: 3 additions & 2 deletions draft/examples/manifest/valid/feature-view.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
{
"versions": ["0.2"],
"name": "VIAF",
"identifierSpace": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes",
"schemaSpace": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD",
"view": {
"url": "https://viaf.org/viaf/{id}"
},
"feature_view": {
"url": "https://vocab.getty.edu/recon/features/{id}"
}
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/findthatcharity.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
{
"versions": ["0.2"],
"name": "findthatcharity",
"identifierSpace": "http://rdf.freebase.com/ns/type.object.id",
"schemaSpace": "http://rdf.freebase.com/ns/type.object.id",
"view": {
"url": "https://findthatcharity.uk/charity/{id}"
},
Expand Down
5 changes: 3 additions & 2 deletions draft/examples/manifest/valid/fundref.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
{
"versions": ["0.2"],
"name": "Open Funder Registry Reconciliation Service",
"identifierSpace": "http://openfunder.crossref.org/openfunder",
"schemaSpace": "http://openfunder.crossref.org/ns/type.object.id",
"view": {
"url": "{+id}"
},
"defaultTypes": [
{
"id": "/fundref/funder_name",
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/geocollider-sinatra.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
{
"versions": ["0.2"],
"name": "Pleiades Reconciliation for OpenRefine",
"schemaSpace": "https://pleiades.stoa.org/places/",
"identifierSpace": "https://pleiades.stoa.org/places/vocab#",
"view": {
"url": "{+id}"
},
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/getty.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,12 @@
"name": "Search all Vocabs"
}
],
"identifierSpace": "http://vocab.getty.edu/doc/#GVP_URLs_and_Prefixes",
"name": "Getty Vocabularies Reconciliation Service",
"batchSize": 50,
"preview": {
"height": 200,
"width": 350
},
"schemaSpace": "http://vocab.getty.edu/doc/#The_Getty_Vocabularies_and_LOD",
"suggest": {
"entity": false,
"property": true,
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/kerameikos.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
"view": {
"url": "http://kerameikos.org/id/{id}"
},
"identifierSpace": "http://kerameikos.org/id/",
"schemaSpace": "http://kerameikos.org/ontology",
"defaultTypes": [
{
"id": "skos:Concept",
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/kew.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
{
"versions": ["0.2"],
"name": "IPNI Name Reconciliation Service",
"identifierSpace": "http://ipni.org/urn:lsid:ipni.org:names:",
"schemaSpace": "http://rdf.freebase.com/ns/type.object.id",
"view": {
"url": "http://ipni.org/urn:lsid:ipni.org:names:{id}"
},
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/lobid-gnd.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
{
"versions": ["0.2"],
"name": "GND reconciliation for OpenRefine",
"identifierSpace": "https://lobid.org/gnd/",
"schemaSpace": "https://d-nb.info/standards/elementset/gnd#AuthorityResource",
"defaultTypes": [
{
"id": "AuthorityResource",
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/nomisma.json
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,6 @@
"view": {
"url": "http://nomisma.org/id/{id}"
},
"identifierSpace": "http://nomisma.org/id/",
"schemaSpace": "http://nomisma.org/ontology",
"defaultTypes": [
{
"id": "nmo:CoinWear",
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/occrp.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
{
"versions": ["0.2"],
"name": "OCCRP Aleph",
"identifierSpace": "http://rdf.freebase.com/ns/type.object.id",
"schemaSpace": "http://rdf.freebase.com/ns/type.object.id",
"view": {
"url": "https://aleph.occrp.org/entities/{id}"
},
Expand Down
2 changes: 0 additions & 2 deletions draft/examples/manifest/valid/ordnance-survey.json
Original file line number Diff line number Diff line change
@@ -1,8 +1,6 @@
{
"versions": ["0.2"],
"name": "Code-Point Open Reconciliation API",
"identifierSpace": "http://data.ordnancesurvey.co.uk/id/data/code-point-open",
"schemaSpace": "http://data.ordnancesurvey.co.uk/id/data/code-point-open",
"view": {
"url": "{+id}"
}
Expand Down
4 changes: 1 addition & 3 deletions draft/examples/manifest/valid/vivo-cornell.json
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
"view": {
"url": "http://vivo.med.cornell.edu/individual?uri={id}"
},
"identifierSpace": "http://vivo.med.cornell.edu/individual/",
"name": "VIVO Reconciliation Service",
"defaultTypes": [
{
Expand Down Expand Up @@ -34,6 +33,5 @@
"name": "obo:IAO_0000030",
"id": "http://purl.obolibrary.org/obo/IAO_0000030"
}
],
"schemaSpace": "http://vivo.med.cornell.edu/individual/"
]
}
4 changes: 1 addition & 3 deletions draft/examples/manifest/valid/wikidata.json
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,6 @@
"width": 400,
"height": 100
},
"schemaSpace": "http://www.wikidata.org/prop/direct/",
"documentation": "https://tools.wmflabs.org/openrefine-wikidata/",
"logo": "https://tools.wmflabs.org/openrefine-wikidata/logo.png",
"serviceVersion": "1.2.3",
Expand Down Expand Up @@ -83,6 +82,5 @@
"type": true,
"entity": true,
"property": true
},
"identifierSpace": "http://www.wikidata.org/entity/"
}
}
40 changes: 7 additions & 33 deletions draft/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -222,7 +222,8 @@ <h4>This Draft</h4>
<ul>
<li>Remove support for flyouts;</li>
<li>The endpoints of various sub-services are no longer configurable, but determined by the root reconciliation endpoint;</li>
<li>The reconciliation queries only support passing a single <code>type</code> and the <code>type_strict</code> parameter was removed.</li>
<li>The reconciliation queries only support passing a single <code>type</code> and the <code>type_strict</code> parameter was removed;</li>
<li>Remove the notion of identifierSpace and schemaSpace and make view templates mandatory.
</ul>
</section>
</section>
Expand Down Expand Up @@ -255,7 +256,7 @@ <h3 data-link-for="entities">Entities</h3>
Moreover, for each <a>property</a> it contains a set of associated <a>property values</a>, possibly empty.
</p>
<p>
Reconciliation services can define in their <a>service manifest</a> a <dfn>URI template</dfn> for entities,
Reconciliation services MUST define in their <a>service manifest</a> a <dfn>URI template</dfn> for entities,
as defined by [[RFC6570]]. This URI template builds a view URI for each entity, and has <code>id</code> as only variable.
For each entity, expanding the template with <code>id</code> being set to the entity's identifier
MUST result in a valid URI.
Expand Down Expand Up @@ -314,29 +315,6 @@ <h3 data-link-for="property values">Property Values</h3>
</ul>
</p>
</section>
<section>
<h3 data-link-for="spaces">Identifier and Schema Spaces</h3>
<p>
A reconciliation service MUST define two URIs, exposed in its <a>service manifest</a>:
<dl>
<dt><dfn>identifier space</dfn></dt>
<dd>The URI namespace (i.e. prefix) for the identifiers of an <a>entity</a> returned by the reconciliation service, for example <code>http://www.wikidata.org/entity/</code> or <code>https://d-nb.info/gnd/</code>. This URI MAY resolve to a page describing these entities and their identifiers;</dd>
<dt><dfn>schema space</dfn></dt>
<dd>A URI which identifies the type of an <a>entity</a> returned by the reconciliation service, for example <code>http://www.w3.org/2004/02/skos/core#Concept</code> or <code>https://schema.org/Thing</code>. This URI MAY resolve to a page describing this type.</dd>
</dl>
</p>
<p>
If two different reconciliation services expose the same entities and properties, then
they SHOULD use the same identifier and schema space URIs, signalling that
(for instance) the Data Extension service of the first one can be used on reconciliation candidates by the second one.
</p>
<p class="note">
The notions of identifier and schema space
have been inherited from the API's original purpose, when it was specific
to Freebase. Their original meaning was to be understood within Freebase's
own data model.
</p>
</section>
</section>
<section>
<h2>Service Definition</h2>
Expand All @@ -362,10 +340,6 @@ <h3>Service Manifest</h3>
<dt><code>name</code></dt>
<dd>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;</dd>
<dt><code>identifierSpace</code></dt>
<dd>The <a>identifier space</a> used by the service, as a URI;</dd>
<dt><code>schemaSpace</code></dt>
<dd>The <a>schema space</a> used by the service, as a URI;</dd>
<dt><code>defaultTypes</code></dt>
<dd>An array of <a>types</a> 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.<dd>
Expand All @@ -376,7 +350,7 @@ <h3>Service Manifest</h3>
<dt><code>serviceVersion</code></dt>
<dd>An optional string which describes the version of the software exposing this service. This is not to be confused with <code>versions</code> which is about the versions of the reconciliation API supported by the service;</dd>
<dt><code>view</code></dt>
<dd>An optional object which contains a single field <code>url</code>. Its value is a <a>URI template</a> for <a>entities</a>;</dd>
<dd>An object which contains a single field <code>url</code>. Its value is a <a>URI template</a> for <a>entities</a>;</dd>
<dt><code>feature_view</code></dt>
<dd>An optional object which contains a single field <code>url</code>. Its value is a <a>URI template</a> for <a>matching features</a>;</dd>
<dt><code>preview</code></dt>
Expand Down Expand Up @@ -906,9 +880,9 @@ <h3>Data Extension Responses</h3>
The <dfn id="data+extension+response+rows">rows</dfn> object contains, for each <a>entity</a> identifier in the
<a>data extension query</a>, for each <a>property</a> identifier in the
<a href="#data+extension+response+metadata">metadata</a>, the <a>property values</a> of that property in that entity.
If the property values are <a>entities</a>, their identifiers are expected to be in the service's <a>identifier space</a>.
If that is not the case, the service MUST specify in the <code>meta</code> section the endpoint of another reconciliation service whose <a>identifier space</a>
contains the returned entities. This endpoint is specified on a column-per-column basis.
If the property values are <a>entities</a>, 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 <code>meta</code> 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.
</p>
<p>
Response example for the <a>data extension query</a> from the previous example:
Expand Down
11 changes: 1 addition & 10 deletions draft/schemas/manifest.json
Original file line number Diff line number Diff line change
Expand Up @@ -18,14 +18,6 @@
"type": "string",
"description": "A human-readable name for the service or data source"
},
"identifierSpace": {
"type": "string",
"description": "A URI describing the entity identifiers used in this service"
},
"schemaSpace": {
"type": "string",
"description": "A URI describing the schema used in this service"
},
"documentation": {
"type": "string",
"description": "A URI which hosts documentation about this service"
Expand Down Expand Up @@ -267,7 +259,6 @@
"required": [
"versions",
"name",
"identifierSpace",
"schemaSpace"
"view"
]
}
Loading