Issue |
---|
What is the schema.org model for offering Data Services and Continuous Feeds? |
Can we use Wikidata for canonical data service types? |
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.
{ "@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." } }
{ "@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.
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.
Is an API type missing from this list?
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.