p419dcatservices

Axioms

1. primary audience for schema.org markup is harvesters
2. the common denominator across search interfaces of most harvesters is a single text box (for harvester-specific DSL queries)
3. a typical schema.org harvester should not be expected to understand other vocabularies outside of schema.org

Analysis of Axioms

1. schema.org for Data Services should help harvesters find and understand how to present these services as a search result
2. for smart-handoffs from harvesters, schema.org for Data Services should help harvesters pass along single text box query to the service
3. to support pass thru service calls for [schema.org] class-specific searches (such as the Dataset class), the schema.org markup describing services must express:
   1. the result set is specific to the schema.org class being searched (i.e. Dataset objects are being returned as search results from executing a service call)
   2. the response is formatted as parseable schema.org (JSON-LD or HTML response, to support RDFa, microformats, etc.)

Issues

Issue
What is the schema.org model for offering Data Services and Continuous Feeds?
Can we use Wikidata for canonical data service types?

References

• DCAT Version 2 (https://w3c.github.io/dxwg/dcat/)
• Machine Readable Web APIs with Schema.org Action Annotations (https://doi.org/10.1016/j.procs.2018.09.025)

Guidance

Describing APIs

schema:WebAPI extends the generic schema:Service by adding a single field schema:documentation which links the 'Service' of the API to its documentation - either a schema:CreativeWork or a simple URL.

WebAPI documentation as a URL:

{
  "@context": "http://schema.org/",
  "@type": "WebAPI",
  "name": "Google Knowledge Graph Search API",
  "description": "The Knowledge Graph Search API lets you find entities in the Google Knowledge Graph. The API uses standard schema.org types and is compliant with the JSON-LD specification.",
  "documentation": "https://developers.google.com/knowledge-graph/",
  "termsOfService": "https://developers.google.com/knowledge-graph/terms",
  "provider": {
    "@type": "Organization",
    "name": "Google Inc."
  }
}

WebAPI documentation as a CreativeWork (example: WMS 1.3 service):

{
  "@context": "http://schema.org/",
  "@type": "WebAPI",
  "name": "WMS 1.3 for Sample Data Repository",
  "description": "The WMS 1.3 lets you find datasets in the Sample Data Repository.",
  "documentation": {
    "@type": "HowTo",
    "name": "WMS 1.3 for Example Repository Data Catalog",
    "additionalType": "http://www.wikidata.org/entity/Q974922",
    "schemaVersion": "1.3"
  },
  "provider": {
    "@id": "https://www.sample-repository.org",
    "@type": "Organization",
    "name": "Sample Data Repository"
  }
}

For being more explicit about the type of schema:documentation, see the sub types of a schema:CreativeWork. Notable types, each may lend itself as a better fit depending on the type of API documentation: Article, DigitalDocument, HowTo, WebPage.

Wikidata API types

In the above CreativeWork example, we specify the type of WebAPI by using the schema:additionalType field. One consideration for the types of WebAPIs is the version of the API that is being described.

• CSW - http://www.wikidata.org/entity/Q661823
• OAI-PMH - http://www.wikidata.org/entity/Q2430433
• JSON API - http://www.wikidata.org/entity/Q28758133
• OpenSearch - http://www.wikidata.org/entity/Q1294021
• OPeNDAP - http://www.wikidata.org/entity/Q7072878
• WMS - http://www.wikidata.org/entity/Q974922
• WFS - http://www.wikidata.org/entity/Q2296308
• SPARQL endpoint - http://www.wikidata.org/entity/Q26261192
• GeoNetwork - http://www.wikidata.org/entity/Q477787
• GeoServer - http://www.wikidata.org/entity/Q1502779
• Apache SOLR - http://www.wikidata.org/entity/Q2858103

Is an API type missing from this list?

1. Search Wikidata.
2. If no type at Wikidata, create it.

API Type Versions

In the example above, we are able to use the schemaVersion field of a CreativeWork to specify the exact version of the WebAPI type. NOTE: the version field would let you specify the version of the documentation, where this schemaVersion field specifcally references the version of the schema behind the documentation.

Describing actionable API endpoints

See https://github.com/ESIPFed/science-on-schema.org/blob/master/guides/Dataset.md#accessing-data-through-a-service-endpoint