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

Capabilities include:

The specification allows but does not mandate creation and updating of configurations local to a tool or domain.

The 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 specification does not include all of ITIL or IT Service Management, a configuration as defined by this specification 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.

Editor's working draft.

Notation and Conventions

The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC–2119. This document is a mixture of normative and informative text.

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 set of versioned resources. Components are the units of configurability, and form reusable assets or building blocks.
Configuration
A set of versions of resources in a component. Configurations commonly identify exactly 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 contributed configurations, identifying further sets of versions of resources in other components.
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 repositories.
Contribution
A configuration that is a member of the set of configurations making up a configuration. The set of versioned resources in a configuration is the union of the set of versioned resources in that configuration and all its contributions; contributions are ordered to resolve any conflicts between that set.
Branch
(verb) to create a configuration for parallel or insulated development.
(noun) the result of parallel or insulated development after branching - that is, a sequence of baselines, usually with a stream at the end of the branch.
Baseline
An immutable configuration of one or more components that corresponds to some meaningful state of its resources. The set of configuration items in a baseline cannot be changed; the state of each of those items cannot be changed. Some of the metadata on the baseline itself may be changed, such as tags, comments, etc. 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:VersionResource.

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:VersionResource ;
	dcterms:isVersionOf :conceptResourceA .
:conceptResourceA
	a :someType ;
    oslc_config:versionId "23" ;
	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:VersionResource ;
    dcterms:isVersionOf :conceptResourceA .
:conceptResourceA
    a :someType ;
    oslc_config:versionId "17" ;
    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:VersionResource ;
		dcterms:isVersionOf :conceptResourceA .
	:conceptResourceA
		a :someType ;
       oslc_config:versionId "23" ;
		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:VersionResource ;
		dcterms:isVersionOf :conceptResourceA .
	:conceptResourceA
		a :someType ;
       oslc_config:versionId "17" ;
		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 - VersionResource, Component, Configuration,

Properties - immutable, versionId, component

Shapes

Configuration Item and Version Resource

Resources of any type may appear as configuration items - resources 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:VersionResource, and a single dcterms:isVersionOf triple whose subject is the version resource and whose object is the concept resource.

VersionResource

This type is used as a marker for any version resource. There are two mandatory properties for a version resource that use the the version resource URI as their subject, and one recommended property that uses the concept resource URI as its subject.

Properties of a VersionResource
Prefixed Name Occurs Read-only Value-type Representation Description
rdf:type one-or-many unspecified Resource Reference The resource type URIs. The subject of this predicate MUST be the version resource URI. A version resource MUST have a resource type of oslc_config:VersionResource, and SHOULD have other types.
dcterms:isVersionOf exactly-one unspecified Resource Reference The concept resource of which this resource is a version. The subject of this predicate MUST be the version resource URI.
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. The subject of this predicate SHOULD be the concept resource URI.

Component

A component is a unit of organization consisting of a set of versioned resources (not a set of versions of those resources). Components are the units of configurability, and form reusable assets or building blocks. The granularity of a component varies between providers, but typically it contains the set of resources of some type being used in some product, project, or a subdivision of such a set. A component has at least the following properties:

Properties of a Component
Prefixed Name Occurs Read-only Value-type Representation Description
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 MAY be a Linked Data Platform Container, containing the concept resources associated with this component.
dcterms:contributor zero-or-many unspecified Resource Either Contributor or contributors to resource (reference: Dublin Core). 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 Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many true Resource Either Creator or creators of resource (reference: Dublin Core). 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 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 this component.
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 false 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 false 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:modifiedBy zero-or-many unspecified Resource Either 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: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.

A component itself MAY be a versioned resource, indicated by the RDF type oslc_config:VersionResource on its versions, but need not be versioned; the semantics of versioned components are not defined by this specification.

Typically, components themselves are not nested - that is, typically none of the members of an oslc_config:Component container are themselves of type oslc_config:Component; any required structure and hierarchy is realized through configurations, or through the structures within the configuration items themselves (e.g., versioned folders or directories). TBD: can we make this a MUST to simplify client processing? Similarly, can we exclude sub-configurations from appearing in this flattened list of configuration items?

Configuration

A configuration identifies a set of versions of resources in a component. Configurations commonly identify exactly 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 contributed configurations, identifying further sets of versions of resources in other components. A global 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 repositories.

Properties of a Configuration
Properties specific to a configuration
Prefixed Name Occurs Read-only Value-type Representation Description
rdf:type one-or-many unspecified Resource Reference The resource type URIs. A configuration MUST have a resource type of oslc_config:Configuration.
oslc_config:component exactly-one unspecified Resource Reference The component of which this is a configuration. The component is an invariant relating the different configurations of the same "thing".
oslc_config:contribution zero-or-many false Contribution Either A contribution to this configuration. The set of resource versions identified by this configuration includes the set determined by the oslc_config:selections container, and each of the sets of resource versions identified by the contributed configurations.
oslc_config:selections zero-or-one false Resource Reference A reference to the container identifying the versions of the resources (configuration items) in the configuration.
oslc_config:mutable exactly-one true Boolean n/a

Whether the set of configuration items selected by this configuration, and the states of each of those configuration items themselves, 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, other resources that define such status may 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 property.

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 Automation and Actions.
Common Properties
dcterms:contributor zero-or-many unspecified Resource Either Contributor or contributors to resource (reference: Dublin Core). 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 Timestamp of resource creation (reference: Dublin Core)
dcterms:creator zero-or-many true Resource Either Creator or creators of resource (reference: Dublin Core). 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 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 false 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 false 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: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.
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.
prov:wasDerivedFrom, prov:wasRevisionOf zero-or-many unspecified Resource Either If the configuration is a versioned resource, indicates the previous versions or revisions of this resource.

Contribution

A contribution represents the contribution of one configuration to another. Contribution resources SHOULD (MUST? TBD) be returned inline with the configuration resource.

Properties of a Component
Prefixed Name Occurs Read-only Value-type Representation Description
rdf:type zero-or-many unspecified Resource Reference The resource type URIs. A contribution has a resource type of oslc_config:Contribution, but this type need not be explicitly represented in the RDF.
oslc_config:contributedConfig exactly-one false Configuration Reference The contributed configuration.
oslc_config:contributionOrder exactly-one false String n/a An indication of the order of the contribution, relative to other contributions. Contributions are sorted lexicographically on this property to resolve component skew.

Selections

A resource listing the version resources seelcted by this configuration. This resource MAY be a Linked Data Platform Container.

Properties of a Component
Prefixed Name Occurs Read-only Value-type Representation Description
rdf:type zero-or-many unspecified Resource Reference The resource type URIs. A Selections resource MUST have a resource type of oslc_config:Selections, but may have other types as well.
oslc_config:selects zero-or-many unspecified Resource Reference The selected version resource.

Configuration context

Since concept resource URIs for versioned resources do not inherently identify a specific version of that resource, a client SHOULD provide a configuration context for any HTTP request.

The client is responsible for providing the correct configuration context to every request issued by that client, at least where the relevant resource might be a configuration item (a versioned resource appearing in a configuration). If a resource returned from such a request contains links, the client MUST NOT assume the server has returned version-specific or configuration-specific links, and the client MUST continue to provide the correct configuration context to fetch those related resources. Only in cases where the client knows that a resource is not versioned may the configuration context be omitted.

If a configuration contest is not provided, the server MAY provide a default configuration, or MAY fail the request.

Where a configuration context is provided in a request, but the resource does not need a context (e.g., the resource is not versioned, or explicitly identifies a specific version of a versioned resource), the server MUST ignore the context.

Where a configuration context is provided in a request, and the resource is a concept resource for a versioned resource, but the configuration context is unknown or the concept resource has no version in that configuration, the request MUST fail with a 404 status.

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 or links of certain types MAY indicate that a different context is to be used when following links from that resource. Any such semantics are defined by the vocabulary for such resource and link types (RDF predicates); none are defined by this specification.

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

Configuration-Context header

The Configuration-Context header field is used on any HTTP request to identify the configuration to be used to resolve concept resource references.

Configuration-Context = URI-reference

The field value consists of a single URI-reference. When it has the form of a relative reference ([RFC3986], Section 4.2), the final value is computed by resolving it against the effective request URI ([RFC3986], Section 5).

TBD - are those references the right ones? Should the syntax use IRIs rather than URIs?

A request SHOULD contain only a single occurrence of the Configuration-Context header, and MUST NOT contain multiple Configuration-Context headers referencing different values. A server SHOULD treat multiple identical Configuration-Context headers as it would a single header, and MUST treat multiple Configuration-Context headers with different configuration values as an error, returning the status code 400.

Configuration context query string

The oslc_config:context query string may be added to any HTTP request to identify the configuration to be used to resolve concept resource references.

?oslc_config.context=uri_ref_esc

The uri_ref_esc is an angle bracket-delimited URI reference in which > and \ are \-escaped, as defined in the OSLC Core Specification (TBD - add link to OSLC Core spec at OASIS).

A request SHOULD contain only a single occurrence of the oslc_config:context query string, and MUST NOT contain multiple oslc_config:context query strings referencing different values. A server SHOULD treat multiple identical oslc_config:context query strings as it would a single header, and MUST treat multiple oslc_config:context query strings with different configuration values as an error, returning the status code 400.

If a request contains both a Configuration-Context header and an oslc_config:context query string, the oslc_config:context query string takes precedence, and the Configuration-Context header MUST be ignored.

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 global configuration provider MUST provide delegated user interface dialogs for creation and selection of configurations. A local configuration provider MUST provide a delegated user interface dialog for selection of configurations, and MAY also provide a delegated dialog for creation of configurations.

Tools providing versioned resources using configuration management systems SHOULD provide delegated user interface dialogs for selection of configuration items, and MAY provide delegated user interface dialogs for creation of configuration items.

Compact Rendering

Configuration providers SHOULD implement compact rendering. If provided, such rendering MUST honor configuration contexts. Clients MUST pass any required context both on the initial request for a compact resource and on any subsequent requests to the linked resources, such as the large and small icons, etc. TBD - check details here, and add context and core links.

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.

Service Discovery and Registration

TBD - how a local configuration provider finds its global configuration provider. Service resources need to distinguish local and global config services.

TBD - how a global configuration provider finds the possible local configuration providers that might contribute to global configurations.

TBD - are multiple global configuration providers supported, and how they discover each other?

TBD - is any kind of subscription and/or update notification required?

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:

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:

Supported Operations on Configurations

A configuration provider MUST support the following operations on configurations:

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

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:

All configuration providers MUST provide an action that:

A configuration provider MAY support actions that:

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