Notices

Copyright © OASIS Open 2013-2023. 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.

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

1.2 References

1.2.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/
[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
[TRS]
Steve Speicher; Frank Budinsky; Vivek Garg; Nick Crossley. OSLC Tracked Resource Set Version 3.0. Part 1: Specification. OASIS. URL: https://docs.oasis-open-projects.org/oslc-op/trs/v3.0/tracked-resource-set.html

2. Concept and Version Resources

This section is non-normative.

This part of the OSLC Configuration Management Specification defines the representation and behavior of versioned resources - resources that have multiple versions.

As described in OSLC Configuration Management - Concept resources, version resources, and configuration contexts, the major “Artifacts” or “Entities” in OSLC domains are concept resources.

The state (including the properties) of a concept resource can vary over time, or for other reasons. A versioned resource is a concept resource that keeps track of different states; a version resource is one specific state of a versioned resource.

Versioned resources are typically used in configurations - where they are often called configuration items.

3. Version Resources

A version resource defines a particular version of the state of a concept resource. Not every past state is necessarily kept. A server MAY elide or discard states. [CONFIG-VR-1]

A version resource URI identifies a specific version of a concept resource with no further configuration context required.

A version resource MUST have a type of oslc_config:VersionResource. [CONFIG-VR-2]

Version resources SHOULD be compliant with [LDP]. [CONFIG-VR-4]

Version resources SHOULD have an oslc_config:versionId property. [CONFIG-VR-5]

Servers MAY provide other properties that distinguish between major changes or revisions, and minor changes or iterations. [CONFIG-VR-6]

4. Version Resource Shapes

VersionResource Properties
Prefixed Name Occurs Read-only Value-type Representation Range Description
dcterms:contributor Zero-or-many unspecified AnyResource Either foaf:Agent, foaf:Person Contributor or contributors to the resource. The link target is usually a foaf:Person or foaf:Agent, but could be any type.
dcterms:created Zero-or-one true dateTime N/A Unspecified Timestamp of resource creation. Each resource SHOULD have one instance of the dcterms:created property [CONFIG-VR-9].
dcterms:creator Zero-or-many true AnyResource Either foaf:Agent, foaf:Person Creator or creators of the resource. The link target is usually a foaf:Person or foaf:Agent, but could be any type.
dcterms:description Zero-or-one false XMLLiteral N/A Unspecified Descriptive text about the resource, represented as rich text in XHTML content.
dcterms:identifier Zero-or-one true string N/A Unspecified A unique identifier for this resource.
dcterms:isVersionOf Exactly-one unspecified Resource Reference Unspecified The concept resource of which this resource is a version. The subject of this property MUST be the version resource URI [CONFIG-VR-10].
dcterms:modified Zero-or-one true dateTime N/A Unspecified Timestamp of latest resource modification. Each resource SHOULD have one instance of the dcterms:modified property [CONFIG-VR-11].
dcterms:subject Zero-or-many unspecified string N/A Unspecified Tag or keyword for a resource. Each occurrence of a dcterms:subject property denotes an additional tag for the resource. Tags on versioned resources SHOULD be modifiable even if the resource is otherwise immutable (checked in) [CONFIG-VR-12].
dcterms:title Zero-or-one false XMLLiteral N/A Unspecified Title of the resource, represented as rich text in XHTML content.
oslc_config:committed Zero-or-one true dateTime N/A Unspecified Date and time this version resource was checked in. Absent for mutable (checked out) versions.
oslc_config:committer Zero-or-many true AnyResource Either foaf:Agent, foaf:Person The entity that checked in this version.
oslc_config:component Zero-or-one unspecified Resource Reference oslc_config:Component The component to which this version belongs. Configuration Management servers SHOULD indicate the owning component for each version resource using either this property, or using the membership relationship from the component LDPC [CONFIG-VR-13].
oslc_config:versionId Zero-or-many unspecified string N/A Unspecified A short human-readable identifier for the version of a resource. All versioned resources SHOULD have this property; where the property is present, this identifier MUST be unique amongst all currently existing versions of the same concept resource. The subject of this property SHOULD be the concept resource URI [CONFIG-VR-14].
oslc:archived Zero-or-one unspecified boolean N/A Unspecified Indicates whether the subject has been marked as archived, no longer an active resource.
oslc:instanceShape Zero-or-one true Resource Either oslc:ResourceShape The URI of a Resource Shape that describes the possible properties, occurrence, value types, allowed values and labels. This shape information is useful in displaying the subject resource as well as guiding clients in performing modifications. Instance shapes may be specific to the authenticated user associated with the request that retrieved the resource, the current state of the resource, and other factors, so instance shapes SHOULD NOT be cached [CONFIG-VR-15].
oslc:modifiedBy Zero-or-many true AnyResource Either foaf:Agent, foaf:Person The entity that most recently modified the subject resource. The link target is usually a foaf:Person or foaf:Agent, but could be any type.
oslc:serviceProvider Zero-or-many true Resource Reference oslc:ServiceProvider A link to the resource's OSLC Service Provider. If the subject resource is available from an application that implements multiple domain specifications, there can be multiple values for this property.
oslc:shortId Zero-or-one unspecified string N/A Unspecified A short and human-readable identifier for the resource, such as a number.
oslc:shortTitle Zero-or-one unspecified XMLLiteral N/A Unspecified A short title for the resource, represented as rich text in XHTML content.
prov:wasDerivedFrom Zero-or-many unspecified Resource Reference Unspecified A resource from which this version was derived. This is likely to reference a different concept resource; use of prov:wasRevisionOf is recommended to indicate an earlier version of the same concept resource. The subject of each instance of this property MUST be the concept resource URI; the object can be a version resource URI, or a concept resource URI (possibly for a non-versioned resource) [CONFIG-VR-16].
prov:wasRevisionOf Zero-or-many unspecified Resource Reference Unspecified A resource from which this version was derived. This is likely to reference an earlier version of the same concept resource; use of prov:wasDerivedFrom is recommended to indicate an earlier version of a different concept resource. The subject of each instance of this property MUST be the concept resource URI; the object is likely to be a version resource URI [CONFIG-VR-17].
rdf:type One-or-many unspecified Resource Reference rdfs:Class A resource type URI. One of the type properties MUST have the version resource URI as the subject, and MUST have a resource type of oslc_config:VersionResource [CONFIG-VR-18]. Other types for the concept resource of which this is a version SHOULD use the concept resource URI as the subject [CONFIG-VR-19].

5. Supported Operations on Versioned Resources

A versioned resource server MUST support the following operations on version resources: [CONFIG-VR-20]

A versioned resource server MAY support the following operations on version resources: [CONFIG-VR-21]

6. Delegated UIs

A versioned resource server MAY provide delegated user interface dialogs for creation of new concept resources or new version resources. [CONFIG-VR-24]

A versioned resource server SHOULD provide delegated user interface dialogs for selection of concept resources. A versioned resource server MAY provide delegated user interface dialogs for selection of version resources, but such selection is typically performed in a configuration context to find the appropriate version. [CONFIG-VR-25]

7. Compact Rendering

A versioned resource server SHOULD implement compact rendering, both for concept resources and version resources. See Compact Rendering for the handling of configuration context in such rendering. [CONFIG-VR-26]

8. Tracked Resource Sets

A versioned resource server MAY publish version resources in a Tracked Resource Set; the URIs in the base and change log MUST be the version resource URIs, not the concept resource URIs. All Tracked Resource Sets for version resources MUST be compliant with [TRS]. [CONFIG-VR-27]

9. Conformance

Implementations of this specification need to satisfy the following conformance clauses.

Clause Number Requirement
CONFIG-VR-1 A version resource defines a particular version of the state of a concept resource. Not every past state is necessarily kept. A server MAY elide or discard states.
CONFIG-VR-2 A version resource MUST have a type of oslc_config:VersionResource.
CONFIG-VR-3 A version resource MUST be related to its concept resource using the dcterms:isVersionOf property.
CONFIG-VR-4 Version resources SHOULD be compliant with [LDP].
CONFIG-VR-5 Version resources SHOULD have an oslc_config:versionId property.
CONFIG-VR-6 Servers MAY provide other properties that distinguish between major changes or revisions, and minor changes or iterations.
CONFIG-VR-7 The shape of a versioned resource: all versioned resources MUST match this shape
CONFIG-VR-8 Versioned resources SHOULD match other shapes appropriate for their types - that is, they MAY have additional properties and property constraints beyond those defined here
CONFIG-VR-9 Each resource SHOULD have one instance of the dcterms:created property
CONFIG-VR-10 The subject of this property MUST be the version resource URI
CONFIG-VR-11 Each resource SHOULD have one instance of the dcterms:modified property
CONFIG-VR-12 Tags on versioned resources SHOULD be modifiable even if the resource is otherwise immutable (checked in)
CONFIG-VR-13 Configuration Management servers SHOULD indicate the owning component for each version resource using either this property, or using the membership relationship from the component LDPC
CONFIG-VR-14 All versioned resources SHOULD have this property; where the property is present, this identifier MUST be unique amongst all currently existing versions of the same concept resource. The subject of this property SHOULD be the concept resource URI
CONFIG-VR-15 instance shapes SHOULD NOT be cached
CONFIG-VR-16 The subject of each instance of this property MUST be the concept resource URI; the object can be a version resource URI, or a concept resource URI (possibly for a non-versioned resource)
CONFIG-VR-17 The subject of each instance of this property MUST be the concept resource URI; the object is likely to be a version resource URI
CONFIG-VR-18 One of the type properties MUST have the version resource URI as the subject, and MUST have a resource type of oslc_config:VersionResource
CONFIG-VR-19 Other types for the concept resource of which this is a version SHOULD use the concept resource URI as the subject
CONFIG-VR-20 A versioned resource server MUST support the following operations on version resources:
CONFIG-VR-21 A versioned resource server MAY support the following operations on version resources:
CONFIG-VR-22 PUT: Update the state of a specific version resource; this operation MAY succeed by creating a new version, or MAY succeed without creating a new version for servers that offer version resources with mutable state. A PUT operation on a version resource MAY fail, since version resources may be immutable, or have many immutable properties.
CONFIG-VR-23 DELETE: Delete the specified version resource. Deletion of immutable versions, or versions used in configurations, MAY fail or MAY require specific privileges.
CONFIG-VR-24 A versioned resource server MAY provide delegated user interface dialogs for creation of new concept resources or new version resources.
CONFIG-VR-25 A versioned resource server SHOULD provide delegated user interface dialogs for selection of concept resources. A versioned resource server MAY provide delegated user interface dialogs for selection of version resources, but such selection is typically performed in a configuration context to find the appropriate version.
CONFIG-VR-26 A versioned resource server SHOULD implement compact rendering, both for concept resources and version resources. See Compact Rendering for the handling of configuration context in such rendering.
CONFIG-VR-27 A versioned resource server MAY publish version resources in a Tracked Resource Set; the URIs in the base and change log MUST be the version resource URIs, not the concept resource URIs. All Tracked Resource Sets for version resources MUST be compliant with [TRS].