OSLC Tracked Resource Set Version 3.0. Part 3: Constraints

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.

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.

1. Introduction

This section is non-normative.

This specification defines standard constraints on the vocabulary for Tracked Resource Sets.

RDF vocabularies define the terms and resources for a domain of interest, in this case, OSLC Tracked Resource Sets. These vocabularies are often specified in an open manner, without providing information such as property domain and range assertions, cardinalities, etc. This helps keep the vocabulary applicable for a wide range of uses and furthering integration with other vocabularies.

However, it is often desirable to closed down a vocabulary with specific constraints to facilitate using the vocabulary for a specific purpose. This document specifies the constraints for using the OSLC Tracked Resource Set vocabulary in OSLC. Different sets of constraints may be applied to a vocabulary in order to tailor its use, without overly constraining the vocabulary for other usages.

These constraints apply to the core vocabulary defined in OSLC Tracked Resource Set Version 3.0. Part 2: Vocabulary.

Note that this document is informative; the normative document for the vocabulary is the machine-readable source in [VOCAB].

1.1 Typographical Conventions and Use of RFC Terms

This section is non-normative.

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.

1.1.1 References

1.1.1.1 Normative references

[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

1.1.1.2 Informative references

[VOCAB]: Nick Crossley; Frank Budinsky. OSLC TRS Version 3.0: Part 4: Machine-readable RDF Vocabulary. http://open-services.net. Finalization. URL: https://docs.oasis-open-projects.org/oslc-op/trs/v3.0/os/trs-vocab.ttl

1.2 Resource Constraints

This section specifies the constraints for Tracked Resource Set resources. The resource properties are not limited to the ones defined in this specification, TRS Servers may provide additional properties. It is recommended that any additional properties exist in their own unique namespace and not use the namespaces defined in these specifications.

1.2.1 Resource: TrackedResourceSetShape

Describes: http://open-services.net/ns/core/trs#TrackedResourceSet
Summary: The shape of a TrackedResourceSet
Description: A Tracked Resource Set provides a representation of the current state of a set of Tracked Resources.

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-1].
`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-2].
`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-3].

1.2.2 Resource: BaseShape

Describes: http://open-services.net/ns/core/trs#Base
Summary: The shape of a Base
Description: A Base is an ldp:DirectContainer that enumerates the members of a Tracked Resource Set at the time the Base was computed.

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.

1.2.3 Resource: ChangeLogShape

Describes: http://open-services.net/ns/core/trs#ChangeLog
Summary: The shape of a ChangeLog
Description: A Change Log describes what resources have been created, modified or deleted, and when.

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-4] The URI is used to identify an event; it need not be dereferenceable, and MAY be a URN. [CC-5] The URI of a Change Event MUST be guaranteed unique, even if order numbers get reused in the wake of a Server rollback [CC-6].
`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.

1.2.4 Resource: CreationEventShape

Describes: http://open-services.net/ns/core/trs#Creation
Summary: Creation Event
Description: Represents the creation or modification of a resource at a point in time.

Creation 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-7], but a more recently available Change Event MUST have a larger number than any previously avalable Change Event as accessed by GET on the change log [CC-8].
`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-9], 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.

1.2.5 Resource: ModificationEventShape

Describes: http://open-services.net/ns/core/trs#Modification
Summary: Modification Event
Description: Represents the creation or modification of a resource at a point in time.

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-10], but a more recently available Change Event MUST have a larger number than any previously avalable Change Event as accessed by GET on the change log [CC-11].
`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-12], 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.

1.2.6 Resource: DeletionEventShape

Describes: http://open-services.net/ns/core/trs#Deletion
Summary: Deletion Event
Description: Represents the deletion of resource at a point in time.

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-13], but a more recently available Change Event MUST have a larger number than any previously avalable Change Event as accessed by GET on the change log [CC-14].

1.3 Conformance

OSLC TRS Servers MUST use the vocabulary terms defined here where required, and with the meanings defined here. Servers MAY augment this vocabulary with additional terms. [CC-15]