|
Open Services for Lifecycle Collaboration
Tracked Resource Set Specification Version 2.0
|
Status: WORKING DRAFT 2.0 Specification - February 27, 2013
This Version
Latest Version
PreviousVersion
Authors
Contributors
Table of Contents
Contents
License
This work is licensed under a Creative Commons Attribution License.
Notation and Conventions
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC2119. Domain name examples use RFC2606.
Introduction
The Tracked Resource Set protocol allows a server to expose a set of resources in a way that allows clients to discover the exact set of resources in the set, to track all additions to and removals from the set, and to track state changes to all resources in the set. The protocol does not assume that clients will dereference the resources. The protocol is suitable for dealing with large sets containing a large number of resources, as well as highly active resource sets that undergo continual change. The protocol is HTTP-based and follows RESTful principles.
Terminology
Resource Set - an enumerable, finite, collection of Resources
Resource - web resource identified by URI; the Resource Set members
Server - party playing the role of Resource Set provider
Client - party playing the role of consumer; interacts with a Server to
enumerate and track Resources in the Server’s Resource Set
Tracked Resource Set (TRS) - describes the set of Resources in a
Resource Set, expressed as a Base and a Change Log
Base - portion of a Tracked Resource Set representation that lists member
Resources
Change Log - portion of a Tracked Resource Set representation
detailing a series of Change Events
Change Event - describes the addition, removal, or state change of
a member Resource
Overview
The Server maintains a Resource Set. A Resource Set consists of a finite,
enumerable set of Resources. Each Resource is identified by a URI.
The Server will have its own criteria for determining the exact set
of member Resources at any point in time. However, clients need not
be aware of the Server’s criteria, and will instead discover a
Resource Set’s members by interacting with the Server using the
Tracked Resource Set protocol.
The
Server MUST provide an HTTP(S) URI corresponding to its Resource Set.
This is referred to as the Tracked Resource Set URI. (Mechanisms for
discovering Tracked Resource Set URIs is outside the scope of the
Tracked Resource Set specification.)
A
GET request sent to the Tracked Resource Set URI returns a
representation of the state of the Resource Set characterized in
terms of a Base and a Change Log: the Base provides a point-in-time
enumeration of the members of the Resource Set, and the Change Log
provides a time series of adjustments describing changes to members
of the Resource Set. When the Base is empty, the Change Log describes
a history of how the Resource Set has grown and evolved since its
inception. When the Change Log is empty, the Base is a simple
enumeration of the Resources in the Resource Set. This hybrid
base+delta form gives the Server flexibility to structure the
representation in ways that are most useful to its Clients.
The
Base portion of a Tracked Resource Set representation is an RDF
container where each member references a Resource that was in the
Resource Set at the time the Base was computed. The Change Log
portion is represented as an RDF collection, where the entries
correspond to Change Events arranged in reverse chronological order.
There must not be a gap between the Base portion and the Change Log
portion of a Tracked Resource Set representation; however, the Change
Log portion may contain earlier Change Event entries that would be
accounted for by the Base portion. A “cutoff” property of the
Base identifies the point in the Change Log at which processing of
Change Events can be cut off because older changes are already
covered by the Base portion.
Tracked Resource Set
An HTTP GET on a Tracked Resource Set URI returns a representation structured as follows (note: for exposition, the example snippets show the RDF information content using Turtle; the actual representation of these resources “on the wire” may vary):
# Resource: http://cm1.example.com/trackedResourceSet
@prefix trs: <http://open-services.net/ns/core/trs#> .
<http://cm1.example.com/trackedResourceSet>
a trs:TrackedResourceSet ;
trs:base <http://cm1.example.com/baseResources> ;
trs:changeLog [
a trs:ChangeLog ;
trs:changes ... .
] .
A Tracked Resource Set MUST provide references to the Base and Change Log using the trs:base and trs:changeLog predicates respectively.
A typical Client will periodically poll the Tracked Resource Set looking for recent Change Events. In order to cater to this usage, the Tracked Resource Set’s HTTP response MUST contain the triples for the referenced Change Log (i.e., via a Blank Node, or an inline named Resource). The Server SHOULD also support etags, caching, and conditional GETs for Tracked Resource Set resources and relegate the Base to separate resources.
Appendix A: Samples
(this section is informative)
See TrackedResourceSet 2.0 Samples
Appendix B: Resource Shapes
(this section is informative)
See TrackedResourceSet 2.0 Shapes
Appendix C: Notices and References
Contributors
Reporting Issues on the Specification
The working group participants who author and maintain this working draft specification, monitor a distribution list where issues or questions can be raised, see Core Mailing List
Also the issues found with this specification and their resolution can be found at @@@CoreV2Issues.
License and Intellectual Property
We make this specification available under the terms and conditions set forth in the site Terms of Use, IP Policy, and the Workgroup Participation Agreement for this Workgroup.
References
Appendix D: Changes
