WADG0001 WebAPI type extension

Draft Community Group Report,

This version:
Issue Tracking:
Mike Ralphson (Mermade Software)
Ivan Goncharov (APIs.guru)


It is proposed to create an extension to the Schema.Org WebAPI type to facilitate better automatic discovery of WebAPIs and associated machine- and human-readable documentation.


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.

Note: See this article for an explanation of the difference between API documentation, specifications and definitions.

2. Proposed Extension

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 as follows:

The extension properties (and their types) are:

The Content-Type(s) consumed by the WebAPI MAY be included in the EntryPoint.contentType property. The Content-Type(s) produced by the WebAPI MAY be included in the EntryPoint.responseContentType property.

2.1. Content-Types

The webApiDefinitions (EntryPoint) contentType property MUST contain the singular contentType relevant to the API description format used. It is RECOMMENDED that IANA-registered contentTypes be used. For example, application/wsdl+xml is the IANA registered content-type for the Web Service Definition Language. The following non-IANA contentTypes MAY additionally be used:

Format Content-Type
OpenAPI / Swagger in YAML application/vnd.oai.openapi
OpenAPI / Swagger in JSON application/vnd.oai.openapi+json
RAML application/raml+yaml
API Blueprint in markdown text/vnd.apiblueprint
API Blueprint parsed in YAML application/vnd.refract.parse-result+yaml
API Blueprint parsed in JSON application/vnd.refract.parse-result+json

Content-Types MAY include a ;version parameter where appropriate.

Other content-Types such as application/ld+json, application/json, text/markdown etc MAY be used, with decreasing levels of machine-readability. The webApiDefinition (EntryPoint) encodingType property MAY also be specified.

2.2. webApiActions

Valid Action.names for webApiActions are:

Name Description
apiAuthentication Links to a resource detailing authentication requirements. Note this is a human-readable resource, not an authentication endpoint
apiClientRegistration Links to a resource where a client may register to use the API
apiConsole Links to an interactive console where API calls may be tested
apiPayment Links to a resource detailing pricing details of the API
apiSLA Links to a resource detailing the Service Level Agreement relating to the API. This may be machine- or human-readble.
apiSupport Links to a resource where a client may obtain support for the API

3. Example

A fuller example of a WebAPI annotation, including the extension attributes. Note the @type name is still to be determined.

  "@context": "http://schema.org/",
  "@type": "ActionableWebAPI",
  "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",
  "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"
  "versions": [
  "entryPoints": [
      "@type": "EntryPoint",
      "url": "https://kgsearch.googleapis.com/",
      "contentType": "application/json",
      "responseContentTypes": "application/json"
  "transport": "HTTP",
  "apiProtocol": "JSON API",
  "webApiDefinitions": [
      "@type": "EntryPoint",
      "contentType": "application/json",
      "url": "https://kgsearch.googleapis.com/$discovery/rest?version=v1"
      "@type": "EntryPoint",
      "contentType": "application/vnd.oai.openapi+json;version=2.0",
      "url": "https://api.apis.guru/v2/specs/googleapis.com/kgsearch/v1/swagger.json"
  "webApiActions": [
      "@type": "ConsumeAction",
      "name": "apiAuthentication",
      "target": "https://developers.google.com/knowledge-graph/how-tos/authorizing"


Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.


Terms defined by this specification


Normative References

S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Informative References

API Blueprint. URL: https://apiblueprint.org
apis.json. URL: http://apisjson.org/format/apisjson_0.15.txt
JSON-home. URL: https://tools.ietf.org/html/draft-nottingham-json-home-06
OpenAPI Specification v3.0.2. URL: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.2.md
RAML 1.0. URL: https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md
Semantic Versioning 2.0.0. URL: https://semver.org/