Potential Actions

What follows describes some terminology and conventions for use with http://schema.org/Action. The purpose is to enable describing the capability to perform an action in the future, as well as how that capability can be exercised. See the blog post Schema.org Actions (April 2014) for more background. Earlier drafts and alternate formats are available from the W3C Wiki.

Part 1: Action status

First, we need a mechanism for differentiating potential actions from actions that have actually taken place or are even still in-progress. The expectation is that the status of an action will often be self-evident based on the usage context, so this property can often be elided. However, it may still be necessary for resolving ambiguous cases when they arise. For this we introduce a new property of Action called "actionStatus.

Thing > Action

Thing > Intangible > Enumeration > ActionStatusType

• PotentialActionStatus - A description of an action that is supported
• ActiveActionStatus - An in-progress action (e..g, while watching the movie, or driving to a location)
• CompletedActionStatus - An action that has already taken place.

Example: actionStatus

Part 2: Connecting Actions to Things

Frequently actions are taken or offered in the context of an object (e.g., watch this movie, review this article, share this webpage, etc.). We introduce a new property called potentialAction for describing the "prototype" of an action that can be taken on that Thing.

Thing

Example: Thing.potentialAction

Part 3: Action EntryPoints

Potential actions are materialized via execution against the target EntryPoint of an Action.

Example: Action target URL

For some platforms and use cases, however, a simple URL is insufficient for formulating a request and/or processing the result, so we are introducing a new EntryPoint class for specifying that additional context beyond a URL when necessary.

Action

Thing > Intangible > EntryPoint

Scheme-based encoding of EntryPoint

Ideally, the simple "deep link" use cases should work with just a simple URL template. In some cases, new schemes might even be created to make that possible for some platforms, for example:

android-app://{package_id}/{scheme}/{host_path}

Example: Multiple platform URLs

Note: we expect the detail of platform-specific bindings to evolve and be clarified through implementation experience. These examples indicate the general approach rather than the exact information needs of each platform. Also note that the example syntax shown here is not strictly JSON; inline comments have been added for readability.

Part 4: Input and Output constraints

Additional information is often required from a user or client in order to formulate a complete request. To facilitate this process we need the ability to describe within a potential action how to construct these inputs. Since we need this capability for filling in any property of an Action, we introduce a notion of property annotations using a hypen ("-") delimiter. For example, by specifying a "location-input" property on a potential action we are indicating that "location" is a supported input for completing the action.

Similarly, it is also helpful to indicate to clients what will be included in the final completed version of an action, so we introduce the corresponding -output annotation for indicating which properties will be present in the completed action.

Thing > Intangible > PropertyValueSpecification

A property value specification.

The minValue, maxValue and stepValue properties specify the allowed range and intervals for literal values and are equivalent to HTML's input@min, max, step. It should also be noted that if both a property and its -input annotation are present, the value of the un-annotated property should be treated as the allowed options for input (similar to <select><option> in HTML) unless the Input indicates that the value is also readonly, in which case the value(s) should all be returned in a manner analogous to hidden inputs in forms.

Textual representations of Input and Output
For convenience, we also support a textual short-hand for both of these types that is formatted and named similarly to how they would appear in their HTML equivalent. For example:

"<property>-input": {
  "@type": "PropertyValueSpecification",
  "valueRequired": true,
  "valueMaxlength": 100,
  "valueName": "q"
}

Can also be expressed as:

<property>-input: "required maxlength=100 name=q"

URI Templates
Finally, we also allow URI templating (using RFC6570) for inlining the resulting value of -input properties into action URLs. The allowed references in the templates for substitution are dotted schema paths to the filled-in properties (relative to the Action object).

Example: Text search deep link with -input

description

request

Example: Product purchase API call with -output

description

request

response

Example: Movie review site API with -input and -output

description

request

response