rfc0001.bs

<p class="copyright">
Copyright © 2017,2019,2020 the Contributors to the WADG0001/Jul2020 report, published by the <a href="https://www.w3.org/community/web-api-discovery">W3 WebAPI Discovery Community Group</a> under the <a href="http://www.w3.org/community/about/agreements/cla/">W3C Community Contributor License Agreement (CLA)</a>. A human-readable <a href="http://www.w3.org/community/about/agreements/cla-deed/">summary</a> is available.
</p>

<a href=http://www.w3.org/><img alt=W3C height=48 src=http://www.w3.org/Icons/w3c_home width=72></a>
<pre class='metadata'>
Title: WADG0001 WebAPI type extension
H1: Version 0.4.0
Date: 2020-07-08
Shortname: wadg0001
Revision: 4
Status: w3c/CG-DRAFT
Group: w3c
URL: https://webapi-discovery.github.io/rfcs/rfc0001.html
Editor: Mike Ralphson, Mermade Software
Editor: Nick Evans, Open Data Institute, http://nickevans.me/
Former Editor: Ivan Goncharov, APIs.guru
Repository: webapi-discovery/rfcs
Abstract: It is proposed to create an extension to the <a href="https://schema.org/">Schema.Org</a> <a href="https://pending.schema.org/WebAPI">WebAPI</a> type to facilitate better automatic discovery of WebAPIs and associated machine- and human-readable documentation.
Markup Shorthands: css no, markdown yes
Ignored Terms: h1, h2, h3, h4, h5, h6, xmp
</pre>

<pre class=biblio>
{
	"OpenAPI": {
		"title": "OpenAPI Specification v3.0.3",
		"href": "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.3.md"
	},
	"RAML": {
		"title": "RAML 1.0",
		"href": "https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md"
	},
	"API-Blueprint": {
		"title": "API Blueprint",
		"href": "https://apiblueprint.org"
	},
	"JSON-home": {
		"title": "JSON-home",
		"href": "https://tools.ietf.org/html/draft-nottingham-json-home-06"
	},
	"apis.json": {
		"title": "apis.json",
		"href": "http://apisjson.org/format/apisjson_0.15.txt"
	},
	"semver": {
		"title": "Semantic Versioning 2.0.0",
		"href": "https://semver.org/"
	}
}
</pre>

<p style="display:none" class="copyright" data-fill-with="copyright"></p>

This draft report is the work of the <a href="https://www.w3.org/community/web-api-discovery/">W3 WebAPI Discovery Community Group</a>

<p>This report was published by the <a href="https://www.w3.org/community/web-api-discovery">W3 WebAPI Discovery Community Group</a>. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the <a href="http://www.w3.org/community/about/agreements/cla/">W3C Community Contributor License Agreement (CLA)</a> there is a limited opt-out and other conditions apply. Learn more about <a href="http://www.w3.org/community/">W3C Community and Business Groups</a>.</p>

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

# Definitions

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

<div class="note">Note: See <a href="http://nordicapis.com/difference-api-documentation-specification-definition/">this article</a> for an explanation of the difference between API documentation, specifications and definitions.</div>

# 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.


# Proposed extension

Schema.org's Dataset vocabulary was originally [based on DCAT](https://schema.org/docs/data-and-datasets.html), which in turn used Dublin Core and FOAF terms. [DCAT Version 2](https://www.w3.org/TR/vocab-dcat-2/) is now current, and is therefore used within this draft.

The base [schema.org](https://schema.org/) [WebAPI](https://schema.org/WebAPI) type, for example:

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

## New property `endpointUrl`

### Proposal

<table>
<thead>
<tr>
<th>Property</th>
<th>Domain</th>
<th>Range</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`endpointUrl`</td>
<td>`schema:WebAPI`</td>
<td>`schema:URL`, `schema:EntryPoint`</td>
<td>The root location or primary endpoint of the API.</td>
</tr>
</tbody>
</table>

### Examples

Simple usage:

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

Advanced usage:

```json
"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"
  }
],
```

### Notes

This proposal brings the property above [directly from DCAT v2](https://www.w3.org/TR/vocab-dcat-2/#Property:data_service_endpoint_url). The [DCAT v2 to schema.org mapping](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo) 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.

## Update description for `documentation` property

### 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.

### 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](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo) that recommends the `schema:documentation` property for *both* human-readable documentation and <a>machine-readable API definitions</a>. A proposal for a separate `endpointDescription` property reserved for <a>machine-readable API definitions</a> can be found below.

An alternative that was considered was to use `schema:documentation` for *both* human-readable documentation and <a>machine-readable API definitions</a>, bringing it *fully* in line with [DCAT v2](https://www.w3.org/TR/vocab-dcat-2/#Property:data_service_endpoint_description), and the [DCAT v2 to schema.org mapping](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo). Such an approach was discounted as it would have necessitated the use of "whitelists" of human- and machine-readable `encodingFormat`s by data consumers to distinguish between them, which would have entailed unnecessary complexity and maintenance.


## New property `endpointDescription`


### Proposal

<table>
<thead>
<tr>
<th>Property</th>
<th>Domain</th>
<th>Range</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`endpointDescription`</td>
<td>`schema:WebAPI`</td>
<td>`schema:CreativeWork`</td>
<td>
  <p>Machine-readable API definition of the services available via the `WebAPI`, including their operations, parameters etc.</p>
  <p>Machine-readable formats include OpenAPI (Swagger) description, an OGC GetCapabilities response WFS, ISO-19142, WMS, ISO-19128, a SPARQL Service Description, an OpenSearch or WSDL20 document, or a Hydra API description. The `encodingFormat` of the `CreativeWork` should be used to indicate the use of such formats via their MIME type.</p>
  <p>The `endpointDescription` property gives specific details of the actual endpoint instances, while the `conformsTo` property is used to indicate the general standard or specification that the endpoints implement.</p>
</td>
</tr>
</tbody>
</table>

### Examples

```json
"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"
  }
],
```

### Notes

This proposal brings the property above [directly from DCAT v2](https://www.w3.org/TR/vocab-dcat-2/#Property:data_service_endpoint_description), using `schema:CreativeWork` to be consistent with the range of `schema:documentation`.

The [DCAT v2 to schema.org mapping](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo) 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.


## New property `conformsTo`

### Proposal

<table>
<thead>
<tr>
<th>Property</th>
<th>Domain</th>
<th>Range</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`conformsTo`</td>
<td>`schema:WebAPI`</td>
<td>`schema:URL`</td>
<td>The URL reference of an established standard to which the described API conforms, for example `https://jsonapi.org/format/1.0/`, `https://grpc.io/`, or `http://www.hydra-cg.com/spec/latest/core/`.</td>
</tr>
</tbody>
</table>

### Example

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

### Notes

This proposal brings the property [directly from DCAT v2](https://www.w3.org/TR/vocab-dcat-2/#Property:data_service_endpoint_url).

The [DCAT v2 to schema.org mapping](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo) does not include `conformsTo`. The mapping gap was recognised in [previous mapping attempts](https://ec-jrc.github.io/dcat-ap-to-schema-org/#mapping-properties-dataset) and not addressed within [DCAT v2 discussions](https://github.com/w3c/dxwg/issues/251).

## New property `accessService`

### Proposal

<table>
<thead>
<tr>
<th>Property</th>
<th>Domain</th>
<th>Range</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`accessService`</td>
<td>`schema:Dataset`, `schema:DataDownload`</td>
<td>`schema:WebAPI`</td>
<td>An API that provides access to the dataset</td>
</tr>
</tbody>
</table>

### Example

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

### Notes

The [DCAT v2 to schema.org mapping](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo) 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](https://www.w3.org/TR/vocab-dcat-2/#Property:data_service_serves_dataset) 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](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo) does not include `accessService`.

## Add `WebAPI` to domain of `version`

### Proposal

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

### Example

```json
"version": "1.0.0",
```

### Notes

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

## New property `apiTransport`

### Proposal

<table>
<thead>
<tr>
<th>Property</th>
<th>Domain</th>
<th>Range</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>`apiTransport`</td>
<td>`schema:WebAPI`</td>
<td>`schema:Text`</td>
<td>The type of transport used for the API, such as HTTP, HTTPS, SMTP, MQTT, WS, WSS</td>
</tr>
</tbody>
</table>

### Example

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

### Notes

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


## Add `WebAPI` to domain of `license`

### Proposal

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

### Example

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

## Add `url` to the `WebAPI` example

### 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](https://schema.org/WebAPI) page:

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

### Notes

The [DCAT v2 to schema.org mapping](https://www.w3.org/TR/vocab-dcat-2/#dcat-sdo) 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/](https://azure.microsoft.com/en-gb/services/cdn/)) rather than the documentation (e.g. [https://docs.microsoft.com/en-gb/azure/cdn/](https://docs.microsoft.com/en-gb/azure/cdn/)).

<div class="non-normative">

# Suggested values

This section is non-normative, and these values are outside the scope of schema.org. They serve as an illustration of suggested usage.

## `encodingFormat` values

When `encodingFormat` is used to specify the API description format used, and where an <a href="https://iana.org">IANA</a>-registered media type is not available, the following widely recognised non-IANA media types may be used:

<table class=data>
<thead>
<tr>
<th>Format
<th>Media type
<tbody>
<tr><td>OpenAPI / Swagger in YAML<td>`application/vnd.oai.openapi`
<tr><td>OpenAPI / Swagger in JSON<td>`application/vnd.oai.openapi+json`
<tr><td>RAML<td>`application/raml+yaml`
<tr><td>API Blueprint in markdown<td>`text/vnd.apiblueprint`
<tr><td>API Blueprint parsed in YAML<td>`application/vnd.refract.parse-result+yaml`
<tr><td>API Blueprint parsed in JSON<td>`application/vnd.refract.parse-result+json`
</tbody>
</table>

Media types may include a `;version` parameter where appropriate.

Other media types such as <b>application/ld+json</b>, <b>application/json</b>, <b>text/markdown</b>, etc. may be used, with decreasing levels of machine-readability.


## `Action` `name` values

A number of `Action` names are suggested for use with `potentialAction` of `WebAPI`, though this list is not exhaustive:

<table class=data>
<thead>
<tr>
<th>Name
<th>Description
<tbody>
<tr><td>`API Authentication` <td> Links to a resource detailing authentication requirements. Note this is a human-readable resource, not an authentication endpoint
<tr><td>`API Client Registration` <td> Links to a resource where a client may register to use the API
<tr><td>`API Console` <td> Links to an interactive console where API calls may be tested
<tr><td>`API Payment` <td> Links to a resource detailing pricing details of the API
<tr><td>`API SLA` <td> Links to a resource detailing the Service Level Agreement relating to the API. This may be machine- or human-readable.
<tr><td>`API Support` <td> Links to a resource where a client may obtain support for the API
</tbody>
</table>

</div>



Full example
=======

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


```json
{
  "@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"
    }
  ]
}
```