Notices

Copyright © OASIS Open 2021. All Rights Reserved.

All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.

This specification is published under the Attribution 4.0 International (CC BY 4.0). Portions of this specification are also provided under the Apache License 2.0.

All contributions made to this project have been made under the OASIS Contributor License Agreement (CLA).

For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Open Projects IPR Statements page.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Open Project or OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Project Specification or OASIS Standard, to notify the OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.

OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Open Project that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.

OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Open Project Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.

The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.

Table of Contents

1. Introduction

This section is non-normative.

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 monitor the tracked resources, aggregate information from multiple sets of tracked resources, and maintain live, searchable information based on that linked data.

1.1 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 point in time.
Change Log
The portion of a Tracked Resource Set representation detailing a series of Change Events for Tracked Resources, where those changes are relative to the Base.
Change Event
Identifies an addition, removal, or state change of a Tracked Resource in a Tracked Resource Set. These events are represented using the three RDF classes trs:Creation, trs:Modification, and trs:Deletion - but note that the distinction between creation and modification is historical and servers are not required to observe any such distinction.
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.

1.2 Typographical Conventions and Use of RFC Terms

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this specification are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

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#>.

2. Basic Concepts

This section is non-normative.

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 can vary over time. A Tracked Resource Set is represented 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) 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 can periodically update the Base of a TRS and truncate the Change Log to avoid excessively large Change Logs. Clients can 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 can 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 this change and older changes are already included in the Base. TRS Clients use the Base to establish an initial set of resources to track, and the Change Log to address changes to that set, and changes to the those resources.

3. Discovery

Note: Discovery is a convenience

Discoverability is a convenience; an administrator can configure a Client with a particular Tracked Resource Set knowing just the URI of the Server's Tracked Resource Set. Documentation for an TRS Server can describe its Tracked Resource Sets, including the URI of each of the Server's Tracked Resource Set resources.

A Server MAY provide multiple Tracked Resource Sets, and MAY make its Tracked Resource Sets discoverable. [CC-1]

A trs:trackedResourceSet property MAY be used to declare the whereabouts of a Tracked Resource Set resource; the value of such a property MUST be the URI of a Tracked Resource Set. [CC-2]

This allows the existence and location of a Tracked Resource Set resource to be declared with an RDF statement like the following:

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

Where such RDF statements might be found is outside the scope of this specification. See also [OSLCCore3], section "Well-known URI Bootstrapping".

4. General Behavior

The TRS Server MUST support GET requests conformant with [OSLCCore2] or [OSLCCore3] for Tracked Resource Sets, Base resources, and Change Logs. [CC-3]

The RDF returned for Tracked Resource Sets, Base resources, Change Logs, MUST conform to the shapes and constraints in the following section. [CC-4]

The TRS Server SHOULD support ETags, caching, and conditional GETs for those resources. [CC-5]

Servers providing the tracked resources referenced by a Tracked Resource Set MUST also support GET requests conformant with [OSLCCore2] or [OSLCCore3] and SHOULD support ETags, caching, and conditional GETs for those resources. [CC-6]

5. Resource Shapes for Tracked Resource Sets

5.1 Tracked Resource Set

TrackedResourceSet Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
rdf:type One-or-many unspecified Resource Reference rdfs:Class A resource type URI. A tracked resource set MUST have at least the resource type trs:TrackedResourceSet [CC-7].
trs:base Exactly-one true Resource Reference trs:Base An enumeration of the resources in the Tracked Resource Set. This SHOULD be a reference to a separate resource, not returned inline with the Tracked Resource Set itself [CC-8].
trs:changeLog Exactly-one true AnyResource Inline trs:ChangeLog A Change Log providing an ordered series of incremental adjustments to the Tracked Resource Set. The Tracked Resource Set representation MUST contain the triples for the referenced Change Log (i.e., via a blank node, or an inline named resource), including the Change Events for the first page of changes [CC-9].

5.2 TRS Base

Base Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
ldp:hasMemberRelation Exactly-one true Resource Reference Unspecified The membership predicate for this Base container.
ldp:member Zero-or-many true Resource Reference Unspecified A Tracked Resource that is a member of the Tracked Resource Set. ldp:member is the preferred predicate, but the actual predicate is indicated by ldp:hasMemberRelation.
rdf:type Zero-or-many unspecified Resource Reference rdfs:Class A resource type URI. Clients can infer a resource type of trs:Base, or its superclass ldp:DirectContainer.
trs:cutoffEvent Exactly-one true AnyResource Either trs:Deletion, trs:Modification, trs:Creation The URI of an entry in the Change Log at and after which all changes have already been included in the Base.

5.3 TRS Change Log

ChangeLog Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
trs:change Zero-or-many true Resource Inline trs:Deletion, trs:Modification, trs:Creation An inline resource describing a change to a Tracked Resource. Change Events MUST have URIs (i.e., they cannot be blank nodes) to allow clients to recognize entries they have seen before. [CC-10] The URI is used to identify an event; it need not be dereferenceable, and MAY be a URN. [CC-11] The URI of a Change Event MUST be guaranteed unique, even if order numbers get reused in the wake of a Server rollback [CC-12].
trs:previous Zero-or-one true AnyResource Either trs:ChangeLog The continuation of the Change Log, containing the next group of chronologically earlier Change Events.

5.4 TRS Creation or Modification Event

Modification Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
trs:changed Exactly-one true Resource Reference Unspecified The resource that has been created, modified, or deleted.
trs:order Exactly-one true integer N/A Unspecified A non-negative integer number indicating the sequence in time of the Change Event. There MAY be gaps in the sequence [CC-13], but a more recent Change Event MUST have a larger number than any preceding Change Event [CC-14].
trspatch:afterETag Zero-or-one true string N/A Unspecified This property, when present, gives the final HTTP entity tag of the resource referenced in the trs:changed property - the entity-tag value that would have been returned in the HTTP ETag response header if the resource had been retrieved immediately after the change. Clients can use this as the expected trspatch:beforeETag value in a chain of patch events for a tracked resource.
trspatch:beforeETag Zero-or-one true string N/A Unspecified This property, when present, gives the initial HTTP entity tag of the antecedent resource for a patch event. This is the entity-tag value that would be returned in the HTTP ETag response header if the antecedent resource had been retrieved immediately before the change. If this property is missing, or if the entity-tag value does not match the current state of the antecedent resource, the patch should be ignored and the event treated as a normal modification event.
trspatch:createdFrom Zero-or-one true Resource Reference Unspecified This property MUST NOT be present unless the trspatch:rdfPatch property is also present [CC-15], indicating this change event is annotated with a patch. This property, when present, identifies the antecedent resource to be used to define the "before" state of the patch. If omitted, the antecedent resource is the resource referenced in the trs:changed property.
trspatch:rdfPatch Zero-or-one true string N/A Unspecified This property, when present, describes a patch to be applied to the antecedent resource’s RDF representation. A patch cannot describe a change to the non-RDF contents of a resource. The result of applying the patch describes the representation of the resource referenced in the trs:changed property immediately after this change event. This property is used with trs:Modification and trs:Creation Change Events; it is not meaningful for trs:Deletion Change Events. The format of the patch property is defined at TRS Patch.

5.5 TRS Deletion Event

Deletion Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
trs:changed Exactly-one true Resource Reference Unspecified The resource that has been created, modified, or deleted.
trs:order Exactly-one true integer N/A Unspecified A non-negative integer number indicating the sequence in time of the Change Event. There MAY be gaps in the sequence [CC-16], but a more recent Change Event MUST have a larger number than any preceding Change Event [CC-17].

6. Cutoff Event

The cutoff event in the Base marks the point in the Change Log at which this change and all earlier changes have already been accounted for in the Base.

If the cutoff property is missing, or if it has the value rdf:nil, the Base enumerates the (possibly empty) Resource Set at the inception of the Tracked Resource Set, and the Change Log MUST list all changes since that inception. [CC-18]

Otherwise, the identified Change Event MUST be in the Change Log - that is, there MUST NOT be a discontinuity between the Base portion and the Change Log portion of a Tracked Resource Set. [CC-19]

Conversely, the Change Log MAY contain earlier Change Event entries that have been accounted for in the Base. [CC-20]

7. Change Logs and Creation or Modification 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. [CC-21]

A Change Log represents a series of changes to the corresponding Tracked Resource Set over some period of time. For any given tracked resource, 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 the end of that period of time. [CC-22]

The ordering of Change Log events is meaningful for changes to any specific resource, but there is no meaning to the ordering of change log events for different resources. That is, a change event for resource R1 at time t MAY have an order number that is greater than a change to an unrelated resource R2 at time t+1 [CC-23].

The Change Log does not necessarily identify every change of state before or during that period of time, as further explained in the following paragraphs.

A Server MAY batch up changes and add a batch of consolidated Change Events to the Change Log at some interval. [CC-24]

A Server MUST eventually report a change event for a tracked resource if at time t0, a tracked resource is added to the Tracked Resource Set, deleted from the Tracked Resource Set, or the state of the Tracked Resource Set is modified, such that a GET on that resource would now return a semantically different response from a GET request issued just before t0. [CC-25]

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

A Server MAY report a modification event even in cases where there would be no significant difference in response. [CC-27] This could happen because a resource was modified and then that change was reverted in a second modification; the first modification could be elided in the change log.

There is no difference between change events with RDF type trs:Creation and trs:Modification; the two types exist for historical reasons. When a new resource is modified or added to a tracked resource set, a Server MAY issue a modification event or a creation event [CC-28]; as described earlier, the server MUST eventually issue at least one such event [CC-29].

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

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 [CC-31]. 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 than the base cutoff event [CC-32], allowing a client to compute the correct set of Tracked Resources.

A Server MAY issue a deletion event for a resource that is not a member of the Tracked Resource Set. This includes issuing multiple deletion events for (what was) a member of the Tracked Resource Set. This might happen when the base is being recalculated, and the change log slightly overlaps the base, or as part of the corrective set of change events described in the previous paragraph. [CC-33]

Note

From the above sections, one can infer that the consistency and completeness of the change log with respect to the data on a TRS Server is only possible (but is not guaranteed) after reading the entire Base and Change Log. A client cannot skip the initial reading of the base, nor partially consume a Change Log, and then expect consistency with some earlier point-in-time of the server’s data. Even having read the entire base plus change log, a client may still not have information on the most recent changes to the tracked resources; nor is there any guarantee that the result represents an exact state of the server's data at any specific point in time.

8. Change Log Segmentation

The number of Change Events in the Change Log can grow to a point where it is not reasonable to contain all the Change Events in a single HTTP response. In this case, the most recent Change Event resources MUST be included in the RDF representation of the Tracked Resource Set itself [CC-34], and earlier events MAY be segmented into separate Change Log resources referenced from the trs:previous property [CC-35].

There can be any number of such Change Log segments. The events in a Change Log segment MUST all have order numbers higher than any events in any subsequent Change Log segments. [CC-36]

Just as the most recent Change Events MUST be included inline in the HTTP response for the Change Log in the Tracked Resource Set resource itself, TRS Servers MUST include the Change Event resources for each Change Log segment inline in the RDF representation of the HTTP response for the Change Log segment. [CC-37]

Note

The above paragraphs allows a Client to discover the most recent Change Events, retrieve successively older Change Log resources until it encounters a Change Event that has already been processed (on a previous check), and for it to be guaranteed that a segment cannot contain Change Events with a higher order number (representing a more recent change) than the events already encountered on earlier segments in the chain. The protocol does not attach significance to where a Server breaks the Change Log into separate segments, i.e., the number of entries in a trs:ChangeLog is entirely up to the Server.

9. Base Segmentation

The number of Tracked Resources in the Base could be such that it is not reasonable to list them all in a single HTTP response. In this case, the Base MAY be segmented into separate resources; there can be any number of such Base segments, each one listing a subset of all Tracked Resources [CC-38].

Base segmentation MUST be accomplished using the mechanisms described in the "Resource Paging" section of [OSLCCore3]. [CC-39]

A Server MAY include a Tracked Resource in more than one base segment. [CC-40]

10. Updating Change Log segments, Truncating Change Logs, and Replacing the Base

A Server MAY add new change events at the start of the initial set of events returned inline with the Tracked Resource itself [CC-41] (in fact, this is the only way in which new change events are added to the Change Log).

A Server MUST NOT move a change event from one segment of a segmented change log to an earlier segment in the chain, one with more recent change events. [CC-42]

A Server MAY move a change event from one segment of a segmented change log to an later segment in the chain, one with older change events. [CC-43]

Note

The above implies that a client could see the same change event more than once. Since each change event has a unique URI, clients can detect such repetition, and ignore duplicate events.

A Server MAY remove a change event from the change log [CC-44], perhaps because that change is now reflected in an updated base with a new cutoff event.

A chain of Change Log segments MAY continue all the way back to the inception of the Tracked Resource Set and contain Change Events for every change made since then. [CC-45] 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 [CC-46]. 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.

Note

TRS Servers can 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 [CC-47], 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 inception of the Tracked Resource Set), the Change Log MUST contain all Change Events back to the inception of the Tracked Resource Set; i.e., no truncation is allowed [CC-48].

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 [CC-49]. When doing this, In order to handle clients that are currently processing the older Base and Change Log [CC-50]:

11. Timescales and event frequency

This section is non-normative.

In order to provide adequate response to client requests, a TRS server needs to allow those clients sufficient time to read the base, the change log, and process the set of tracked resources. However, the data volumes and timescales involved in TRS processing are likely to vary between servers for different applications. A server representing Amazon transactions might have many events per second, while a server representing exhibits at a museum might have a few events per month. The cost of processing a single event is also likely to vary between applications; reading a new or modified resource with 5 RDF properties will take less time than reading one with 5,000 properties.

For these reasons, the TRS specification does not impose specific constraints over the length of time for which a TRS base needs to remain readable, nor what the degree of overlap should be between a base and a corresponding change log. A server implementing TRS needs to consider, and should document, the quality of service it will provide in terms of the size of pages in the base or change log, how long base pages are kept, how long change events are kept, and the minimum period for which change events behind the latest base cutoff are kept.

12. TRS Examples

This section is non-normative.

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.

Example 2: Change Log
# 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 .

13. TRS Patch

This section describes an mechanism allowing Change Events to carry detailed information about modifications to resources with an inline RDF representation, avoiding the need for a client to issue a GET request for a new or modified resource. This allows more efficient handling of frequent small changes to a large resources and creation of new versions of existing resources. The patch format is a subset of [RDFPatch].

A patch event MUST have type trs:Modification or trs:Creation Change Events; it is not meaningful for trs:Deletion Change Events. [CC-53]

13.1 TRS Patch

A TRS patch MUST consist of a sequence of directives delimited by a ‘.’ [CC-54]

Each directive of a patch MUST consist of four terms. [CC-55]

Each term in a directive MAY be separated with white space, including newlines. [CC-56]

The first term of a directive MUST be the ASCII character 'A' (U+0041) or the ASCII character 'D' (U+0044)". [CC-57]

A directive with the first term being the ASCII character ‘A’ (U+0041) describes the addition of one RDF triple to the resource’s RDF data graph. The subject, predicate, and object of the triple to be added are given in terms 2 to 4 of the directive.

A directive with the first term being the ASCII character ‘D’ (U+0044) describes the deletion of one RDF triple from the resource’s RDF data graph. The subject, predicate, and object of the triple to be added are given in terms 2 to 4 of the directive.

The subject and predicate (terms 2 and 3) in a directive MUST be in the form of absolute URI references enclosed between ‘<’ and ‘>’ [CC-58]

The object in a directive (term 4) MUST be either an absolute URI reference enclosed between ‘<’ and ‘>’, or a literal in [Turtle] syntax. [CC-59]

The order of patch directives is significant - changes MUST be applied in the order given. [CC-60]

Example of a TRS 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 RDF triple (subject https://example.com/fred, predicate http://http://xmlns.com/foaf/0.1/member, object http://example.com/old-timers):

Example 3: Patch to delete a triple
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> .

13.2 TRS Patch Example

This section is non-normative.

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:

Example 4: sw-movie Version 1
# 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:

Example 5: sw-movie Version 2
# 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:

Example 6: Create sw-movie version 2 from version 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".
     """.

14. Conformance

This specification is based on [OSLCCore3]. OSLC Tracked Resource Set Servers servers MUST be compliant with the Core specification, MUST follow all the mandatory requirements in the normative sections of each part of this specification, and SHOULD follow all the guidelines and recommendations in both these specifications. [CC-61]

Clause Number Requirement
CC-1 A Server MAY provide multiple Tracked Resource Sets, and MAY make its Tracked Resource Sets discoverable.
CC-2 A trs:trackedResourceSet property MAY be used to declare the whereabouts of a Tracked Resource Set resource; the value of such a property MUST be the URI of a Tracked Resource Set.
CC-3 The TRS Server MUST support GET requests conformant with [OSLCCore2] or [OSLCCore3] for Tracked Resource Sets, Base resources, and Change Logs.
CC-4 The RDF returned for Tracked Resource Sets, Base resources, Change Logs, MUST conform to the shapes and constraints in the following section.
CC-5 The TRS Server SHOULD support ETags, caching, and conditional GETs for those resources.
CC-6 Servers providing the tracked resources referenced by a Tracked Resource Set MUST also support GET requests conformant with [OSLCCore2] or [OSLCCore3] and SHOULD support ETags, caching, and conditional GETs for those resources.
CC-7 A tracked resource set MUST have at least the resource type trs:TrackedResourceSet
CC-8 This SHOULD be a reference to a separate resource, not returned inline with the Tracked Resource Set itself
CC-9 The Tracked Resource Set representation MUST contain the triples for the referenced Change Log (i.e., via a blank node, or an inline named resource), including the Change Events for the first page of changes
CC-10 Change Events MUST have URIs (i.e., they cannot be blank nodes) to allow clients to recognize entries they have seen before.
CC-11 The URI is used to identify an event; it need not be dereferenceable, and MAY be a URN.
CC-12 The URI of a Change Event MUST be guaranteed unique, even if order numbers get reused in the wake of a Server rollback
CC-13 There MAY be gaps in the sequence
CC-14 a more recent Change Event MUST have a larger number than any preceding Change Event
CC-15 This property MUST NOT be present unless the trspatch:rdfPatch property is also present
CC-16 There MAY be gaps in the sequence
CC-17 a more recent Change Event MUST have a larger number than any preceding Change Event
CC-18 If the cutoff property is missing, or if it has the value rdf:nil, the Base enumerates the (possibly empty) Resource Set at the inception of the Tracked Resource Set, and the Change Log MUST list all changes since that inception.
CC-19 Otherwise, the identified Change Event MUST be in the Change Log - that is, there MUST NOT be a discontinuity between the Base portion and the Change Log portion of a Tracked Resource Set.
CC-20 Conversely, the Change Log MAY contain earlier Change Event entries that have been accounted for in the Base.
CC-21 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.
CC-22 For any given tracked resource, 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 the end of that period of time.
CC-23 That is, a change event for resource R1 at time t MAY have an order number that is greater than a change to an unrelated resource R2 at time t+1
CC-24 A Server MAY batch up changes and add a batch of consolidated Change Events to the Change Log at some interval.
CC-25 A Server MUST eventually report a change event for a tracked resource if at time t0, a tracked resource is added to the Tracked Resource Set, deleted from the Tracked Resource Set, or the state of the Tracked Resource Set is modified, such that a GET on that resource would now return a semantically different response from a GET request issued just before t0.
CC-26 When a resource is modified two or more times in rapid succession, a Server MAY elide such modifications by reporting only a single creation or modification event in the Change Log.
CC-27 A Server MAY report a modification event even in cases where there would be no significant difference in response.
CC-28 When a new resource is modified or added to a tracked resource set, a Server MAY issue a modification event or a creation event
CC-29 the server MUST eventually issue at least one such event
CC-30 When a resource is created and deleted in rapid succession, a Server MAY omit all Change Events for that resource.
CC-31 a Server MAY produce a Base that is only an approximation of the Tracked Resource Set membership
CC-32 For each such inconsistency in the Base, the Server MUST at some point include a corrective Change Event in the Change Log more recent than the base cutoff event
CC-33 A Server MAY issue a deletion event for a resource that is not a member of the Tracked Resource Set. This includes issuing multiple deletion events for (what was) a member of the Tracked Resource Set. This might happen when the base is being recalculated, and the change log slightly overlaps the base, or as part of the corrective set of change events described in the previous paragraph.
CC-34 the most recent Change Event resources MUST be included in the RDF representation of the Tracked Resource Set itself
CC-35 earlier events MAY be segmented into separate Change Log resources referenced from the trs:previous property
CC-36 There can be any number of such Change Log segments. The events in a Change Log segment MUST all have order numbers higher than any events in any subsequent Change Log segments.
CC-37 Just as the most recent Change Events MUST be included inline in the HTTP response for the Change Log in the Tracked Resource Set resource itself, TRS Servers MUST include the Change Event resources for each Change Log segment inline in the RDF representation of the HTTP response for the Change Log segment.
CC-38 the Base MAY be segmented into separate resources; there can be any number of such Base segments, each one listing a subset of all Tracked Resources
CC-39 Base segmentation MUST be accomplished using the mechanisms described in the "Resource Paging" section of [OSLCCore3].
CC-40 A Server MAY include a Tracked Resource in more than one base segment.
CC-41 A Server MAY add new change events at the start of the initial set of events returned inline with the Tracked Resource itself
CC-42 A Server MUST NOT move a change event from one segment of a segmented change log to an earlier segment in the chain, one with more recent change events.
CC-43 A Server MAY move a change event from one segment of a segmented change log to an later segment in the chain, one with older change events.
CC-44 A Server MAY remove a change event from the change log
CC-45 A chain of Change Log segments MAY continue all the way back to the inception of the Tracked Resource Set and contain Change Events for every change made since then.
CC-46 a Server MAY truncate the Change Log at a suitable point in the chain
CC-47 the Change Log MUST contain the base cutoff event of the corresponding Base
CC-48 When the Base has no base cutoff event (i.e., the Base enumerates the Resource Set at the inception of the Tracked Resource Set), the Change Log MUST contain all Change Events back to the inception of the Tracked Resource Set; i.e., no truncation is allowed
CC-49 a TRS Server MAY calculate a new base set at any time, with a new cutoff event in the Change Log
CC-50 In order to handle clients that are currently processing the older Base and Change Log
CC-51 When calculating a new Base, the TRS Server SHOULD retain Change Events before the new cutoff event that a reasonable client might still be processing.
CC-52 When producing multiple segments of a new Base, the TRS Server MUST NOT reuse URIs from segments of a previous Base.
CC-53 A patch event MUST have type trs:Modification or trs:Creation Change Events; it is not meaningful for trs:Deletion Change Events.
CC-54 A TRS patch MUST consist of a sequence of directives delimited by a ‘.’
CC-55 Each directive of a patch MUST consist of four terms.
CC-56 Each term in a directive MAY be separated with white space, including newlines.
CC-57 The first term of a directive MUST be the ASCII character 'A' (U+0041) or the ASCII character 'D' (U+0044)".
CC-58 The subject and predicate (terms 2 and 3) in a directive MUST be in the form of absolute URI references enclosed between ‘<’ and ‘>’
CC-59 The object in a directive (term 4) MUST be either an absolute URI reference enclosed between ‘<’ and ‘>’, or a literal in [Turtle] syntax.
CC-60 The order of patch directives is significant - changes MUST be applied in the order given.
CC-61 This specification is based on [OSLCCore3]. OSLC Tracked Resource Set Servers servers MUST be compliant with the Core specification, MUST follow all the mandatory requirements in the normative sections of each part of this specification, and SHOULD follow all the guidelines and recommendations in both these specifications.

Appendix A. Acknowledgements

This section is non-normative.

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

Appendix B. References

B.1 Normative references

[LDP]
Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. W3C, 26 February 2015. W3C Recommendation. URL: https://www.w3.org/TR/ldp/
[OSLCCore3]
Steve Speicher; Jim Amsden. OSLC Core 3.0. OASIS. URL: http://tools.oasis-open.org/version-control/svn/oslc-core/specs/oslc-core-v3.html
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. IETF, March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
B. Leiba. Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. IETF, May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174
[Turtle]
Eric Prud'hommeaux; Gavin Carothers. RDF 1.1 Turtle. W3C, 25 February 2014. W3C Recommendation. URL: https://www.w3.org/TR/turtle/

B.2 Informative references

[HTTP11]
R. Fielding, Ed.; J. Reschke, Ed.. Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing. IETF, June 2014. Proposed Standard. URL: https://httpwg.org/specs/rfc7230.html
[OSLCCore2]
S. Speicher; D. Johnson. OSLC Core 2.0. http://open-services.net. Finalized. URL: http://open-services.net/bin/view/Main/OslcCoreSpecification
[RDFPatch]
Andy Seaborne; Rob Vesse. RDF Patch – Describing Changes to an RDF Dataset. Unofficial Draft 20 November 2014. URL: http://afs.github.io/rdf-patch/
[WEBARCH]
Ian Jacobs; Norman Walsh. Architecture of the World Wide Web, Volume One. W3C, 15 December 2004. W3C Recommendation. URL: https://www.w3.org/TR/webarch/