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.

One Click Actions

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.

RSVP Action

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:


Review Action

While this example could be realized the same way as above, we will show an alternative by creating an anonymous inline class.


Vocabulary Specification

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

Additional Concepts for Hypermedia-Driven Web APIs

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