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

Introduction

References


Service Discovery

A configuration server SHOULD implement [[OSLCCore3]] ServiceProvider and Service resources, where an oslc:domain property has the value http://open-services.net/ns/config#. A global configuration service resource, if provided, SHOULD include the property oslc:usage with the value http://open-services.net/ns/config#globalConfigurationService. A service with this usage property MUST provide all global configuration capabilities described as mandatory in this specification.

Component Container

Configuration Management servers MUST provide a single Linked Data Platform Container (LDPC) for all components in that server.

This component container MUST be advertised as an [[OSLCCore3]] Creation Factory in the Service resource for the configuration server. This creation factory SHOULD provide a resource shape describing the shape of components that can be created; if any properties beyond those described in this standard are required to create components, then a resource shape MUST be provided.

Component and Configuration Resource Shapes

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

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:

TBD - define syntax of Configuration-Context header by referring to IETF RFC.

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.

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.

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. The absence of the oslc_config:defaultConfiguration has no implication as to the presence or absence of a default configuration. 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.

Supported Operations on Components

A configuration server MUST support the following operations on components:

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

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.

Supported Operations on Configurations

A configuration server MUST support the following operations on configurations:

A configuration server SHOULD support, and a global configuration server MUST support, the following operations on configurations:

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

Since servers may support deletion of baselines, clients must not assume that references to baselines can be resolved; like any other resource, clients must be prepared to handle 404 errors. Since baselines are normally linked into a provenance chain using the oslc_config:previousBaseline property, servers may elect to leave a stub resource (one with a minimal set of properties) behind instead of truly deleting a baseline. Servers SHOULD add the property oslc:archived=TRUE on a reduced form of a partially deleted baseline.

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:

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:

Creation of Baselines and Streams

When a new component is created by POSTing to the Component Container, an empty baseline for that component MUST be created automatically, and 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:

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.

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:

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:

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

Version Resolution

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

  1. 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)
  2. 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
  3. 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 from change set configurations MUST 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=%3Chttp://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.

Compact Rendering

Configuration servers SHOULD implement [[OSLCCore3]] UI Previews and compact rendering.

Where implemented, clients MUST pass any required configuration context on the initial request for a compact resource, and the configuration server MUST return a compact resource honoring that configuration context. Moreover, the icon reference, the large preview reference, the small preview reference, and any image or intra-page 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 selected by the given configuration, or a concept resource URI with a configuration query string that resolves to the versioned resource selected by the given configuration.

Tracked Resource Sets

A configuration server SHOULD provide one or more Tracked Resource Sets for configurations, contributions, and components. A configuration server MAY publish selections and versioned resources in a Tracked Resource Set (TRS); URIs for versioned resources in the base and change log of the TRS MUST be version resource URIs.

Query Support

Configuration servers MAY support [[OSLCCore3]] Query for configurations and components. TBD: That reference must be changed to refer to OSLC Core 3.1 once that is published, since query is not in 3.0. If OSLC Query is provided, queries for the following properties using oslc.where and oslc.select SHOULD 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 encoded, 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

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 may 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:

  1. The parent has an oslc_config:accepts property whose value matches one of the types of the child configuration, AND
  2. 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.

Long Operations

Some operations (for example, creating a baseline from a large hierarchy of streams) can take a long time to complete. Servers MAY use the standard HTTP response 202 Request Accepted to indicate that a request has been accepted, but may not yet be complete. The content and location header of this 202 response MUST be that of an oslc_config:Activity resource, indicating the progress or result of that activity. Clients SHOULD poll the Activity resource periodically until the state indicates it has finished.

Each Activity resource MUST be persisted by a server (including over a restart) for a minimum of 24 hours after completion of the long operation as a whole, or until explicitly deleted by a client.

Clients SHOULD delete each Activity created by a long-running operation soon after the client has seen the completion of the activity, or when the client is no longer interested in the result. Servers MAY deny clients access to delete Activity resources including but not limited to activities still in progress, or activities not created by that client, or MAY require clients to have a specific role or permission to delete activities.