WADG0001 WebAPI type extension

Copyright © 2017,2019,2020 the Contributors to the WADG0001/Jul2020 report, published by the W3 WebAPI Discovery Community Group under the W3C Community Contributor License Agreement (CLA). A human-readable summary is available.

To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 8 July 2020, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

This draft report is the work of the W3 WebAPI Discovery Community Group

This report was published by the W3 WebAPI Discovery Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This extension has been created based on real-world use of metadata in the [OpenAPI], [RAML], [API-Blueprint], [JSON-home] and [apis.json] specifications.

1. Definitions

Machine-readable API Definition a structured document defining the inputs and outputs of an API in a standardised format, primarily designed for automated processing, not human consumption.

2. Scope

This specification does not attempt to replace existing formats of describing an API, such as [OpenAPI], [RAML], [API-Blueprint], [JSON-home] and [apis.json], but rather seeks to describe metadata about an API that will be useful to those who are discovering it.

3. Proposed extension

Schema.org’s Dataset vocabulary was originally based on DCAT, which in turn used Dublin Core and FOAF terms. DCAT Version 2 is now current, and is therefore used within this draft.

The base schema.org WebAPI type, for example:

{
  "@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."
  }
}

is to be extended by several properties.

These properties are defined within the following list of modular proposals for schema.org. The modularity ensures that adoption can progress pragmatically, and not be blocked by a lack of consensus on all properties.

3.1. New property endpointUrl

3.1.1. Proposal

3.1.2. Examples

Simple usage:

"endpointUrl": "https://kgsearch.googleapis.com/",

Advanced usage:

"endpointUrl": [
  {
    "@type": "EntryPoint",
    "name": "Production server (uses live data)",
    "url": "https://api.example.com/v1",
    "contentType": "application/json"
  },
  {
    "@type": "EntryPoint",
    "name": "Sandbox server (uses test data)",
    "url": "https://sandbox-api.example.com:8443/v1",
    "contentType": "application/json"
  }
],

3.1.3. Notes

This proposal brings the property above directly from DCAT v2. The DCAT v2 to schema.org mapping overloads the schema:url property for both dcat:endpointURL and dcat:landingPage. Given the nature of endpointUrl being the base URL of an API (rather than a web page URL, which is likely the most useful to a web-crawler), a specific property has been defined.

To be consistent with the current inclusion of schema:CreativeWork in the range of schema:documentation, schema:EntryPoint could also be included here for cases where a richer description of the endpoint is required. For example, to differentiate between different environments.

3.2. Update description for documentation property

3.2.1. Proposal

The description of the schema:documentation property is updated to:

Human-readable documentation of the services available via the WebAPI, including their operations, parameters etc.

endpointDescription should be used for machine-readable documentation.

3.2.2. Notes

This proposal makes it clear that the schema:documentation property describes the services available via the WebAPI in a human-readable format, bringing it partly in line with the DCAT v2 to schema.org mapping that recommends the schema:documentation property for both human-readable documentation and machine-readable API definitions. A proposal for a separate endpointDescription property reserved for machine-readable API definitions can be found below.

An alternative that was considered was to use schema:documentation for both human-readable documentation and machine-readable API definitions, bringing it fully in line with DCAT v2, and the DCAT v2 to schema.org mapping. Such an approach was discounted as it would have necessitated the use of "whitelists" of human- and machine-readable encodingFormats by data consumers to distinguish between them, which would have entailed unnecessary complexity and maintenance.

3.3. New property endpointDescription

3.3.1. Proposal

3.3.2. Examples

"endpointDescription": [
  {
    "@type": "CreativeWork",
    "encodingFormat": "application/json",
    "url": "https://kgsearch.googleapis.com/$discovery/rest?version=v1"
  },
  {
    "@type": "CreativeWork",
    "encodingFormat": "application/vnd.oai.openapi+json;version=3.0",
    "url": "https://api.apis.guru/v2/specs/googleapis.com/kgsearch/v1/openapi.json"
  }
],

3.3.3. Notes

This proposal brings the property above directly from DCAT v2, using schema:CreativeWork to be consistent with the range of schema:documentation.

The DCAT v2 to schema.org mapping uses the schema:documentation property for both human- and machine-readable documentation, however in order to create an explicit separation between human-readable documentation and machine-readable endpointDescription, a specific property has been defined.

3.4. New property conformsTo

3.4.1. Proposal

3.4.2. Example

"conformsTo": [
  "https://jsonapi.org/format/1.0/"
],

3.4.3. Notes

This proposal brings the property directly from DCAT v2.

The DCAT v2 to schema.org mapping does not include conformsTo. The mapping gap was recognised in previous mapping attempts and not addressed within DCAT v2 discussions.

3.5. New property accessService

3.5.1. Proposal

3.5.2. Example

{
  "@context": "http://schema.org/",
  "@type": "Dataset",
  ...
  "accessService": {
    "@type": "WebAPI",
    ...
  }
}

3.5.3. Notes

The DCAT v2 to schema.org mapping proposes the use of schema:serviceOutput within schema:WebAPI to reference the schema:Dataset. For the inverse, this proposal uses a term from DCAT v2 to reference schema:WebAPI from schema:Dataset:

The DCAT v2 term dcat:accessService links a dcat:Distribution (akin to schema:DataDownload) to the dcat:DataService, however given that a schema:WebAPI may allow read/write access to a schema:Dataset, it is not necessarily limited to only a single schema:DataDownload, and may in fact cover an entire schema:Dataset.

The DCAT v2 to schema.org mapping does not include accessService.

3.6. Add WebAPI to domain of version

3.6.1. Proposal

Add schema:WebAPI to the domain of schema:version, to describe the version of the API.

3.6.2. Example

"version": "1.0.0",

3.6.3. Notes

This is the version of the API itself, and hence schema:softwareVersion, schema:assemblyVersion, and schemaVersion are not appropriate.

3.7. New property apiTransport

3.7.1. Proposal

3.7.2. Example

"apiTransport": [
  "HTTP",
  "HTTPS"
],

3.7.3. Notes

Given the widely recognised acronyms in use for modes of API transport, there is no need to reference an explicit controlled vocabulary.

3.8. Add WebAPI to domain of license

3.8.1. Proposal

Add schema:WebAPI to the domain of schema:license, to describe the license for the design/signature of the API.

3.8.2. Example

"license": "https://creativecommons.org/licenses/by/3.0/",

3.9. Add url to the WebAPI example

3.9.1. Proposal

Include the following in the documentation of schema:WebAPI:

The url property indicates a landing page for the API, which is a Web page that can be navigated to in a Web browser to gain access to the API and/or additional information.

Add the following to the examples to the https://schema.org/WebAPI page:

"url": "https://developers.google.com/knowledge-graph/",
"documentation": "https://developers.google.com/knowledge-graph/reference/rest/v1",

3.9.2. Notes

The DCAT v2 to schema.org mapping overloads the schema:url property for both dcat:endpointURL and dcat:landingPage. Hence url should be used for the landing page of the API (e.g. https://azure.microsoft.com/en-gb/services/cdn/) rather than the documentation (e.g. https://docs.microsoft.com/en-gb/azure/cdn/).

5. Full example

A fuller example of a WebAPI annotation, including the proposed properties.

{
  "@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/reference/rest/v1",
  "endpointDescription": [
    {
      "@type": "CreativeWork",
      "encodingFormat": "application/json",
      "url": "https://kgsearch.googleapis.com/$discovery/rest?version=v1"
    },
    {
      "@type": "CreativeWork",
      "encodingFormat": "application/vnd.oai.openapi+json;version=3.0",
      "url": "https://api.apis.guru/v2/specs/googleapis.com/kgsearch/v1/openapi.json"
    }
  ],
  "url": "https://developers.google.com/knowledge-graph/",
  "termsOfService": "https://developers.google.com/knowledge-graph/terms",
  "logo": "https://www.google.com/images/branding/googlelogo/2x/googlelogo_color_272x92dp.png",
  "license": "https://creativecommons.org/licenses/by/3.0/",
  "provider": {
    "@type": "Organization",
    "name": "Google Inc.",
    "contactPoint": [
      {
        "@type": "ContactPoint",
        "name": "Google",
        "url": "https://google.com"
      }
    ],
  },
  "version": "1.0.0",
  "endpointUrl": [
    {
      "@type": "EntryPoint",
      "name": "Production (uses live data)",
      "url": "https://kgsearch.googleapis.com/",
      "contentType": "application/json"
    },
    {
      "@type": "EntryPoint",
      "name": "Sandbox (uses test data)",
      "url": "https://sandbox.kgsearch.googleapis.com/",
      "contentType": "application/json"
    }
  ],
  "apiTransport": [
    "HTTP",
    "HTTPS"
  ],
  "conformsTo": [
    "https://jsonapi.org/format/1.0/"
  ],
  "potentialAction": [
    {
      "@type": "ConsumeAction",
      "name": "API Client Registration",
      "target": "https://developers.google.com/knowledge-graph/how-tos/authorizing"
    }
  ]
}