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

Compatibility with Other Standards

OSLC Providers and resources SHOULD be compliant with the Linked Data Platform 1.0.

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.

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 - Component, Configuration, ConfigurationMatch, ConfigurationMatches, Contribution, Selections, VersionResource

Properties - accepts, acceptedBy, actions, component, configuration, contribution, contributionOrder, selections, selects, immutable, matchOrder, versionId

Link types - configurationMatches

Individuals - AllMAtches, FirstMatch

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 property MUST be the version resource URI. A version resource MUST have a resource type of oslc_config:VersionResource. Other types for the concept resource of which this is a version SHOULD use the concept resource URI as the subject. Providers MAY treat this property as read-only.
dcterms:isVersionOf exactly-one unspecified Resource Reference The concept resource of which this resource is a version. The subject of this property 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 property SHOULD be the concept resource URI.
oslc_config:derivedFrom zero-or-many unspecified Resource Reference The resource from which this version was derived. This is likely to reference one or more earlier versions of the same 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. Clients should be aware that providers MAY use W3C provenance vocabulary terms in addition to or instead of this term.
oslc_config:match zero-or-many true ConfigurationMatch Inline

A URI used as the subject for triples identifying one match for a configuration of a component containing this resource. Triples with this predicate are returned only when a concept resource is requested in a configuration context, and the request includes the header
Prefer: return=representation; include="http://open-services.net/ns/config#AllMatches".

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 resource
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. Providers MAY treat this property as read-only.
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 resource
Properties specific to a configuration
Prefixed Name Occurs Read-only Value-type Representation Description
rdf:type one-or-many unspecified Resource Reference

Modified - please review.

The resource type URIs. A configuration MUST have a resource type of oslc_config:Configuration. Other types may be added, including types that are used in oslc_config:accepts and oslc_config:acceptedBy properties to define which configurations may be added as contributions to this configuration. Providers MAY treat this property as read-only.

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 Typically inline A contribution to this configuration. The set of resource versions identified by this configuration includes the set determined by the oslc_config:selections resource, and each of the sets of resource versions identified by the contributed configurations. A user may request an update to a configuration to change the set of contributions; servers MUST deny such requests if any added contributions do not match this configuration.
oslc_config:selections zero-or-one false Resource Reference A reference to the resource identifying the versions of the resources (configuration items) in the configuration. The target is likely to be of type oslc_config:Selections.
oslc_config:mutable exactly-one Partially 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 from a false value to a true value, but there are explicit operations to create mutable configurations (streams) from immutable baselines. It is unspecified whether modifying this value from true to false is permitted; again, there are explicit operations to create immutable baselines from mutable streams. 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.
oslc_config:accepts zero-or-many unspecified Resource Reference

New - please review.

A type of configuration that is acceptable as a contribution to this configuration. A configuration with no value for this predicate accepts no contributions - that is, it can only be a leaf in a configuration hierarchy. Providers MAY treat this property as read-only.

oslc_config:acceptedBy zero-or-many unspecified Resource Reference

New - please review.

A type of configuration that accepts this configuration as a contribution. A configuration with no value for this predicate may not be used as a contribution to any other configuration - that is, it can only be a root of a configuration hierarchy (or a stand-alone configuration if there is also no value for oslc_config:accepts). Such configurations should be rare. Providers MAY treat this property as read-only.

oslc_config:derivedFrom zero-or-many unspecified Resource Reference For a stream created by copying some other configuration, the stream or baseline from which this stream was first copied. This property MUST be absent for streams created as new empty streams. The property is undefined for baselines. Providers MAY treat this property as read-only.
oslc_config:previousBaseline zero-or-many false Resource Reference For a stream or a baseline, a link to the most recent baseline before this of the same stream. When creating a new baseline from a stream, the previousBaseline property of the new baseline should be copied from the previous value of previousBaseline on the stream, and the previousBaseline value on the stream should be updated to refer to the newly created baseline. The chain of previousBaseline links thus shows the history of baselines of a stream. Multiple values of previousBaseline may indicate a merge of several baselines into one stream, though this specification does not define how that is achieved.
oslc_config:baselineOfStream exactly-one (for a baseline) true Resource Reference For a baseline, this property MUST be present, and indicates the stream of which this is a baseline. Note that the referenced resource might no longer exist (streams are mutable so may be deleted), but this property remains valuable to relate all baselines of the same stream.
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.

Contribution

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

In the set of Contribution resources for a single parent configuration, there SHOULD be only one contribution for a given contributed configuration.

Properties of a Contribution resource
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. Providers MAY treat this property as read-only.
oslc_config:configuration exactly-one false Configuration Reference

Updated - please review

The contributed configuration. This contributed configuration SHOULD be unique amongst the set of configurations contributed to a given parent configuration. On a PUT or POST of a Configuration resource and its Contributions, a server MAY collapse multiple contributions for the same configuration to a single contribution. During such a reduction of multiple Contribution resources to a single Contribution resource, this specification does not define the contributionOrder value in the merged result.

oslc_config:contributionOrder exactly-one false String n/a

Updated - please review

An indication of the order of the contribution, relative to other contributions. Contributions are sorted lexicographically on the Unicode code points of this value to resolve component skew. A string is used rather than a number to make it easier for tools to insert entries into an existing list. To ensure predictable sorting regardless of implementation and locale, this string SHOULD be restricted to ASCII characters. Providers MUST support at least 64 characters in this string.

Selections

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

Properties of a Selections resource
Prefixed Name Occurs Read-only Value-type Representation Description
rdf:type one-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. Providers MAY treat this property as read-only.
oslc_config:selects zero-or-many unspecified Resource Reference The selected version resource.

ConfigurationMatch

Revised - please review.

An inline read-only resource identified by the oslc_config:match property of a VersionResource, providing details of a single match for a given concept resource contained in the component of a configuration context, or one of the configurations contributed to that context. These inline resources are provided only when a concept resource is requested in a configuration context, and the request includes the header
Prefer: return=representation; include="http://open-services.net/ns/config#AllMatches".

Properties of a ConfigurationMatch resource
Prefixed Name Occurs Read-only Value-type Representation Description
rdf:type zero-or-many true Resource Reference The resource type URIs. The matches returned with a ConfigurationMatches response each have a resource type of oslc_config:ConfigurationMatch, but this type need not be explicitly represented in the RDF.
oslc_config:configuration exactly-one true Resource Reference A reference to a configuration of a component that contains the requested concept resource.
oslc_config:matchOrder exactly-one true Integer literal n/a The ordinal value for this match, starting at 1 for the first match.
oslc_config:selects zero-or-one true Resource Reference The version resource that would be selected by this match, or rdf:nil if no version would be selected (the concept resource is not selected in the corresponding configuration). If the property is missing, the version selected is unknown, or the concept resource might not be selected in the corresponding configuration.

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. The compact rendering returned for UI Previews is an exception to this rule.

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.

Syntax:

?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 Query Syntax Specification.

Example:

?oslc_config:context=%3Chttp://example.com/configurations/globalConfig12%3E

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.

Matching Contributions

New - please review.

Certain types of configuration accept only certain other types of configurations as contributions. A global configuration must be prepared to accept any suitable configuration from an arbitrary configuration provider, while a configuration from some non-global provider may accept only contributions from the same provider. Similarly, some non-global configurations may be acceptable as contributions to global configurations, while other non-global configurations may only be valid in the context of a broader scoped configurations from that same provider.

The acceptability of a configuration as a child contribution to a parent configuration is governed by the oslc_config:acceptedBy property on the child configuration and the oslc_config:accepts property on the parent configuration. A configuration is a match, and thus acceptable as a contribution, if and only if:

  1. The parent has an oslc_config:accepts property whose value is the same as one of the types of the child configuration, AND
  2. The child has an oslc_config:acceptedBy property whose value is the same as one of the types of the parent configuration.

A configuration is thus marked as a global configuration by adding an oslc_config:accepts property with the value oslc_config:Configuration. Any configuration that is suitable to be a contribution to a global configuration (including global configurations themselves) MUST have an oslc_config:acceptedBy property with the value oslc_config:Configuration. A configuration may be marked as not accepting any kind of contribution (that is, it may only appear as a leaf in the configuration tree) by not having any oslc_config:accepts property. A configuration may be marked as ineligible as any form of contribution (that is, it may only appear as a root in the configuration tree) by not having any oslc_config:acceptedBy property.

Configuration providers may define their own types of configuration, and use those types in oslc_config:acceptedBy and oslc_config:accepts properties to define the allowed contributions.

Note that providers are likely to treat the oslc_config:accepts and oslc_config:acceptedBy as provider-generated read-only properties, not modifiable by a consumer.

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.

In order to provide a good user experience when selecting configurations to be used as contributions to a parent configuration, the UI Consumer SHOULD provide the URI of the parent configuration as a parameter to the Delegated UI Dialog, using the parameter oslc_config.parentConfiguration. UI Providers SHOULD use the types and oslc_config:accepts property values of that resource to filter the list of potential contributions shown in the selection dialog.

Syntax:

?oslc_config:parentConfiguration=uri_ref_esc

Example:

?oslc_config:parentConfiguration=%3Chttp://example.com/configurations/globalConfig12%3E

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

Updated - please review

Configuration providers SHOULD implement compact rendering. Where implemented, clients MUST pass any required configuration context on the initial request for a compact resource, and the configuration provider MUST return a compact resource honoring that configuration context. Moreover, the icon reference, the large preview reference, the small preview reference, and any references directly embedded in the large and small HTML preview documents in that compact resource MUST correspond to the given configuration context, so the client need not pass a configuration context to render the icon or the HTML preview. A reference corresponds to a given configuration if it is the URI of a non-versioned resource, the version URI for a versioned resource, or

Tracked Resource Sets

A configuration provider SHOULD, and a global configuration provider MUST, provide a Tracked Resource Set for configurations, contributions, and components. A configuration provider MAY publish selections and configuration items in a Tracked Resource Set.

Service Discovery and Registration

TBD - how a local configuration provider finds its global configuration provider. Service resources need to distinguish local and global configuration 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:

A configuration provider MAY support PATCH on a configuration to update the tags and/or the set of contributed configurations.

Query Support

Configuration providers MUST support OSLC Simple Query for configurations and components. Query for the following properties using oslc.where and oslc.select MUST be supported:

Query for other properties MAY be supported.

For example, this is a query for baselines of a given stream http://example.com/configs/stream123, with tag 'stellar', created after July 1st 2014:

http://example.com/configs?oslc.where=oslc_config:baselineOfStream=<http://example.com/configs/stream123> and 
   dc_terms:modified>="2014-07-01T00:00:00" and dcterms_subject="stellar"

Since some of those character must be encodded, the request would be issued as:

http://example.com/configs?oslc.where=oslc_config%3AbaselineOfStream%3D%3Chttp%3A%2F%2Fexample.com%2Fconfigs%2Fstream123%3E%20and
   %20dc_terms%3Amodified%3E%3D%222014-07-01T00%3A00%3A00%22%20and%20dcterms_subject%3D%22stellar%22

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:

A configuration provider MAY support actions that:

Version and Component Skew

Updated - please review.

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.

References to versioned resources in the context of a configuration are resolved using a pre-ordered traversal of the configuration and its contribution tree:

  1. The component for the context configuration itself is examined; if that component contains the given resource, the reference is resolved using the selections for that configuration.
  2. The contributed configurations are examined in the order determined by the oslc_config:contributionOrder property. If that property is missing, or does not define a unique order for a contribution, then the search order for that contribution is undefined.
  3. For each contributed configuration found in step 2, the search recurses starting at step 1.

In the presence of component or version skew, the above algorithm may find more than one reference to a component containing the given resource. A configuration provider MUST support the ability to return the version selected by the first such reference, including returning a 404 error if there is no selection for the given resource in the first configuration with a matching component. A configuration provider MAY also support the ability to return an ordered list of matching configurations and the versions selected (if any).

A client MAY request a search type using a Prefer header. To request the default first-match search, client may omit the Prefer header, or include a header:

Prefer: return=representation; include="http://open-services.net/ns/config#FirstMatch"

To request a full search and a list of matches, the client includes a header:

Prefer: return=representation; include="http://open-services.net/ns/config#AllMatches"

In either case, the server MUST return the first matched selection in the body of the response (or a 404 error if the first matching component had no selection for this resource). The server MUST also respond with a Preference-Applied header, and if the http://open-services.net/ns/config#AllMatches search was used, the server MUST also include oslc_config:match properties indicating the inline oslc_config:ConfigurationMatch resources that describe each possible matching contributions and the corresponding version selection:

Preference-Applied: return=representation; include="http://open-services.net/ns/config#AllMatches"

: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" ;
   oslc_config:match
      [
         oslc_config:component :component1 ;
         oslc_config:configuration :configuration1 ;
         oslc_config:matchOrder 1 ;
         oslc_selects :conceptResourceA-version17
      ] ,
      [
         oslc_config:component :component1 ;
         oslc_config:configuration :configuration2 ;
         oslc_config:matchOrder 2 ; 
         oslc_selects rdf:nil
      ] ,
      [
         oslc_config:component :component2 ;
         oslc_config:configuration :configuration3 ;
         oslc_config:matchOrder 3 ; 
         oslc_selects :conceptResourceA-version15
      ] .

Non-RDF Sources

All resources selected by configurations as described in this specification MUST be RDF resources. Configuration providers SHOULD follow the Linked Data Platform recommendation for handling non-RDF data sources.

Issues and other TBDs