To the extent possible under law, the editors have waived all copyright
and related or neighboring rights to this work.
In addition, as of 16 October 2022,
the editors have made this specification available under the Open Web Foundation Agreement Version 1.0,
which is available at http://www.openwebfoundation.org/legal/the-owf-1-0-agreements/owfa-1-0.
Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.
Abstract
This document provides additional terms and examples of using SHACL together with Hydra to describe API’s hyperemedia
1. Introduction
Hydra Core vocabulary does define a handful of data modeling terms such as hydra:Class and hydra:supportedProperty which can be used to build basic APIs. However, it was never a goal of Hydra Core to become a full-blown modeling language, given available alternatives.
One such alternative is [SHACL], which is defined by its authors as "a language for validating RDF graphs against a set of conditions", yet its usefulness goes way beyond just data validation. See the SHACL Use Cases and Requirements note for various ideas for employing [SHACL].
In this document we propose various ways in which [SHACL] can be used by both Hydra API publishers and consumers to facilitate client-server interaction.
2. Conventions
The base namespace of extensions is https://w3id.org/hydra/extension#.
The preferred prefix is hex:.
The unique identifier of the SHACL extension is https://w3id.org/hydra/extension#shacl
3. Announcing the extension
Conforming with the Extensions section of [Hydra], an API MUST announce the use of an extension by adding it to its hydra:ApiDocumentation:
4.1. Using Node Shapes to describe request payloads
Node Shapes used as objects of hydra:expects
4.2. Discovering shapes
Add a specialized property to link to a collection of shapes
4.3. Providing choices to properties
Provide choices for properties rendered in a form as dash:EnumSelectEditor and dash:InstancesSelectEditor.
4.3.1. Using hydra:collection
Static choices
4.3.2. Using hydra:search
Filtered choices
5. SHACL Shapes for Hydra Core terms
Model the Hydra Core vocabulary as node shapes
Conformance
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:
