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

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.

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

        SP = " "
        HTAB = %x09
        WSP = SP | HTAB

        header = config-context
        config-context = "Configuration-Context:" *WSP 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.

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 Configurations

A configuration server MUST support the following operations on configurations:

• HEAD and OPTIONS: Retrieve information about the configuration
• GET: Retrieve the current state of the configuration

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

• PUT on a configuration resource to update the tags
• PUT on a configuration resource and its inline Contribution resources to update the set of contributed configurations
• DELETE a configuration; servers MAY refuse to delete configurations that are part of or referenced by existing baselines.

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

Since baselines are normally linked into a provenance chain using the oslc_config:previousBaseline property, servers MAY 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.

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

Supported Operations on Selections

A configuration server MUST support the following operations on selections resources:

• HEAD and OPTIONS: Retrieve information about a selections resource
• GET: Retrieve the current state of a selections resource

Servers may treat selections resources as read-only.

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.

Supported Operations on Change Set Delivery

A change set delivery represents the delivery of a single change set to a single target stream. If multiple change sets are to be delivered, each would be done as a separate delivery.

Servers MUST support a GET of a delivery object URI. The response should include an Etag header.

Servers SHOULD support a HEAD on a delivery object URI. The response should include an Etag header

Delivery objects MAY be immutable, or a server might permit the title to be changed. If a server allows the title to be changed, it SHOULD support a PUT with If-Match header. Servers MAY silently ignore any data that cannot be changed, such as read only properties, or oslc_config:sourceConfiguration or oslc_config:targetStream.

POST SHOULD NOT be supported. A new object can only be created through a creation factory. See the next section: Delivering change sets through a delivery creation factory.

DELETE MAY be supported, but if a server does support it, the semantics of that deletion are undefined. For example, does deleting a delivery remove the change set from the target stream?

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.

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

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:

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

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 [[!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:

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.

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.

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.