OSLC Configuration Management

This document defines an RDF vocabulary and a set of REST APIs for configuration management of linked data resources from multiple domains.

Scope and Capabilities

As with most OSLC domains, this specification is to be developed incrementally, adding new scenarios and capabilities over time. For the first iteration, the workgroup shall determine the capabilities required to create and use cross-domain configurations, establish baselines of those configurations, and navigate to the right versions of resources (configuration items) in those configurations or baselines. Those capabilities include at least:

Create and update configurations
Identify the version of a given resource within the context of a configuration
Establish a baseline (snapshot) of a configuration

For this first iteration, this specification allows but does not mandate capabilities for creation, deletion, and other management of versions of resources other than configurations themselves.

While the scope of this workgroup does not include all of ITIL or IT Service Management, a configuration as defined by this workgroup shall be able to contain or reference a set of Configuration Items (CIs) and their specific versions, and hence participate in the Identification, Control, and Monitoring activities of ITIL.

Terminology

Version: A referenceable state of a resource. Each version can be referenced with a distinct URI.
Revision: A version of a resource that is designed to replace an earlier version, such as an edited version of a source file, or a modified requirement.
Variant: A version of a resource that is identified by a specific set of characteristics that distinguish it from other versions of that resource, where each variant can exist at the same time as those other versions of the resource.
Component: A unit of organization consisting of a reusable set of engineering resources. Some components correspond to units of configurability (see below).
Configuration: A set of versions of some resources. Configurations commonly identify one version of each resource in a component. The resources can be unchanging (from a baseline) or open to change (in development). In some systems, configurations can be hierarchical, so that they contain other configurations.
Global Configuration: A configuration that identifies a set of configurations contributed by multiple tools or configuration management providers, allowing you to define all the relevant resources for a system. Using global configurations, you can establish a configuration context across multiple tools, even when each tool stores its resources in otherwise unrelated configurations and respositories.
Contribution: A configuration that is a member of the set of configurations making up a global configuration. When a configuration is contributed to a global configuration, the set of versions of resource in that configuration are logically added to the set of versions in that global configuration.
Branch: (verb) to create a configuration for parallel or insulated development.
Baseline: An immutable configuration of one or more components that corresponds to some meaningful state of its resources. Baselines are useful for recording deliverables, enabling a team to work with a known configuration, or as an initial state for some new stream of work.
[Work] stream: A modifiable configuration of resources. For example, team members deliver to a stream when they want to make their changes visible to other team members.

Namespaces

In addition to the namespace URIs and namespace prefixes oslc, rdf, dcterms and foaf defined in the OSLC Core specification, OSLC Configuration Management defines the namespace URI of http://open-services.net/ns/config# with a namespace prefix of oslc_config.

This specification also uses these namespace prefix definitions:

prov: http://www.w3.org/ns/prov# (W3C provenance vocabulary)

Concept and Version Resources

All the major “Artifacts” or “Entities” in OSLC domains are Concept Resources. Examples are defects, tasks, products, projects, users, tests cases requirements, plans and so on. Like all resources, concept resources have URLs. Except in a few technical and specialized scenarios, URLs of concept resources are used throughout the system. “Entities” are addressed in HTTP messages via their concept resource URLs. Links are typically established using the URL of a concept resource.

A version resource defines a particular version of the state of a concept resource. A version resource MUST have a type of oslc_config:VersionedResource.

A GET on the URI of a concept resource resolves that URI to an appropriate state of (version of) that concept resource for the appropriate configuration context (see later). The returned resource may contain RDF statements about both the version resource and the concept resource; most statements should use the concept resource as the subject, because a version resource reflects the state of (properties of) the concept resource as it appeared at some time. Using the concept resource URI as the subject of RDF statements is more consistent with the handling of non-versioned resources; using the versioned resource URI as the subject of RDF statements requires more client knowledge of versioning.

Since different versions reflecting different states of the concept resource may return conflicting RDF statements about the same subject, it is important for clients handling multiple versions (multiple configurations) to keep track of the relevant versions; this may be done using RDF named graphs.

The dcterms:isVersionOf property relates the version resource itself to its concept resource; this property is mandatory for all versioned resources.

As an example, GET http://example.com/conceptResourceA in one configuration context might return:

:conceptResourceA-version23
	a oslc_config:VersionedResource ;
	dcterms:isVersionOf :conceptResourceA .
:conceptResourceA
	a :someType ;
	dcterms:title "Concept Resource A" ;
	:color "blue" ;
	dcterms:description "Concept resource A as it appears in the state with the URI :conceptResourceA-version23" .

while in a different configuration context it might return:

:conceptResourceA-version17
	a oslc_config:VersionedResource ;
    dcterms:isVersionOf :conceptResourceA .
:conceptResourceA
    a :someType ;
    dcterms:title "Concept Resource A" ;
    :color "red" ;
    dcterms:description "Concept resource A as it appears in the state with the URI :conceptResourceA-version17" .

To keep track of which version represented which state of the conflicting color statements, use of RDF named graphs is recommended, as shown here using TriG:

:conceptResourceA-version23 = {
	:conceptResourceA-version23
		a oslc_config:VersionedResource ;
		dcterms:isVersionOf :conceptResourceA .
	:conceptResourceA
		a :someType ;
		dcterms:title "Concept Resource A" ;
		:color "blue" ;
		dcterms:description "Concept resource A as it appears in the state with the URI :conceptResourceA-version23" .
}.
   
:conceptResourceA-version17 = {
	:conceptResourceA-version17
		a oslc_config:VersionedResource ;
		dcterms:isVersionOf :conceptResourceA .
	:conceptResourceA
		a :someType ;
		dcterms:title "Concept Resource A" ;
		:color "red" ;
		dcterms:description "Concept resource A as it appears in the state with the URI :conceptResourceA-version17" .
}.

A GET on the URI of a concept resource with no configuration context MAY be resolved using a provider-specific default context, or MAY fail.

Vocabulary

Classes - Configuration, Component, VersionedResource

Properties - immutable, versionId, component

Shapes

OSLC Core properties used by all Configuration Management resources
Prefixed Name	Occurs	Read-only	Value-type	Representation	Description
OSLC Core: Common Properties
`rdf:type`	one-or-many	unspecified	Resource	Reference	The resource type URIs.
`dcterms:contributor`	zero-or-many	unspecified	Resource	Either	Contributor or contributors to resource (reference: Dublin Core). It is likely that the target resource is a [ `foaf:Person` ](http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA#foaf_Person_Resource) but that is not necessarily the case.
`dcterms:created`	zero-or-one	True	DateTime	n/a	Timestamp of resource creation (reference: Dublin Core)
`dcterms:creator`	zero-or-many	unspecified	Resource	Either	Creator or creators of resource (reference: Dublin Core). It is likely that the target resource is a [ `foaf:Person` ](http://open-services.net/bin/view/Main/OSLCCoreSpecAppendixA#foaf_Person_Resource) but that is not necessarily the case.
`dcterms:description`	zero-or-one	unspecified	XMLLiteral	n/a	Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content. SHOULD include only content that is valid and suitable inside an XHTML `<div>` element.
`dcterms:identifier`	exactly-one	True	String	n/a	A unique identifier for a resource. For versioned resources, this identifier is unique across all versions of all resources, not just unique across the concept resources. This property is assigned by the service provider when a resource is created, and is not necessarily intended for end-user display.
`dcterms:modified`	zero-or-one	True	DateTime	n/a	Timestamp of latest resource modification (reference: Dublin Core). Each resource SHOULD have one instance of this property.
`dcterms:subject`	zero-or-many	unspecified	String	n/a	Tag or keyword for a resource. Each occurrence of a `dcterms:subject` property denotes an additional tag for the resource.
`dcterms:title`	exactly-one	unspecified	XMLLiteral	n/a	Title (reference: Dublin Core) of the resource represented as rich text in XHTML content.
`oslc:serviceProvider`	zero-or-many	True	Resource	Reference	A link to the resource's OSLC Service Provider. There may be cases when the subject resource is available from a service provider that implements multiple domain specifications, which could result in multiple values for this property.
`oslc:instanceShape`	zero-or-one	unspecified	Resource	Reference	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 and thus should not be cached.
`oslc:shortTitle`	zero-or-one	unspecified	XMLLiteral	n/a	Optional: a shorter form of `dcterms:title` for the resource represented as rich text in XHTML content. SHOULD include only content that is valid inside an XHTML `<span>` element.
`oslc:shortId`	zero-or-one	unspecified	String	n/a	Optional: a shorter and human-readable form of `dcterms:identifier` for the resource, such as a number.
`oslc:modifiedBy`	zero-or-many	unspecified	Resource	Either	The URI of a resource describing 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. This is modeled after `dcterms:creator`, but Dublin Core currently has no equivalent property.
W3C Provenance Properties
`prov:wasDerivedFrom`, `prov:wasRevisionOf`	zero-or-many	unspecified	Resource	Either	Previous versions or revisions of this resource.
`prov:wasGeneratedBy`	zero-or-many	unspecified	Resource	Either	A change set or similar activity that generated this resource. It is likely that the target resource is an `oslc_config:ChangeSet` or an `oslc_cm:ChangeRequest` but that is not necessarily the case.

Configuration Item

Resources of any type may appear as configuration items - resource that appear as members of configurations or change sets. Configuration items MAY have any of the common properties shown above, and MAY have any other properties. Configuration items that represent versions of a concept resource MUST have an rdf:type triple whose subject is the version resource URI and who object is oslc_config:VersionedResource, and a single dcterms:isVersionOf triple whose subject is the version resource and whose object is the concept resource. Configuration items that are versioned resources have the following additional properties, using the concept resource URI as the subject:

Properties of a Configuration Item
`oslc_config:versionId`	zero-or-one	unspecified	String	n/a	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.

Configuration

A configuration is a Linked Data Platform Container resource with the common properties, plus the following:

Properties of a Configuration
`rdf:type`	one-or-many	unspecified	Resource	Reference	The resource type URIs. A configuration MUST have a resource type of `oslc_config:Configuration`. A configuration that has contributions or sub-configurations (contains or aggregates other configurations) MUST also have a resource type of `ldp:Container`. The members of this container are the aggregated configurations.
TBD - LDPC membership predicate(s)	zero-or-many	unspecified	Resource	Reference	The member configurations of this configuration.
`oslc_config:component`	exactly-one	false	Resource	Reference	The component of which this is a configuration. The component identifies the set of resources (configuration items) in the configuration.
`oslc_config:mutable`	exactly-one	true	Boolean	n/a	Whether the set of versioned artifact states selected by this configuration can be changed. Note that this property may not be modified directly, but there are explicit operations to create mutable configurations (streams) from immutable baselines, and vice versa. Other than this flag, configurations do not have status, workflow, or lifecycle properties; instead, we expect other resources that define such status to link to configurations. These other resources might be Change Requests, or resources from some as-yet undefined OSLC Lifecycle or Process Domain. The title and tags of a configuration may be modified regardless of the setting of this `mutable` properry.
`oslc_config:action`	zero-or-many	true	Resource	Either	The referenced resources MUST be of type oslc_config:Action. This property indicates one of the available action that may be performed on this configuration. See TBD.

Component

A component is a Linked Data Platform Container identifying a set of resources that are configured together as a unit. The granularity of a component varies between providers, but typically it contains the set of resources of some type being used in some project, or a subdivision of such a set. A component has the common properties, plus the following:

Properties of a Component
`rdf:type`	one-or-many	unspecified	Resource	Reference	The resource type URIs. A component MUST have a resource type of `oslc_config:Component`. A component that has any contained configuration items MUST also have a resource type of `ldp:Container`, and MAY have other types. The members of this container are the version resources (configuration items) in this component; the container may be empty for a compoent that has no configuration items, or one that does not publish its members. Note that a GET an a component in the context of a configuration MUST return the version resource URIs of the members.
TBD - LDPC membership predicate(s)	zero-or-many	unspecified	Resource	Reference	The member resources (configuration items) in this component. When fetching this property in the context of a configuration of this component, versioned resource members MUST be identified by a URI specific to the version of the resource in that context.

A component itself MAY be a versioned resource, indicated by the RDF type oslc_config:VersionedResource.

VersionedResource

This type is used as a marker for any versioned resource. There are two mandatory properties for a versioned resource:

Properties of a VersionedResource
`rdf:type`	one-or-many	unspecified	Resource	Reference	The resource type URIs. A versioned resource MUST have a resource type of `oslc_config:VersionedResource`, and SHOULD have other types.
dcterms:isVersionOf	exactly-one	unspecified	Resource	Reference	The concept resource of which this resource is a version.

Configuration context

The initial configuration context is to be established by the user and the system in an appropriate manner - possibly stored in a preference, picked up from an initial resource, selected from a dialog, etc.

While navigating between resources, resources of certain types MAY indicate that a different context is to be used when followings links from that resource. For example, if a member of the current configuration context is itself a configuration, that sub-configuration MUST be used as the context for resources contained in that sub-configuration. .

A client may request a specific configuration context in one of two ways.

When performing a GET on a concept URI, add an X-OSLC-Configuration-Context header, passing the URI of a configuration resource as the value:

GET /resources/conceptResourceA HTTP/1.1
X-OSLC-Configuration-Context: http://example.com/configurations/myConfiguration1

When performing a GET on a concept URI, add a query string oslc_config.context and the encoded configuration URI to the end of the request URI:

GET /resources/conceptResourceA?oslc_config.context=&3Chttp&3A//example.com/configurations/myConfiguration1&3E HTTP/1.1

Creation Factories

A global configuration provider MUST provide a creation factory for new global configurations. A local configuration provider MAY provide creation factories for local configurations and configuration items. This specification does not determine the semantics of or required properties for configuration item factories.

Delegated UIs

A configuration provider MUST provide delegated user interface dialogs for creation and selection of configurations. A configuration provider MAY also provide delegated dialogs for creation and selection of configuration items.

Tracked Resource Sets

A configuration provider SHOULD, and a global configuration provider MUST, provide a Tracked Resource Set for configurations and components. A configuration provider MAY publish configuration items in the same or a different Tracked Resource Set. Configuration providers that choose not to publish configuration items in a Tracked Resource Set MUST provide empty containers for the component resources.

Supported Operations on Configuration Items

A configuration provider MUST support the following operations on configuration items (versioned concept resources) in the context of a global configuration, or in the context of a configuration from this provider:

HEAD: Retrieve information including the version resource URI (if any) about the state of a specified versioned concept resource in the context of a specified configuration.
GET: Retrieve the state of a specified versioned concept resource in the context of a specified configuration, where this operation returns zero or one version resources matching the required state. An attempt to GET a version resource URI in a configuration context where a different version of that concept resource is bound MUST fail with an HTTP 404 error.
PUT: Update the state of a specified versioned concept resource in a specified stream; this operation might or might not cause the creation of a new version of the resource.

A configuration provider MAY support the following operations on configuration items in the context of a global configuration, or in the context of a configuration from this provider:

POST to a component container in the context of a stream, resulting in the creation of the first version of a new concept resource, or a new version of an existing resource
DELETE: Delete the current mutable version resource in a specified stream.

Supported Operations on Configurations

A configuration provider MUST support the following operations on configurations:

HEAD and OPTIONS: Retrieve information about the configuration, including link headers compliant with the W3C Linked Data Platform specification indicating the non-member resource.
GET: Retrieve the current state of the configuration.

A configuration provider MAY support, and a global configuration provider MUST support, the following operations on configurations:

POST on the configuration container to create a new stream sub-configuration
PUT and/or PATCH on the configuration container to update the tags and/or the set of sub-configurations
DELETE a configuration; providers MAY refuse to delete configurations that are part of or referenced by existing baselines.

Automation and Actions

OSLC Configuration Management providers MUST implement the Core Actions specification, and SHOULD implement the Automation specification.

A global configuration provider MUST provide actions that:

Operating on a global configuration, find the contribution (searching recursively) that has the given component
Operating on a global baseline or global stream, create a copy of that global configuration, wherein each global baseline contribution (recursively top down) is replaced by a global stream with the same initial state as the global baseline.
Operating on a global stream, commit a baseline (with optional tags), wherein each global stream contribution (recursively bottom up) is converted into a global baseline if and only if all its contributions are baselines.

All configuration providers MUST provide an action that:

Query for the most recently created baseline of a given component, optionally restricting the result to baselines with a given tag or tags

A configuration provider MAY support actions that:

Operating on a stream, create a new baseline (with optional tags) that captures the current state of (and configuration item versions in) that stream. This operation MAY operate recursively on sub-configurations, or MAY fail or not complete if any sub-configuration is not already a baseline.
Operating on a baseline or stream, create a copy of that configuration (with optional tags), wherein each baseline sub-configuration (recursively top down) is replaced by a stream with the same initial state as the baseline.

Version and Component Skew

Version skew occurs when two or more different versions of a single configuration item (same concept resource) are present in a single configuration. Not many configuration management systems support version skew. This specification does not address version skew other than through component skew.

Component skew occurs when two or more configurations (typically baselines) of the same component are used in or below a parent configuration. Global configuration providers MUST support component skew, and other configuration management providers MAY support it.

Handling of and resolution of skew TBD.

Issues and other TBDs

Service discovery
Registration of contributors
Exact details on location headers and other link headers returned from each operation and action
Handling of non-RDF versioned resources
Updates for latest W3C LDP specification, including container types and required predicates
Required support for OSLC simple query
Error conditions and status codes
Examples and sequence diagrams