Hydra is a lightweight vocabulary to create hypermedia-driven Web APIs. This document describes how a subset of Hydra could be integrated into Schema.org.
This document was created to help with the design of potential Actions in Schema.org. While Hydra hasn't been included in Schema.org (yet), it influenced its design. The document is clearly outdated and serves purely as a historical reference.
To participate in the development of this specification, please join the Hydra W3C Community Group. If you want to suggest a feature or discuss one, you should send a mail to the public-hydra@w3.org mailing list. Specification bugs and issues should be reported in the issue tracker.
This document proposes the introduction of a subset of the Hydra Core Vocabulary [[!HYDRA-CORE]] into Schema.org to make Schema.org's Actions executable. Hydra describes all the details necessary for a client to invoke Actions or follow hyperlinks in order to achieve certain application-specific goals.
This document is based on "Actions" as defined in Actions in schema.org (draft 4). Instead of describing the subset of Hydra here, we concentrate on the differences to the Actions in schema.org draft. For a more thorough explanation of Hydra, please refer to [[HYDRA-CORE]].
This section will illustrate how the Hydra can be used to realize a few of GMail's Action examples. Some examples will use concepts which are not defined in Schema.org yet. We will comment the examples accordingly. Furthermore, we will highlight the concepts introduced by Hydra.
In GMail, one click actions allow users to perform one-click operations directly without having to leave GMail. At the moment GMail supports two types of one click actions: ConfirmAction and SaveAction. Since the mechanism is the same we won't describe the later.
Instead of introducing the notion of an ActionHandler, Hydra assigns the approval request a URL and describes the operations supported by that resource. Consequently the URL can be used to approve the request sending an empty POST. Typically, however, it would make more sense to include data in the POST to make the intent explicit and at the same time to allow to reject the request.
Accept or decline an event invitation.
This tells a client how to send a RsvpResponse in order to accept or decline the EventInvitation. The definition of RsvpResponse defines the required properties:
While this example could be realized the same way as above, we will show an alternative by creating an anonymous inline class.
The following sections define the concepts to be introduced in Schema.org.
Subclass of Intangible > Thing
Equivalent to hydra:Operation
| Property | Type | Description | Equivalent to |
|---|---|---|---|
| method | Text | The HTTP method. | hydra:method |
| expects | Class | The information expected by the Web API. | hydra:expects |
| returns | Class | The information returned by the Web API on success. | hydra:returns |
Subclass of Thing
Equivalent to hydra:Class
| Property | Type | Description | Equivalent to |
|---|---|---|---|
| supportedProperty | SupportedProperty | The properties known to be supported by a class. | hydra:supportedProperty |
| supportedOperation | Class | The operations supported by instances of this class. | hydra:supportedOperation |
Subclass of Intangible > Thing
Equivalent to hydra:SupportedProperty
| Property | Type | Description | Equivalent to |
|---|---|---|---|
| property | Property | The property. | hydra:property |
| required | Boolean | True if the property is required, false otherwise. | hydra:required |
| readonly | Boolean | True if the property is read-only, false otherwise. | hydra:readonly |
| writeonly | Boolean | True if the property is write-only, false otherwise. | hydra:writeonly |
In order to properly document Web APIs and to be able to distinguish URIs used purely as identifiers from URLs intended to be dereferenced, the introduction of the following concepts may be sensible as well.
Subclass of WebResource > CreativeWork > Thing
Equivalent to hydra:ApiDocumentation
| Property | Type | Description | Equivalent to |
|---|---|---|---|
| entrypoint | WebResource | A link to main entry point of the Web API. | hydra:entrypoint |
| supportedClass | Class | The classes known to be supported by the Web API. | hydra:supportedClass |
Subclass of CreativeWork > Thing
Equivalent to hydra:Resource
| Property | Type | Description | Equivalent to |
|---|---|---|---|
| operation | Operation | The operations supported a Hydra resource. | hydra:operation |
WebPage should become a subtype of WebResource.
Subclass of Property > Thing
Equivalent to hydra:Link
| Property | Type | Description | Equivalent to |
|---|---|---|---|
| supportedOperation | Class | The operations supported by the targets of Hydra links. | hydra:supportedOperation |