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 additions to and removals from the set, and to track state changes to the resources in the set. The protocol does not assume that clients will dereference the resources, but they may. 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.


Introduction

An OSLC Tracked Resource Set (TRS) provides a mechanism for making a set of resources discoverable and for reporting ongoing changes affecting the set. This allows tools to expose a live feed of linked lifecycle data in a way that permits other tools to build, aggregate, and maintain live, searchable information based on that linked data.

TRS Clients can use Tracked Resource Sets to monitor or replicate some of the server’s resources, keeping up to date with changes. A single TRS Client could get information from many different TRS Servers and Tracked Resource Sets in order to aggregate information into a repository for more efficient federated access to the resource data, or for access using a different query language or protocol. The TRS protocol does not guarantee that a client can calculate a complete change history (audit log) for the tracked resources.

Still to do

Terminology

Terminology is based on OSLC Core Overview [[OSLCCore3]], W3C Linked Data Platform [[LDP]], W3C's Architecture of the World Wide Web [[WEBARCH]], and Hyper-text Transfer Protocol [[HTTP11]].

Tracked Resource Set (TRS)
Describes a resource that defines a finite, enumerable collection of Tracked Resources expressed as a Base and a Change Log.
Tracked Resource
A resource identified by URI that is a member of one or more Tracked Resource Sets.
Base
The portion of a Tracked Resource Set representation that lists the Tracked Resources at some specific point in time. Change Events in the Change Log are relative to the Base.
Change Log
The portion of a Tracked Resource Set representation detailing a series of Change Events for Tracked Resources.
Change Event
Describes the addition, removal, or state change of a Tracked Resource in a Tracked Resource Set.
TRS Patch
An extended Change Event in a Tracked Resource Set detailing a change to the resource’s RDF representation.
TRS Server
An application or application component that provides one or more Tracked Resource Sets.
Access Context
A grouping of resources with similar security requirements.
Access Context List
A resource describing a list of Access Contexts.

Sample resource representations are provided in text/turtle format [[TURTLE]].

The following common URI prefixes are used throughout this specification:

@prefix dcterms: <http://purl.org/dc/terms/>.
@prefix ex:      <http://example.org/>.
@prefix ldp:     <http://www.w3.org/ns/ldp#>.
@prefix oslc:    <http://open-services.net/ns/core#>.
@prefix rdf:     <http://www.w3.org/1999/02/22-rdf-syntax-ns#>.
@prefix rdfs:    <http://www.w3.org/2000/01/rdf-schema#>.
@prefix xsd:     <http://www.w3.org/2001/XMLSchema#>.
Commonly used URI prefixes.

Basic Concepts

A TRS Server maintains one or more Tracked Resource Sets. The TRS Server decides which particular resources are in a particular Tracked Resource Set at any moment; both the Tracked Resource Sets and the linked data contents of each Tracked Resource may vary over time. An HTTP GET request sent to the Tracked Resource Set URI returns a representation of the state of the Tracked Resource Set characterized in terms of a Base and a Change Log. The Base is a Linked Data Platform (LDP) Container providing a point-in-time enumeration of the Tracked Resource members of the Tracked Resource Set; The Change Log provides a (possibly empty) time-ordered series of adjustments describing changes to the Tracked Resources. When the Base is empty, the Change Log describes a history of how the Tracked Resource Set has grown and evolved since its inception. A TRS Server may periodically update the Base of a TRS and truncate the Change Log to avoid excessively large Change Logs. Clients may read the Base and poll the Change Log to derive and maintain an up to date picture of the state of all the Tracked Resources in a Tracked Resource Set.

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. TRS Clients use the Base to establish the resources to track, and the Change Log to address changes to those resources. TRS Clients are responsible for knowing what change events they have already processed in the Change Log, and should only process new change events.

Discovery

Discoverability is a convenience; an administrator can configure a Client with a particular Tracked Resource Set knowing just the URIs of the Server's Tracked Resource Set and designated Access Context List resource. An administrator can retrieve the Access Context List resource to discover the titles and URIs of the Access Contexts being used with that Server. Documentation for an TRS Server can describe its Tracked Resource Sets, including the URI of each of the Server's Tracked Resource Set resources and designated Access Context List resources.

A Server MAY provide multiple Tracked Resource Sets, and MAY make its Tracked Resource Sets discoverable.

The RDF trs:trackedResourceSet property can be used to declare the whereabouts of a Tracked Resource Set resource. The Tracked Resource Set resource is the object.

This allows the existence and location of a Tracked Resource Set resource to be declared with an RDF statement like the following (rendered here in Turtle):

@prefix trs: <http://open-services.net/ns/core/trs#> .
<> trs:trackedResourceSet <https://a.example.com/trs1> .
    

The RDF oslc_acc:accessContextList property declares the whereabouts of an Access Context List resource. The Access Context List resource is the object.

This allows the existence and location of an Access Context List resource to be declared with an RDF statement like the following (rendered here in Turtle):

@prefix oslc_acc: <http://open-services.net/ns/core/acc#> .
<> oslc_acc:accessContextList <https://a.example.com/acclist> .
    

Where such RDF statements might be found is outside the scope of this specification.

Resource Shapes for Tracked Resource Sets

Tracked Resource Set

Base

Change Log

Creation Event

Modification Event

Deletion Event

Resource Shapes for Access Contexts

Resource

AccessContext

AccessContextList

General Behavior>

Tracked Resources MUST have a RDF linked data representation, and SHOULD support GET requests conformant with [[OSLCCore2]] or [[OSLCCore3]].

The TRS Server SHOULD support ETags, caching, and conditional GETs for Tracked Resources; TBD: TRS Servers MAY support ETags, caching, and conditional GETs for Tracked Resource Sets and Base resources.

TRS servers MUST support Turtle (text/turtle) representations of the TRS, Base, Change Log and Change Event resources, and MAY support other representations, using standard HTTP content negotiation. If the client does not indicate a preference, text/turtle MUST be returned.

Change Logs and Change Events

A Server MUST refer to a given Tracked Resource using the exact same URI in the Base membership property and every Change Event (trs:changed reference) for that resource.

A Change Log represents a series of changes to the corresponding Tracked Resource Set over some period of time. The Change Log MUST contain a sufficient sequence of Change Events such that processing the Base and the Change Log gives a consistent and complete picture of the Tracked Resources at at the end of that period of time; the Change Log does not necessarily identify every change of internal state before or during that period of time.

A Server MAY batch up internal changes and add Change Events to the Change Log in a single transaction at some interval.

A Server MUST eventually report a resource modification event if a GET on that resource would return a semantically different response from previously.

A Server MAY report a modification event even in cases where there would be no significant difference in response.

When a resource is modified two or more times in rapid succession, a Server MAY elide such modifications by reporting only a single modification event in the Change Log.

When a resource is created and deleted in rapid succession, a Server MAY omit all Change Events for that resource.

Because of the highly dynamic nature of the Resource Set and the difficulty of enumerating an exact set of resources at a precise point in time, a Server MAY produce a Base that is only an approximation of the Tracked Resource Set membership. A Base might omit mention of a Resource that ought to have been included or include a Resource that ought to have been omitted. For each such inconsistency in the Base, the Server MUST at some point include a corrective Change Event in the Change Log more recent that the base cutoff event. The corrective Change Event corrects the picture for that Resource, allowing a client to compute the correct set of Tracked Resources.

A corrective Change Event might not appear in the Change Log that was retrieved when the client dereferenced the Tracked Resource Set URI; the client might only see a corrective Change Event when it processes the Change Log resource obtained by dereferencing the Tracked Resource Set URI on later occasions.

Similarly, a TRS Server MAY report unnecessary Change Events such as a creation event for a Resource that is already a member of the Resource Set, or a deletion or modification event for a Resource that is not a member of the Resource Set.

Clients should ignore these redundant events.

Change Log Segmentation

Often, the number of Change Events in the Change Log will grow to the point where it is not reasonable to contain all the Change Events in a single HTTP response. In this case, the most recent Change Events MUST be included in the Tracked Resource Set itself, and earlier events MAY be segmented into separate Change Log resources referenced from the trs:previous property. There can be any number of such Change Log segments, each one containing earlier and earlier events.

Just as the most recent Change Events MUST be included in the HTTP response for the Change Log in the Tracked Resource Set resource itself, TRS Servers MUST include the Change Events for each Change Log segment in the HTTP response for the Change Log segment.

This allows a Client to discover the most recent Change Events, and retrieve successively older Change Log resources until it encounters a Change Event that has already been processed (on a previous check). The protocol does not attach significance to where a Server breaks the Change Log into separate parts, i.e., the number of entries in a trs:ChangeLog is entirely up to the Server.

Paged Base

Often, the number of member Resources in the Base will grow to the point where it is not reasonable to contain all the Resources in a single HTTP response. In this case, the base member Resources may be segmented into separate resources. There can be any number of such base member Resource segments, each one containing a subset of all base member Resource segments

Truncating Change Logs, and Rebasing

A chain of Change Logs MAY continue all the way back to the inception of the Tracked Resource Set and contain Change Events for every change made since then. However, to avoid maintaining this ever growing list of Change Logs indefinitely, a Server MAY truncate the Change Log at a suitable point in the chain. This can be accomplished by deleting the oldest segments of the Change Log and/or by removing trs:previous links that reference them, and/or by removing obsolete Change Events from the end of the Change Log.

TRS Servers may therefore return HTTP status code 404 (Not found) when navigating the "previous" reference from a final or stale Change Log segment; clients should interpret this as indicating that they have reached the end of the change log.

To ensure that a new Client can always get started, the Change Log MUST contain the base cutoff event of the corresponding Base, and all Change Events more recent than it. Thus the Server is only allowed to truncate Change Events older than the base cutoff event. When the Base has no base cutoff event (i.e., the Base enumerates the Resource Set at the start of time), the Change Log MUST contain all Change Events back to the start of time; i.e., no truncation is allowed.

While servers must preserve the cutoff event in the truncated change log, the same is not true of any earlier events that a client might have already processed. For this reason, a client should not assume that it will find a change event that it has previously processed: that change event might have been truncated.

To allow truncation of long Change Logs, a TRS Server MAY calculate a new base set at any time, with a new cutoff event in the Change Log. When doing this, TRS Servers SHOULD take care to handle clients that are currently processing the older Base and Change Log:

TRS Patch

Editor: Why is this non-normative? (img)

Editor: need some words here motivating the need for TRS Patch. Version 432 motivated using Indexable provider, which i think we agreed was not appropriate. (img)

For a Resource that changes frequently, a typical Client may retrieve the same Resource over and over again. When the representation of the Resource is large and the differences between adjacent representations can be described compactly, including additional information in the trs:Modification Change Event can allow the Client to determine the Resource’s current representation and thereby avoid having to retrieve the Resource.

Similiarly, in versioned worlds each change to a versioned resource may result in the creation of a new Resource representing an immutable version of the resource. The typical Client retrieves each such Resource as it is created. The state of the new Resource is often quite similar to the state of a Resource corresponding to a previous version. When the state of one Resource is similar to that of another Resource and the differences between the two can be described compactly, including additional information in the trs:Creation Change Event can allow the Client to determine the new Resource’s resultant state from the potentially-known state of a previously-retrieved Resource and thereby avoid having to retrieve the new Resource.

This section describes an extension to Change Events allowing them to carry detailed information about modifications to resources with an RDF representation.

The trspatch:createdFrom property, when present, identifies the antecedent resource. If omitted, the antecedent resource is the resource referenced in the trs:changed property. The antecedent resource is the one that supplies the “before” state.

The trspatch:rdfPatch property, when present, describes a patch applied to the antecedent resource’s representation. The result of applying the patch describes the representation of the resource referenced in the trs:changed property. The trspatch:rdfPatch property is used with trs:Modification and trs:Creation Change Events; it is not meaningful for trs:Deletion Change Events. The value of the trspatch:rdfPatch property is an LD Patch. The trspatch:rdfPatch property is meaningful only for resources with RDF representations.

The trspatch:beforeETag property, when present, gives the initial HTTP entity tag of the antecedent resource. This is the entity-tag value that would be returned in the HTTP ETag response header if the antecedent resource is retrieved immediately before the change.

The trspatch:afterETag property, when present, gives the final HTTP entity tag of the resource referenced in the trs:changed property. For a trs:Modification (trs:Creation) Change Event, this is the entity tag of the resource immediately after it was modified (created, respectively). This is the entity-tag value that would be returned in the HTTP ETag response header if the resource is retrieved immediately after the change.

Note that these properties are can be used with any resource having both an RDF representation and an entity tag. This includes all Linked Data Platform RDF Source (LDP-RS) resources, which have both.

Note also that the trspatch:beforeETag and trspatch:afterETag properties are meaningful for any kind of resource, not just ones with RDF representations.

LD Patch

Editor: the LD Patch spec has moved up to working group note 28 july 2015. (img)

Editor: the meaning of "temporarily" below is not clear. (img)

The Linked Data Patch (LD Patch) specification is currently under development by the W3C LDP WG. Our intention is to adopt the syntax and semantics of LD patches from the LD Patch specification rather than specifying our own. However, the LD Patch effort is only just beginning, and the First Public Working Draft was published on 18 September 2014.

In an effort to insulate Servers from changes to the LD Patch specification while it is being refined, this document proposes that Servers temporarily limit themselves to generating LD patches in a limited subset which we call Core format. Core format is extremely simple (no prefixes, no variables, and no Binds) but perfectly adequate for describing patches to graphs not involving blank nodes. (Core format is based on an early (and unofficial) precursor called RDF Patch.)

A Core format patch consists of a sequence of rows. A row with ‘A’ (or ‘D’) in the first column describes the addition (deletion) of one RDF triple from the resource’s RDF data graph. The subject, predicate, and object of the triples are described in columns 2-4 in the form of absolute URI references enclosed between ‘<’ and ‘>’. Each row is delimited by a ‘.’ and may have white space between the various terms in a row, including newlines.

Example of a Core format patch that deletes one RDF triple (subject http://example.com/bob, predicate http://xmlns.com/foaf/0.1/knows, object https://example.com/alice) and adds another an RDF triple (subject https://example.com/fred, predicate http://http://xmlns.com/foaf/0.1/member, object http://example.com/old-timers):

  D <http://example.com/bob> <http://xmlns.com/foaf/0.1/knows> <http://example.com/alice> .
  A <http://example.com/fred> <http://http://xmlns.com/foaf/0.1/member> <http://example.com/old-timers> .
         

TRS Patch Example 1

Turtle representation for the resource https://a.example.com/config/a1 in state 1. Assume that when the resource is retrieved in this state, the entity tag 15687ds9gha6s7 is returned in the ETag response header:

  # The following is the representation of
  # https://a.example.com/config/a1
  # in the state with entity tag 15687ds9gha6s7
  @prefix dcterms: <http://purl.org/dc/terms/>.
  @prefix ldp: <http://www.w3.org/ns/ldp#>.
  <https://a.example.com/config/a1>
     a ldp:BasicContainer;
     dcterms:title "Component configuration A1";
     ldp:member <https://a.example.com/version/s/143>;
     ldp:member <https://a.example.com/version/r/577>;
     ldp:member <https://a.example.com/version/t/033>.
       

Turtle representation for the same resource https://a.example.com/config/a1 in state 2. Assume that when the resource is retrieved in this state, the entity tag 285d4h2ffgddd9 is returned in the ETag response header:

  # The following is the representation of
  # https://a.example.com/config/a1
  # in the state with entity tag 285d4h2ffgddd9
  @prefix dcterms: <http://purl.org/dc/terms/>.
  @prefix ldp: <http://www.w3.org/ns/ldp#>.
  <https://a.example.com/config/a1>
     a ldp:BasicContainer;
     dcterms:title "Component configuration A1";
     ldp:member <https://a.example.com/version/s/143>;
     ldp:member <https://a.example.com/version/r/578>;
     ldp:member <https://a.example.com/version/t/033>.
       

Turtle representation for a Change Event describing resource https://a.example.com/config/a1 changing from state 1 to state 2:

  # The following is the representation of a change event
  @prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
  @prefix trs: <http://open-services.net/ns/core/trs#>.
  @prefix trspatch: <http://open-services.net/ns/core/trspatch#>.
  <urn:example:6e8bc430:a.example.com:2014-04-28T17:39:32.000Z:102>
     a trs:Modification;
     trs:changed <https://a.example.com/config/a1>;
     trs:order "102"^^xsd:integer;
     trspatch:beforeEtag "15687ds9gha6s7";
     trspatch:afterEtag "285d4h2ffgddd9";
     trspatch:rdfPatch
       """
        D <https://a.example.com/config/a1> <http://www.w3.org/ns/ldp#member> <https://a.example.com/version/r/577> .
        A <https://a.example.com/config/a1> <http://www.w3.org/ns/ldp#member> <https://a.example.com/version/r/578> .
       """.
       

TRS Patch Example 2

Turtle representation for the resource https://a.example.com/sw-movie/versions/1. Assume that when the resource is retrieved in this state, the entity tag 783xhaty95 is returned in the ETag response header:

  # The following is the representation of
  # https://a.example.com/sw-movie/versions/1
  # in the state with entity tag 783xhaty95
  @prefix dcterms: <http://purl.org/dc/terms/>.
  @prefix ldp: <http://www.w3.org/ns/ldp#>.
  <https://a.example.com/sw-movie/versions/1>
     dcterms:isVersionOf <https://a.example.com/sw-movie> .
  <https://a.example.com/sw-movie>
     a ldp:Resource;
     dcterms:title "Star Wars".
       

Turtle representation for the resource https://a.example.com/sw-movie/versions/2. Assume that when the resource is retrieved in this state, the entity tag 212gyysxx8 is returned in the ETag response header:

  # The following is the representation of
  # https://a.example.com/sw-movie/versions/2
  # in the state with entity tag 212gyysxx8
  @prefix dcterms: <http://purl.org/dc/terms/>.
  @prefix ldp: <http://www.w3.org/ns/ldp#>.
  <https://a.example.com/sw-movie/versions/2>
     dcterms:isVersionOf <https://a.example.com/sw-movie> .
  <https://a.example.com/sw-movie>
     a ldp:Resource;
     dcterms:title "Star Wars: Episode IV - A New Hope".
       

Turtle representation for a Change Event describing the creation of the resource https://a.example.com/sw-movie/versions/2. The TRS patch describes the state of this new resource in terms of the state of resource https://a.example.com/sw-movie/versions/1:

  # The following is the representation of a change event
  @prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
  @prefix trs: <http://open-services.net/ns/core/trs#>.
  @prefix trspatch: <http://open-services.net/ns/core/trspatch#>.
  <urn:example:6e8bc430:a.example.com:2014-11-20T13:08:00.000Z:102>
     a trs:Creation;
     trs:changed <https://a.example.com/sw-movie/version/2>;
     trs:order "192"^^xsd:integer;
     trspatch:createdFrom <https://a.example.com/sw-movie/version/1>;
     trspatch:beforeEtag "783xhaty95";
     trspatch:afterEtag "212gyysxx8";
     trspatch:rdfPatch
       """
        D <https://a.example.com/sw-movie/versions/1>  <http://purl.org/dc/terms/isVersionOf> <https://a.example.com/sw-movie> .
        A <https://a.example.com/sw-movie/versions/2>  <http://purl.org/dc/terms/isVersionOf> <https://a.example.com/sw-movie> .
        D <https://a.example.com/sw-movie> <http://purl.org/dc/terms/title> \"Star Wars\".
        A <https://a.example.com/sw-movie> <http://purl.org/dc/terms/title> \"Star Wars: Episode IV - A New Hope\".
       """.
       

TRS Examples

In this example of a change log, time stamps are used to generate unique URNs for the Change Event URIs; other ways of generating a unique URI are also possible.

Note that the actual time of change is not included in a Change Event. Only a sequence number, representing the "sequence in time" of each change is provided.

# Resource: http://cm1.example.com/trackedResourceSet
@prefix trs: <http://open-services.net/ns/core/trs#> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

<http://cm1.example.com/trackedResourceSet>
  a trs:TrackedResourceSet ;
  trs:base <http://cm1.example.com/baseResources/> ;
  trs:changeLog [
    a trs:ChangeLog ;
    trs:change <urn:example:6e8bc430:cm1.example.com:2010-10-27T17:39:33.000Z:103> ;
    trs:change <urn:example:6e8bc430:cm1.example.com:2010-10-27T17:39:32.000Z:102> ;
    trs:change <urn:example:6e8bc430:cm1.example.com:2010-10-27T17:39:31.000Z:101> .
  ] .

<urn:example:6e8bc430:cm1.example.com:2010-10-27T17:39:33.000Z:103>
  a trs:Creation ;
  trs:changed <http://cm1.example.com/bugs/23> ;
  trs:order "103"^^xsd:integer .

<urn:example:6e8bc430:cm1.example.com:2010-10-27T17:39:32.000Z:102>
  a trs:Modification ;
  trs:changed <http://cm1.example.com/bugs/22> ;
  trs:order "102"^^xsd:integer .

<urn:example:6e8bc430:cm1.example.com:2010-10-27T17:39:31.000Z:101>
  a trs:Deletion ;
  trs:changed <http://cm1.example.com/bugs/21> ;
  trs:order "101"^^xsd:integer .
  

Access Context

This entire section has not yet been edited for brevity and to remove duplication.

A Client that provides services based on resources fetched from a Tracked Resource Set Server, may want to control access to those Resources. It is simple enough for a Client to allow some users to access these copies, while denying access to other users.

In order to make it feasible for Clients to offer access control that reflects the access control on the Tracked Resource Set Server, a Server can define one or more Access Contexts and associate each of its Resources with an Access Context. When configuring a Client to work with a particular Server, the administrator can query the Server for a list of relevant Access Contexts. This allows the administrator to configure access control at the level of Access Contexts within a Tracked Resource Set.

For its part, the Server associates each of its Resources with an Access Context, asserted in the representation of each Resource. This lets the Client connect access control rules expressed in terms of Access Contexts with the resource representations copied from the Server. Adding a resource to an Access Context, or removing one from it, changes the RDF representation of the resource. Like other changes affecting the RDF representation of the resource, this change is reported as a Change Event in the Server's Tracked Resource Set. This supports Clients working with Servers whose resources' Access Contexts vary over time.

Editor: related to https://issues.oasis-open.org/browse/OSLCCORE-82. (img)

This set of Access Contexts within a Server can also change over time. Adding a new Access Context Client will generally require an administrator to reconfigure the Client against that Server.

Associations between Resources and Access Contexts

The RDF oslc_acc:accessContext property is used to indicate that a resource belongs to an Access Context. The resource is the subject; the Access Context is the object.

For example, the RDF statement (in Turtle):

@prefix oslc_acc: <http://open-services.net/ns/core/acc#> .
<https://a.example.com/defect/2314> oslc_acc:accessContext <https://a.example.com/acclist#alpha> .
  

declares the resource https://a.example.com/defect/2314 to be in the Access Context https://a.example.com/acclist#alpha.

A linked data resource that is deemed (by the Server) to be in an Access Context MUST use the oslc_acc:accessContext predicate in its RDF representation to assert a relation between the linked data resource (subject) and an Access Context.

For example, the above RDF statement embedded in the representation of resource https://a.example.com/defect/2314 asserts that this resource is in Access Context https://a.example.com/acclist#alpha. The RDF representation of a linked data resource in several Access Contexts will have multiple such RDF statements; for a linked data resource not in any Access Context, there will be none.

Access Context List Resource

If an Server uses Access Contexts within its resources, the Server MUST provide an Access Context List resource. If a Server has more than one Tracked Resource Set, it MUST designate an Access Context List resource for each Tracked Resource Set; several Tracked Resource Sets MAY share the same Access Context List resource.

The Access Context List resource is intended to be accessed by administrator for the purpose of configuring a TRS Client that is working with linked data obtained from that Server's Tracked Resource Set. The representation of the Access Context resource is itself linked data.

The Server MUST support the use of the HTTP GET method for the Access Context List resource. The Server SHOULD require the use of TLS when making requests to the Access Context List resource. The Server SHOULD require authentication for the Access Context List resource, and SHOULD allow access only to users with administrative privileges. The Server's response MUST support the JSON-LD media type (application/ld+json), and MAY support other linked data representations. The response SHOULD include an ETag header.

A client uses an HTTP GET request to retrieve a representation of the Access Context List resource, specifying JSON-LD as an acceptable format. For example:

GET https://a.example.com/acclist HTTP/1.1
Accept: application/ld+json
Authorization: Basic [missing - admin user credentials]

The response MUST be a JSON-LD format string with a node for the Access Context List along with a node for each Access Context. The response SHOULD use the simple @graph form with a default graph as shown in the example below. The response SHOULD use the @context value shown below (i.e., as a boilerplate header), and SHOULD NOT use other advanced JSON-LD features, since these can make the response more difficult to understand for human readers who only know JSON, and more difficult to processed programmatically by scripts without the benefit of a full JSON-LD library. The node’s type property gives the type of the node - either oslc_acc:AccessContextList or oslc_acc:AccessContext; the node’s id property gives the Access Context URI; the title and description properties give the title and description, respectively.

Example of a response:

HTTP/1.1 200 OK
Content-Type: application/ld+json;charset=UTF-8
ETag: 68djsgg82
{
  "@context": {
    "acc": "http://open-services.net/ns/core/acc#",
    "id": "@id",
    "type": "@type",
    "title": "http://purl.org/dc/terms/title",
    "description": "http://purl.org/dc/terms/description"
  },
  "@graph": [{
     "id": "https://a.example.com/acclist",
     "type": "oslc_acc:AccessContextList"
    }, {
     "id": "https://a.example.com/acclist#alpha",
     "type": "oslc_acc:AccessContext",
     "title": "Alpha",
     "description": "Resources for Alpha project"
    }, {
     "id": "https://a.example.com/acclist#beta",
     "type": "oslc_acc:AccessContext",
     "title": "Beta",
     "description": "Resources for Beta project"
  }]
}

URI Stability

Access Context List and Access Context resources should have stable URIs. When Access Context URIs are based on an Access Context List URI with the addition of local id in the fragment (e.g., the Access Context URI https://a.example.com/acclist#alpha is based on the Access Context List URI https://a.example.com/acclist), the Server should ensure that each Access Context has a stable local id that is unique within the Access Context List.

Access Context Examples

RDF Vocabularies

RDF Vocabulary for Tracked Resource Set

RDF Vocabulary for Access Context

Acknowledgements

The following individuals have participated in the creation of this specification and are gratefully acknowledged:

Participants:

James Amsden, IBM (Chair, Editor)
Frank Budinsky, IBM
Nick Crossley, IBM
Vivek Garg, IBM
Ian Green, IBM
Arthur Ryman, IBM
Steve Speicher, IBM

Change History

Revision Date Editor Changes Made
03 10/26/2017 Nick Crossley Moved to TRS subdirectory. Removed all client guidance and most other non-normative text.
02 03/17/2017 Ian Green removed references to indexed linked data provider/consumer. use client/server rather than consumer/provider. added some comments to the editor for identified issues.
01 07/15/2016 Jim Amsden Editor's draft created.