Definition

A Quad Pattern Fragment is a Linked Data Fragment [[!HYDRA-LDF]] of a dataset with the following characteristics:

data

A Quad Pattern Fragment MUST contain all quads of the dataset that match a given quad pattern “?subject ?predicate ?object ?graph.”,

A Quad Pattern Fragment MAY additionally contain other data quads.

metadata

A Quad Pattern Fragment MUST contain one or more quads that express the estimated total number of matches for the quad pattern.

A Quad Pattern Fragment MAY contain additional metadata.

hypermedia controls

A Quad Pattern Fragment MUST contain hypermedia controls that allow to retrieve any other Quad Pattern Fragment of the same dataset. This MUST either be provided as a form that allows to choose subject, predicate, object, and graph of the selector's graph pattern, or as a form that allows to choose subject, predicate, and object of the selector's graph pattern in the default graph. In the latter case we can simply speak of a Triple Pattern Fragment, this means that every Triple Pattern Fragment is also a Quad Pattern Fragment.

A Quad Pattern Fragment MAY contain additional hypermedia controls. The IRIs of data, metadata, and control quads entities SHOULD be dereferenceable.

A Quad Pattern Fragment of a dataset is fully determined and identified by its quad pattern selector. This selector consists of four components subject, predicate, object, and graph [[!RDF11-CONCEPTS]]. The subject MUST either be a variable or an IRI; the predicate MUST either be a variable or an IRI; the object MUST either be a variable, an IRI, or a literal; the graph MUST either be a variable or an IRI; These components MUST NOT be blank nodes.

The above constraints define the document type of Quad Pattern Fragments. The following sections , , and explain this in more detail. Quad Pattern Fragments SHOULD be paged, as detailed in .

Quad Pattern Fragments are not bound to a specific syntax because different methods can be used to represent its data, metadata, and controls. The server MUST, however, support at least one RDF-based representation that SHOULD allow for quads to be represented. This representation MAY instead also allow for just triples to be represented. For allowing clients to correctly parse requests Quad Pattern Fragments, servers MUST indicate the correct MIME type when responding with those fragments.

For RDF syntaxes without named graph support (such as Turtle or N-Triples), the data, metadata, and controls SHOULD be serialized to the same graph, quad graphs MUST be truncated. This means that all quads will be present in the default graph. The interface MAY return an error response stating that the requested serialization format is not supported. For RDF syntaxes with multiple graph support (such as JSON-LD, TriG or N-Quads), the data MUST be serialized to their respective graphs and the metadata and controls MUST be serialized to one or multiple non-default graphs.

When the above constraints are taken into account, every Quad Pattern Fragment can be interpreted as a Triple Pattern Fragment for backwards-compatibility with TPF-clients and each Triple Pattern Fragment can still be interpreted as a Quad Pattern Fragment for backwards-compatibility with TPF-servers.

A Quad Pattern Fragments server is a Triple Pattern Fragments server that provides access to Quad Pattern Fragments, a generalization of Triple Pattern Fragments.

The dataset that is made available through a Quad Pattern Fragments server MUST follow the document type as defined in next to the dataset requirements defined by Triple Pattern Fragments.

Data

A Quad Pattern Fragment contains all quads of a dataset that matches the fragment's quad pattern selector. These quads SHOULD be consistently ordened such that Quad Pattern Fragments can be paged consistently. Quads SHOULD NOT contain blank nodes, instead these blank nodes SHOULD be skolemized.

If the RDF syntax does not support multiple graphs, data quads SHOULD be converted to triples by truncating their graph. Otherwise, the MAY return an error response stating that the requested serialization format is not supported. In case of an HTTP [[RFC7230]] implementation, this SHOULD be an HTTP 406 [[RFC2616]] error. If the RDF syntax supports multiple graphs, data quads MUST be serialized to their respective graph.

Metadata

Each Quad Pattern Fragment and Quad Pattern Fragment page MUST contain an estimate of the total number of quads matching this fragment's selector. This MUST be expressed as a triple in the metadata graph with the following components:

subject

the IRI of the fragment

predicate

the void:triples predicate

object

an integer literal expressing the estimated total number of matching triples

The estimate MUST be a non-negative, finite, integer number with the following properties:

• If no quads match the selector, the estimate MUST be zero.
• If one or more quads match the selector, the estimate MUST NOT be zero.
• The estimate SHOULD be as close as possible to the actual number of matches.
• If the number of matching quads is smaller than the number of items per page, the estimate SHOULD be exactly the number of matching triples.

The metadata MAY additionally contain variations of the above triple. For instance, it is RECOMMENDED to add a triple with the same subject and object and the hydra:totalItems predicate.

Each Quad Pattern Fragment and Quad Pattern Fragment page MUST contain a triple in the metadata graph declaring the default graph of the interface's dataset if this default graph contains at least one triple. Each Quad Pattern Fragment and Quad Pattern Fragment page MAY contain a triple in the metadata graph declaring the default graph of the interface's dataset if this default graph is empty. This MUST be expressed as a triple with the following components:

subject

the IRI of the dataset

predicate

the sd:defaultGraph predicate

object

a URI refering to the default graph of the interface's dataset.

If the RDF syntax supports named graphs, metadata triples MUST be serialized to a non-default graph. This non-default graph MUST be explicitly related to the Quad Pattern Fragment using the foaf:primaryTopic predicate, so clients can interpret what resource this metadata belongs to. This relating triple MUST be present in metadata graph. This graph SHOULD be the same as the graph containing the hypermedia controls.

Hypermedia controls

Each Quad Pattern Fragment and Quad Pattern Fragment page MUST contain a hypermedia control through which the IRI of any other Quad Pattern Fragment of the same dataset can be generated.

This control MUST either be in function of the four input parameters subject, predicate, object, and graph, or in function of the three input parameters subject, predicate, and object. In the latter it is simply a Triple Pattern Fragment control where the graph parameter is assumed to be empty. Each of these parameters can either be a variable, a constant IRI, or (in the case of object) a constant literal. The output of this function MUST be the IRI of the dataset's Quad Pattern Fragments whose identifying selector has the given parameter values.

This control MUST be expressed as a form in the Hydra Core Vocabulary [[!HYDRA-CORE]] using triples in the controls graph. This structure MUST either be as the Triple Pattern Fragments control form or as the following:

<http://example.org/example#controls>
      {
        <http://example.org/example#dataset>
        void:subset <http://example.org/example?s=http%3A%2F%2Fexample.org%2Ftopic>;
        <http://example.org/example#controls>
        foaf:primaryTopic <http://example.org/example#dataset>;
        hydra:search [
            hydra:template "http://example.org/example{?s,p,o,g}";
            hydra:mapping  [ hydra:variable "s"; hydra:property rdf:subject ],
                           [ hydra:variable "p"; hydra:property rdf:predicate ],
                           [ hydra:variable "o"; hydra:property rdf:object ],
                           [ hydra:variable "g"; hydra:property sd:graph ]
        ].
      }

The above snippet assumes the dataset IRI is http://example.org/example#dataset, the controls graph is http://example.org/example#controls, the fragment (or fragment page) IRI is http://example.org/example?s=http%3A%2F%2Fexample.org%2Ftopic, and the IRI template [[!RFC6570]] to retrieve Quad Pattern Fragments of the dataset is http://example.org/example{?s,p,o,g}. It also assumes that the parameter names of subject, predicate, object, and graph are respectively s, p, o, and g. This dataset IRI, fragment (or fragment page) IRI, template and mapping MUST be adjusted for each fragments server to have a fitting configuration. The control form MUST be attached to the dataset since the form filters the dataset, and not the fragment. The fragment MUST be declared as a subset of the dataset such that their relation becomes apparent.

These hypermedia controls generally accept strings as input. The conversion of IRIs, literals, and variables to strings is specified by Triple Pattern Fragments.

If the RDF syntax supports multiple graphs, control triples MUST be serialized to a non-default graph. This non-default graph MUST be explicitly related to the Quad Pattern Fragment using the foaf:primaryTopic predicate, so clients can interpret what resource this metadata belongs to. This relating triple must be present in controls graph. This graph SHOULD be the same as the graph containing the metadata

Clients that use these controls MAY omit any of the parameters. A control parameter that is not present MUST have the same effect as that parameter being the empty string, they MUST be seen as a wildcard being able to match any value for that parameter.

Not providing the graph parameter or giving it an empty string value selects quads with any named graph, i.e., triples from all possible graphs in the dataset. To be able to select triples from the default graph, its IRI must be entered as value in the graph parameter, which is identified as metadata by the sd:defaultGraph predicate.

Paging

Quad Pattern Fragments SHOULD be paged to avoid overly large responses. A page of a Quad Pattern Fragment has the same characteristics as a Triple Pattern Fragment page.