TREE Profile specification

Draft Community Group Report,

More details about this document
This version:
https://w3id.org/tree/specification/profile
Feedback:
public-treecg@w3.org with subject line “[TREEProfile] … message topic …” (archives)
Issue Tracking:
GitHub
Editor:
Pieter Colpaert

Abstract

This specification defines a profile to allow clients to parse in a streaming fashion and extract TREE members, complementing the more computationally intensive Member Extraction Algorithm in scenarios where throughput is a concern.

Status of this document

1. Introduction

This specification introduces profiles for serializations such as [n-triples], [n-quads], [turtle] and [TRiG] to first contain a group for the hypermedia, and then contain groups for the members. The profile is optional to implement, yet comes with the benefit that it allows TREE clients to speed up extracting members and process them in a streaming fashion. The TREE profile does this by promising to a TREE client that the triples about the members are going to be bundled together.

2. Discovering the profile through the content-type header

There are two ways in which a client MAY discover the fact that the TREE profile has been used.

  1. The server add ;profile="https://w3id.org/tree/profile" to the content-type headers on top of their [turtle], [n-quads], [turtle] or [TRiG] responses, such as Content-Type: text/turtle;profile="https://w3id.org/tree/profile.

  2. The server uses for their node links a .tree prefix in the suffix of the file format. E.g., https://example.org/file.tree.nq.

3. An example

@prefix ex: <https://example.org/> .
@prefix tree: <https://w3id.org/tree/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.

# The document starts with hypermedia controls
<> tree:relation [
    a tree:GreaterThanOrEqualToRelation ;
    tree:node <?greaterThanOrEqualTo=10>;
    tree:value 10;
    tree:remainingItems 10 ;
    tree:path ex:value
] .

ex:Collection1 a tree:Collection;
            tree:view <> ;
            rdfs:label "A Collection of 2 subjects"@en;
# `tree:member` indicates the hypermedia group is done, and the first member begins
            tree:member ex:Subject1 .

ex:Subject1 a ex:Subject ;
            rdfs:label "Subject 1" ;
      ex:value 2 ;
            ex:linkedTo [ a ex:Subject ] .

# Start of the second member
ex:Collection1 tree:member ex:Subject2 .
ex:Subject2 a ex:Subject ;
            rdfs:label "Subject 2" ;
      ex:value 9 ;
            ex:linkedTo ex:Subject1 .
# EOF flags the end of the second member

4. Implementing a TREE profile client

The client in this case MUST use a parser that retains triple order as in the original document.

When the profile is set (see [](#profile)), the client MAY implement the profile algorithm and not perform the steps indicated by the Member Extraction Algorithm. In this case, a client MUST assume the document starts with a hypermedia block. It then follows three simple rules:

  1. From the moment the tree:member property is used, a new bundle of member quads will start.

  2. From the moment the base IRI (<>) is used in the subject position, or when a tree:view property is used, a new block of hypermedia starts.

  3. When end of file is encountered, the currently active block is closed.

Each member SHOULD be emitted from the moment it has been extracted. The client MUST wait for the end of the file before emitting the hypermedia.

Conformance

Document conventions

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:

Note, this is an informative note.

References

Normative References

[N-QUADS]
Gavin Carothers. RDF 1.1 N-Quads. URL: https://w3c.github.io/rdf-n-quads/spec/
[N-TRIPLES]
Gavin Carothers; Andy Seaborne. RDF 1.1 N-Triples. URL: https://w3c.github.io/rdf-n-triples/spec/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[TRiG]
Gavin Carothers; Andy Seaborne. RDF 1.1 TriG. URL: https://w3c.github.io/rdf-trig/spec/
[TURTLE]
Eric Prud'hommeaux; Gavin Carothers. RDF 1.1 Turtle. URL: https://w3c.github.io/rdf-turtle/spec/