diff --git a/specs/config/README.md b/specs/config/README.md index 28d18443..873d31ec 100644 --- a/specs/config/README.md +++ b/specs/config/README.md @@ -3,6 +3,8 @@ This directory contains the source files for the OSLC Configuration Management Specification, which is one of the work products of the OASIS OSLC Open Project. +Version 1.1 extends OASIS Standard version 1.0 with change set delivery and history. + Earlier draft revisions of this specification were work products of the OASIS OSLC Core Technical Committee, and may be found in the [OASIS OSLC Core TC SVN repo](https://tools.oasis-open.org/version-control/browse/wsvn/oslc-core/trunk/specs/config/). diff --git a/specs/config/Resources/OSLC Configuration Management Delivery and Delivery History.pdf b/specs/config/Resources/OSLC Configuration Management Delivery and Delivery History.pdf new file mode 100644 index 00000000..784e3b61 Binary files /dev/null and b/specs/config/Resources/OSLC Configuration Management Delivery and Delivery History.pdf differ diff --git a/specs/config/config-resources.html b/specs/config/config-resources.html index d82146c6..7372e0b7 100644 --- a/specs/config/config-resources.html +++ b/specs/config/config-resources.html @@ -6,25 +6,25 @@ name="description" content="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)." /> - OSLC Configuration Management Version 1.0. Part 3: Configuration Specification + OSLC Configuration Management Version 1.1. Part 3: Configuration Specification +
@@ -243,6 +251,17 @@

Resource shape for ChangeSet

data-include-format="html" >
+
+

Resource shape for ChangeSetDelivery

+
+

Resource shape for Contribution

Supported Operations on Versioned Resources in a Configuration Context
  • 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? +

    +
    +

    Delivering change sets using a creation factory

    +

    + There are several key aspects of change set delivery that OSLC Configuration Management should support: +

    +
      +
    1. Delivery is atomic. Either all the changed/new/removed resources are delivered, or none are.
      2. +
    2. A delivery might be a long-running operation.
      3. +
    3. + Delivery of a change set should not result in an earlier change being lost. A conflict arises when a change + set applies changes on top of version X of an object, whereas the target stream has changes on top of + version X+N of that object. +
      4. +
    +

    + An OSLC server would declare an OSLC Creation Factory for rdf:type + oslc_config:ChangeSetDelivery in some OSLC service that was discoverable from an OSLC Service + Provider Catalog. The declaration of that creation factory SHOULD reference a resource shape that is + compatible with oslc_config:ChangeSetDelivery. +

    +

    + A client would perform a POST with an RDF body conformant with the resource shape. The server would respond + with one of: +

    +
      +
    1. + 201 Created, with the response including a Location header of the new + oslc_config:ChangeSetDelivery resource that was created. This might be the case for a server + where the operation is quick to execute. +
      2. +
    2. + 400 Bad request, if the request was invalid. For example, missing source configuration or + target stream in the POSTed content. +
      3. +
    3. + 409 Conflict, if the delivery could not be made because of a conflict between the change set + and the target stream. +
      4. +
    4. + 303 See other, including a Location header of an existing delivery if the change set was + already delivered to the target stream. +
      5. +
    5. + 202 Accepted, with the response including a Location header 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. +
      6. +
    +
    +
    +

    Delivery Conflicts

    +

    + If the delivery of a change set would result in the loss or overwriting of a later change to the same object, + the delivery MUST fail and report a conflict. The corresponding oslc:Error should provide + sufficient information for a client to understand the nature of the conflict. For each conflict, the + corresponding oslc:Error should provide a statement using + oslc_config:ChangeSetDeliveryConflict to an inline resource of implied type + oslc_config:ChangeSetDeliveryConflict with the following resource shape: +

    +
    +

    + OSLC Configuration Management does not specify any means to resolve such conflicts, or to preview a delivery + to identify potential conflicts without committing the delivery. Conflicts are expected to be resolved using + the tool’s UI and/or non-OSLC defined APIs. +

    +
    +
    +

    Change Set Delivery History

    +

    + There are several common uses cases for finding information about change set deliveries: +

    + +

    + OSLC Query Capability is used to access change set delivery history. Servers SHOULD provide a query capability + for rdf:type oslc_config:ChangeSetDelivery in some OSLC service that is discoverable from an OSLC + Service Provider Catalog. The declaration of that query capability SHOULD reference a resource shape describes + the LDP query results container (as per the OSLC Query specification), which in turn provides a value resource + shape for its members that is compatible with oslc_config:ChangeSetDelivery. +

    +

    Some example queries include:

    + + + + + + + + + + + + + + + + + + + + + +

    + Clients that want to find the files changes associated with a delivery would do so through the referenced + change set. Query capabilities MAY support nested query properties in oslc.select. For example, + an unencoded oslc.select value of + dcterms:title,dcterms:created,oslc_config:sourceConfiguration, oslc_config:sourceConfiguration + {dcterms:title,oslc_config:selections{oslc_config:selects}} + might return the delivery title, when it was delivered, the URI of the change set, the title of the change + set, and the URIs of the files changed in the change set. +

    +
    DescriptionUnencoded oslc.where expression
    Find the delivery for a specified change set and target streamoslc_config:sourceConfiguration={changeSetUri} and oslc_config:targetStream={streamUri}
    Find the deliveries for a specified change set to any streamoslc_config:sourceConfiguration={changeSetUri}
    Find the deliveries for all change sets to a specified target streamoslc_config:targetStream={streamUri}
    Find the deliveries for all change sets to a specified target stream since 1st January 2023oslc_config:targetStream={streamUri} and dcterms:created >= "2023-01- 01'T'00:00:00"^^xsd:dateTime
    +
    +
    +

    Change Set Delivery Persistence

    +

    + The persistence of delivery information is a server implementation choice. In servers where there is a + corresponding persisted object, a server might map such objects to delivery objects. In servers where there is + no first-class object representing a delivery, the delivery might be constructed from querying internal data. +

    +
    +
    +

    Creation of Baselines and Streams

    @@ -726,11 +907,11 @@

    Version Resolution

    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 + 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 @@ -739,10 +920,10 @@

    Change Sets

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

    @@ -757,11 +938,12 @@

    Change Sets

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

    diff --git a/specs/config/config-shapes.ttl b/specs/config/config-shapes.ttl index 60580549..e1e5e010 100644 --- a/specs/config/config-shapes.ttl +++ b/specs/config/config-shapes.ttl @@ -25,7 +25,7 @@ @prefix rdfs: . @prefix xsd: . -@prefix : . +@prefix : . : a oslc:ResourceShapeConstraints ; @@ -33,9 +33,9 @@ dcterms:title "Resource Shapes for OSLC Configuration Management" ; dcterms:description "Shapes for resources defined by OSLC Configuration Management."^^rdf:XMLLiteral ; dcterms:publisher ; - dcterms:source ; - dcterms:isPartOf ; - dcterms:hasVersion "PS" ; + dcterms:source ; + dcterms:isPartOf ; + dcterms:hasVersion "PSD" ; dcterms:license ; dcterms:issued "2023-07-23"^^ ; dcterms:dateCopyrighted "2012-2023" . @@ -931,6 +931,111 @@ or to a change set that include both a `oslc_config:RemoveAll` and a `oslc_confi {{servers MAY treat occurrences of potentially conflicting selections as an error}}."""^^rdf:XMLLiteral ] . +:ChangeSetDeliveryShape + a oslc:ResourceShape ; + oslc:describes oslc_config:ChangeSetDelivery ; + dcterms:title "The shape of a ChangeSetDelivery." ; + dcterms:description """A ChangeSetDelivery is a resource representing the delivery of a single change set to a single target stream."""^^rdf:XMLLiteral ; + + oslc:property + + [ + a oslc:Property ; + oslc:name "type" ; + oslc:propertyDefinition rdf:type ; + oslc:occurs oslc:One-or-many ; + oslc:representation oslc:Reference ; + oslc:valueType oslc:Resource ; + oslc:range rdfs:Class ; + dcterms:description """A resource type URI. +{{A change set delivery MUST have at least the resource type `oslc_config:ChangeSetDelivery`}}. +Clients may infer a resource type of `oslc_config:ChangeSetDelivery`, +but there is no requirement for servers to materialize this triple in the RDF representation. +."""^^rdf:XMLLiteral + ] , + [ + a oslc:Property ; + oslc:name "sourceConfiguration" ; + oslc:propertyDefinition oslc_config:sourceConfiguration ; + oslc:occurs oslc:Exactly-one ; + oslc:representation oslc:Reference ; + oslc:valueType oslc:Resource ; + oslc:range oslc_config:ChangeSet ; + dcterms:description """A reference to a resource identifying the change set that was +delivered. This cannot be modified after creation."""^^rdf:XMLLiteral + ] , + [ + a oslc:Property ; + oslc:name "targetStream" ; + oslc:propertyDefinition oslc_config:targetStream ; + oslc:occurs oslc:Exactly-one ; + oslc:representation oslc:Reference ; + oslc:valueType oslc:Resource ; + oslc:range oslc_config:Configuration ; + dcterms:description """A reference to a resource identifying the stream to which the +change set was delivered. This cannot be modified after creation."""^^rdf:XMLLiteral + ] , + + :created , + :creator , + :description , + :identifier , + :instanceShape , + :modified , + :modifiedBy , + :shortId , + :shortTitle , + :subject , + :title . + + +:ChangeSetDeliveryConflictShape + a oslc:ResourceShape ; + oslc:describes oslc:Error ; + dcterms:title "The shape of a ChangeSetDeliveryConflict." ; + dcterms:description """A ChangeSetDeliveryConflict is a resource representing a conflict error in the delivery of a single change set to a single target stream."""^^rdf:XMLLiteral ; + + oslc:property + + [ + a oslc:Property ; + oslc:name "type" ; + oslc:propertyDefinition rdf:type ; + oslc:occurs oslc:One-or-many ; + oslc:representation oslc:Reference ; + oslc:valueType oslc:Resource ; + oslc:range rdfs:Class ; + dcterms:description """A resource type URI. +{{A change set delivery conflict MUST have at least the resource type `oslc_config:ChangeSetDeliveryConflict`}}. +Clients may infer a resource type of `oslc_config:ChangeSetDeliveryConflict`, +but there is no requirement for servers to materialize this triple in the RDF representation. +."""^^rdf:XMLLiteral + ] , + [ + a oslc:Property ; + oslc:name "sourceVersionResource" ; + oslc:propertyDefinition oslc_config:sourceVersionResource ; + oslc:occurs oslc:Exactly-one ; + oslc:representation oslc:Reference ; + oslc:valueType oslc:Resource ; + oslc:range oslc_config:VersionResource ; + dcterms:description """The version resource in the source +configuration that is in conflict."""^^rdf:XMLLiteral + ] , + [ + a oslc:Property ; + oslc:name "targetVersionResource" ; + oslc:propertyDefinition oslc_config:targetVersionResource ; + oslc:occurs oslc:Exactly-one ; + oslc:representation oslc:Reference ; + oslc:valueType oslc:Resource ; + oslc:range oslc_config:VersionResource ; + dcterms:description """The version resource in the target +stream that is in conflict."""^^rdf:XMLLiteral + ] . + + + # ============================ Activity shape ============================ :ActivityShape diff --git a/specs/config/config-vocab.html b/specs/config/config-vocab.html index 469eb4fc..f1d55a9c 100644 --- a/specs/config/config-vocab.html +++ b/specs/config/config-vocab.html @@ -3,25 +3,25 @@ - OSLC Configuration Management Version 1.0. Part 4: RDF Vocabulary + OSLC Configuration Management Version 1.1. Part 4: RDF Vocabulary