OSLC Configuration Management Version 1.0. Part 3: Configuration Specification

This part of the OSLC Configuration Management Specification defines the representation and behavior of components and configurations of resources in those components (typically referred to as configurations of components, or just configurations).

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 within which the concept resource is resolved to a specific version.

A client requests a specific configuration context in one of two ways:

When performing a GET on a concept URI, add a Configuration-Context header, passing the URI of a configuration resource as the value.
```
GET /resources/conceptResourceA HTTP/1.1
Configuration-Context: https://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
```

The Configuration-Context header is a URI that MUST conform to the following ABNF grammar [[!ABNF]]:

        SP = " "
        HTAB = %x09
        WSP = SP / HTAB

        header = config-context
        config-context = "Configuration-Context:" *WSP URI

Where the term URI is defined in [[!URI]].

Syntax of the query string for configuration context:

?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 [[!OSLCCore3]].

A server MUST support both these methods of passing configuration context.

If a request contains both a header and a query string, the server MUST use the query string. Servers MUST reject requests that contain two or more different configuration contexts passed in query strings.

Where the Configuration-Context header is used on a request, a server SHOULD include in the response a header Vary=Configuration-Context so that different configuration contexts do not use a previously cached response.

Configuration Management servers SHOULD use the Access-Control-Allow-Headers header [[!CORS]] to allow the use of the Configuration-Context header in OSLC requests.

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.

If a configuration context is passed on a request for a non-versioned resource, the server MUST NOT treat that as an error, and MAY use that context to resolve references to embedded or related resources.

If a configuration context is passed on a request using the version URI for a versioned resource, a server MUST ignore the configuration context, even if that configuration context does not select that versioned resource.

The client is responsible for providing the correct configuration context to each request issued by that client at least where the relevant resource might be a versioned resource. If a resource returned from such a request contains links, the client should not assume the server has returned version-specific or configuration-specific links, and the client should 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. As noted later, the compact rendering returned for UI Previews is an exception to this rule.

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 should be defined by the specifications for such resource and link types; none are defined by this specification.

Default configuration

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

A server MAY include an oslc_config:configurationSettings link in the OSLC Service resource, referencing an oslc_config:ConfigurationsSettings resource. That resource MAY contain at most one oslc_config:defaultConfiguration property whose value is the URI of the default configuration to be used by that service.

An oslc_config:defaultConfiguration property with an rdf:nil value implies there is no default configuration, so requests with no context MUST fail.

Servers MAY support a PUT on oslc_config:ConfigurationsSettings resource as a way to set the default configuration. Servers MAY provide other ways for users to set the default configuration.

The absence of the oslc_config:defaultConfiguration has no implication as to the presence or absence of a default configuration.

Supported Operations on Components

A configuration server MUST support the following operations on components:

HEAD and OPTIONS: Retrieve information about the component
GET: Retrieve the current state of the component
GET on the component creation factory LDPC to find all components
GET on the configuration LDPC for a component to find all configurations (baselines and streams) of that component

A configuration server SHOULD support, and a global configuration server MUST support, the following operations on Linked Data Platform Containers:

POST to the component LDPC to create a new component. A successful response MUST contain a Location header providing the URI of the newly created component.
POST to the configuration LDPC for a component to create a new stream for that component, optionally specifying an initial baseline; if an initial baseline is not specified, a real or notional empty baseline is implied as the starting point for the stream. A successful response MUST contain a Location header providing the URI of the newly created component.

Servers SHOULD support the Prefer header for GET on LDPCs specifying PreferMinimalContainer:

Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMinimalContainer"

allowing a client to retrieve properties about the LDPC, including any oslc:resourceShape properties, without needing to retrieve all membership triples.

Servers MAY support OSLC selective properties on a GET, allowing a client to specify exactly which properties of those LDPCs are to be returned.

A configuration server SHOULD support, and a global configuration server MUST support one or more component creation factories declared in one or more OSLC service providers.

A configuration server SHOULD support one or more query capabilities for components.

Supported Operations on Versioned Resources in a Configuration Context

A configuration server 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 server:

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 MUST ignore the configuration context and return the specified version resource if it exists..
PUT: Update the state of a specified versioned concept resource in a specified stream or change set; this operation MAY cause the creation of a new version of the resource.

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

POST to a component in the context of a stream or change set, resulting in the creation of the first version of a new concept resource, or a new version of an existing resource. A successful response MUST include a Location header specifying the URI of the newly created resource.
DELETE: Delete the current mutable version resource in a specified stream or change set.

Creation of Baselines and Streams

When a new component is created by POSTing to the Component Container, an empty baseline for that component SHOULD be created automatically, and MUST be added to the oslc_config:configurations container for that component. The empty baseline has no contributions, no selections, and no branch.

Creation of Streams

A new stream is created by POSTing to the oslc_config:streams container for a baseline. By default, the new stream inherits (MUST copy) the component, contributions, and selections of the baseline, but does not inherit (MUST NOT copy) the branch property. Other properties MAY be inherited (copied) from the baseline, or MAY be set to server defaults. The POSTed data MAY include any of the following properties; if these properties are supported by the server, then the POSTed values for these properties MUST completely replace any default or inherited values:

dcterms:subject
dcterms:title *
dcterms:description
oslc:shortTitle *
oslc_config:branch
oslc_config:contribution
oslc_config:selections

The server MUST set the oslc_config:previousBaseline property of the new stream, and SHOULD set the prov:wasDerivedFrom property of the new stream, to reference the baseline owning the oslc_config:streams container.

A server MAY support one or more configuration creation factories declared in one or more OSLC service providers that create a stream for the component specified in the configuration's POSTED RDF body.

Creation of Baselines

A new baseline of a stream is created by POSTing to the oslc_config:baselines container for that stream. If the server determines that a suitable baseline already exists, the server MAY return a 303 with a Location header referring to that existing baseline; for an existing baseline to be suitable it MUST be for the same component, MUST have the same oslc_config:branch value, if any, MUST select the same version resources, each contribution MUST be a suitable baseline for the corresponding stream contribution, and there must be no additional or missing contributions.

Where a new baseline is created, that new baseline inherits (MUST copy) the following properties of the stream:

oslc_config:branch
oslc_config:component
oslc_config:contribution
oslc_config:selections
oslc_config:previousBaseline

Other properties MAY be inherited (copied) from the stream, or MAY be set to server defaults. The POSTed data MAY include any of the following properties; if these properties are supported by the server, then the POSTed values for these properties MUST completely replace any default or inherited values:

dcterms:subject
dcterms:title *
dcterms:description
oslc:shortTitle *

When creating a new baseline from a stream, after copying all previous values of the previousBaseline to the new baseline, the server MUST replace all those previousBaseline properties on the stream by a single reference to the newly created baseline. The chain of previousBaseline links thus shows the history of baselines of a stream.

The server MUST set the oslc_config:baselineOfStream property of the new baseline to reference the stream owning the oslc_config:baselines container.

Since all contributions to a baseline must themselves be baselines, creation of a baseline requires that a server MUST first create or obtain baselines for the current state of all stream contributions, recursively downward through the contribution graph. See Long Operations.

Concerns common to streams and baselines

* A server MAY adjust the name properties of a configuration to maintain any name uniqueness constraints; a server SHOULD NOT fail creation of a baseline or stream just because the requested name is not unique.

The server MAY ignore any additional properties, or MAY return an error if those properties are considered incompatible with the creation request.

Any properties required on new streams or baselines not defined by this standard MUST be described in resource shapes referenced by oslc:resourceShape properties on the container.

Servers SHOULD support the Prefer header for GET on those LDPCs specifying PreferMinimalContainer:

Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferMinimalContainer"

allowing a client to retrieve properties about the LDPC, including any oslc:resourceShape properties, without needing to retrieve all membership triples. Servers MAY support OSLC selective properties on a GET, allowing a client to specify exactly which properties of those LDPCs are to be returned.

Contributions and Overrides

Global configurations, and possible other types of configuration, support aggregation of multiple configurations, using the oslc_config:Contribution resource. Changes to contributions are made using PUT. For change sets, and possibly other use cases, a configuration or contribution can override another configuration contributed to the overall hierarchy. An override relationship may be specified at the configuration level (for change sets that apply to a specific base configuration) or at the contribution level (allowing a hierarchy where some contributions may override others without modifying the properties of potentially shared configurations).

When adding a contribution, if the configuration being added has an oslc_config:overrides relationship, that relationship MUST be copied to the contribution.
If the configuration being added has no OSLC overrides - it is a reusable configuration - a client MAY include an oslc_config:overrides relationship in a PUT to the contribution resource.
Servers MAY require an overriding configuration to be for the same component as the overridden contribution.
Servers MAY report an error if the configuration identified in the oslc_config:overrides property does not exist in the hierarchy for the context configuration.

Version Resolution

When a request is made for a versioned resource in the context of a configuration:

if there is no version of that resource in any of the selections in the contributions to the context configuration, nor in any of the selections in their recursive contributions, the request MUST fail with a 404 Resource not found (note that this includes unbound selections from a selection with type oslc_config:UnboundSelections)
if there is exactly one version of that resource in the union of the selections in the recursive contributions, the request MUST return that one version
if there is more than one version of that resource in the union of the selections in the recursive contributions, the behavior is implementation-defined, but SHOULD be well-defined in that the successive requests in the same configurations with the same selections SHOULD resolve to the same version. A server MAY perform an ordered search using the oslc_config:contributionOrder property, and MAY have a way to indicate multiple possible version resolutions.
The oslc_config:contributionOrder property is defined as a string rather than an integer to make it easier for servers to insert new contributions into an existing set without having to adjust the order value of existing contributions.

During this version resolution, overrides for entire configurations MUST be taken into account. If a contribution is marked as an override and the overriding configuration is earlier in the ordered set of all recursive contributions than the overridden configuration, the overridden configuration and all its contributions MUST be ignored in their entirety. Servers MAY report an error if an overriding configuration is later in the ordered set of all recursive contributions than the overridden configuration.

Overrides from change set configurations MUST also be taken into account. If a change set removes a selection for a versioned resource in the overridden configuration, and no other selection is provided for that resource in some other configuration, then the request MUST fail with a 404 Resource not found. If a change set replaces a selection for a versioned resource in the overridden configuration, and no other selection is provided for that resource in some other configuration, the request MUST return the version in the change set selection.

Implementations SHOULD provide documentation on their version resolution behavior.

Change Sets

Some systems use change sets to group related changes, or changes to multiple resources that must be kept together. Change sets may be represented using a configuration of type oslc_config:ChangeSet - a special type of stream. Each oslc_config:ChangeSet resource is related to exactly one base configuration (either a stream or a baseline), using the oslc_config:overrides property. A oslc_config:ChangeSet has either a complete set of replacements for the versions selected by that base configuration, or a set of changes - a delta. The configuration defined by a change set thus identifies both the 'before' state (the base configuration that is overridden by this change set), and the 'after' state defined by the change set configuration itself.

Systems that allow multiple change sets to be applied to a single base configuration should represent each such internal change set as an oslc_config:ChangeSet resource using the same value of oslc_config:overrides; the property prov:wasDerivedFrom should be used to provide a complete or partial ordering of such change sets. Servers may also synthesize a combined oslc_config:ChangeSet resource representing the overall effect of multiple internal change sets.

When a change set is based on a stream (the oslc_config:overrides property on an instance of an oslc_config:ChangeSet refers to a configuration of type oslc_config:Stream), then the 'before' state is mutable, and may not represent the state at the time the change set was created. Servers can avoid this lack of precision by ensuring either that all changes made to a stream are captured in a change set based off that stream, or that the stream's oslc_config:selections properties accurately represent the sets of changes delivered to that stream before any of the change sets based on that stream (those change sets probably representing changes still pending for the stream).

Since the shape for a change set allows only a single value for oslc_config:overrides, systems that allow a single change set to be applied to multiple base configurations need to represent that internal change set by multiple oslc_config:ChangeSet resources. These copies may be associated with each other using properties such as http://purl.org/datanode/ns#isCopyOf, dcterms:relation, or similar.

Delegated UIs

All configuration servers MUST provide a delegated user interface dialog for selection of configurations. A global configuration server MUST provide, and a local configuration server MAY provide, a delegated user interface 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=%3Chttps://example.com/configurations/globalConfig12%3E

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

Query Support

Configuration servers MAY support [[!OSLCQuery]] for configurations and components. If OSLC Query is provided, queries for the following properties using oslc.where and oslc.select SHOULD be supported:

dcterms:title
dcterms:created
dcterms:subject
rdf:type
oslc_config:component
oslc_config:contribution{oslc_config:configuration}
oslc_config:baselineOfStream

Query for other properties MAY be supported.

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

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

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

https://example.com/configs?oslc.where=oslc_config%3AbaselineOfStream%3D%3Chttps%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

Servers that support query capabilities on versioned resources MUST support the use of a configuration context to limit the query results to the versions selected by that configuration context, or to unversioned resources. The configuration context MUST support reference of a global configuration, or a configuration from this server.

Matching Contributions

Certain types of streams accept only certain other types of configurations as contributions. A global stream MUST accept any suitable configuration (baseline or stream) from an arbitrary configuration server, while a stream from some non-global server might accept only configurations from the same server. For a non-global server, some configurations may be acceptable as contributions to global streams, while other non-global configurations are valid only as a contribution to a broader scoped stream from that same server.

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

The parent has an oslc_config:accepts property whose value matches one of the types of the child configuration, AND
The child has an oslc_config:acceptedBy property whose value matches one of the types of the parent configuration.

A configuration type matches another type if they are the same type, or if the parent type is oslc_config:Configuration and the child type is either oslc_config:Baseline or oslc_config:Stream. No other form of inference is required, but servers MAY use inference through properties such as owl:sameAs and rdfs:subClassOf to extend the definition of matching configuration types.

A configuration is 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 stream is 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 is 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.

A stream with an oslc_config:accepts property with the value oslc_config:Baseline accepts only baselines in changes to its set of contributions. A server MAY use this to indicate a stream being used to stage the progressive construction of a baseline, where any initial stream contributions are gradually replaced by baselines as they become available.

Since baselines are immutable, their contributions (if any) are immutable, derived from the streams from which those baselines were created, so the oslc_config:accepts property is not meaningful and may be omitted.

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

Servers MAY treat the oslc_config:accepts and oslc_config:acceptedBy as server-generated read-only properties, not modifiable by a client.

Servers MAY perform validation of oslc_config:acceptscode> and oslc_config:acceptedBy. If a server performs such validation, it MAY limit validation to new contributions being added or defined for the first time.

Introduction

References

Service Discovery

Component and Configuration Constraints

Resource shape for Component

Resource shape for Baseline

Resource shape for Stream

Resource shape for ChangeSet

Resource shape for Contribution

Resource shape for Selections

Resource shape for ChangeSet Selections