This wiki is locked. Future workgroup activity and specification development must take place at our new wiki. For more information, see this blog post about the new governance model and this post about changes to the website.
OSLC_logo.png

Software Configuration Management 1.0 Specification

Status: 1.0 Specification (in finalization)

This Version

Latest Version PreviousVersion Author Contributors

License

88x31.png
This work is licensed under a Creative Commons Attribution License.

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

Table of Contents

Introduction

This section is informative.

Software Configuration Management covers a wide range of practices, including tracking and controlling changes in the software using version control, building software and creating baselines, reporting on the contents of such builds and baselines, establishing traceability from requirements and change requests to software revisions, etc. This specification defines a set of RESTful interfaces using representations of resources, content types, the basic HTTP 1.1 methods and response codes. The capabilities of the interface definitions are driven by key integration scenarios and do not represent a complete set of operations on resources or resource types; service providers are neither required nor expected to expose their complete data model and application logic.

This version of the OSLC SCM specification describes services to browse the contents of baselines and change sets, and the version-controlled resources associated with those baselines and change sets. Clients may inspect the properties of these resources, and find differences between two such resources. No services are defined for the creation, modification, or deletion of resources.

Base Requirements

Compliance

This specification is based on the OSLC Core Specification 2.0. OSLC SCM 1.0 providers MUST be compliant with both the core specification 2.0 and this SCM 1.0 specification, and SHOULD follow all the guidelines and recommendations in both these specifications. As a result of following these requirements and recommendations, OSLC SCM 1.0 providers SHOULD also be compliant with the Reporting Specifications.

The following table summarizes the requirements from OSLC Core Specification as well as some additional specific to SCM, qualifying some of the requirements from the OSLC Core Specification. See further sections in this specification or the OSLC Core Specification to get further details on each of these requirements.

Requirement Level Meaning
Unknown properties and content MAY / MUST OSLC services MAY ignore unknown content and OSLC clients MUST preserve unknown content
Resource Operations MUST OSLC services MUST support resource operations via standard HTTP operations
Resource Paging MAY OSLC services MAY provide paging for resources but only when specifically requested by the client
Partial Resource Representations SHOULD OSLC services SHOULD support request for a subset of a resource's properties via the oslc.properties URL query string retrieval via HTTP GET
Service Provider Resources SHOULD / MUST OSLC service providers SHOULD provide at least one Service Provider Catalog and MUST provide a Service Provider resource for each service provider
Query Capabilities MUST OSLC service providers MUST provide query capabilities to enable clients to query for resources, via HTTP GET
Query Syntax SHOULD / MAY OSLC query capabilities SHOULD support the extended subset of the OSLC Core Query Syntax defined in this specification, and MAY use other query syntax
Delegated UI Dialogs SHOULD OSLC services SHOULD offer delegated UI selection dialogs specified via service provider resource
HTTP Basic Authentication MAY OSLC services MAY support Basic Auth, over http and/or https
OAuth Authentication SHOULD / MAY OSLC services SHOULD support OAuth and MAY indicate the required OAuth URLs via the service provider resource
Error Responses SHOULD OSLC services SHOULD provide error responses using Core defined error formats
RDF/XML Representations MUST OSLC services MUST provide an RDF/XML representation for responses to HTTP GET requests and queries requesting this representation. OSCL SCM service providers are not restricted to use of the constrained RDF/XML subset.
JSON Representations MUST OSLC services MUST provide JSON representations that conform to the Core Guidelines for JSON in response to HTTP GET requests and queries requesting this representation.
Other Representations MAY OSLC services MAY provide other representations if requesting, such as HTML.

Specification Versioning

See OSLC Core Specification Versioning section.

OSLC SCM 1.0 Service providers MUST respond to all client requests with a representation that complies with this SCM 1.0 specification, including an OSLC-Core-Version header with a value of 2.0, regardless of the version (if any) requested by the client.

Clients SHOULD provide at least the desired OSLC-Core-Version value in the headers of their requests, and SHOULD handle the returned versions as follows:

  1. If no version headers are provided in the response (the provider being non-compliant), the client MAY assume the requested version was returned, or MAY fail.
  2. If version headers are returned and the client understands these versions, the client SHOULD process the data accordingly.
  3. If version headers are returned, but the client does not understand these versions, the client MAY process any data it does understand, or MAY fail.

Namespaces

In addition to the namespace prefixes oslc, rdf, and dcterms described in the core specification, this specification uses a domain-specific namespace of http://open-services.net/ns/scm# with a default prefix of oslc_scm, and the RDF Schema namespace http://www.w3.org/2000/01/rdf-schema# with the prefix rdfs.

Resource Representations and Properties

SCM services MUST support both RDF/XML and JSON resource representations, and MAY support other representations. For RDF/XML representations, the returned content type MUST be application/rdf+xml; for JSON representations the content type MUST be application/json.

A normal GET request on any SCM resource MUST return the full base resource, with all the properties of that resource. These properties SHOULD include the properties defined in this specification, and MAY include additional provider-specific properties; providers SHOULD use their own namespaces for such properties, or use standard Dublin Core or RDF namespaces and properties where appropriate.

Clients may request derived resources with a subset of the base resource properties, using the OSLC Core Specification oslc.properties syntax. Since some base resources may have a very large number of properties and some properties may be very large and/or expensive to compute, consumers are strongly encouraged to access derived resources, limiting the properties to the subset required.

Pagination

SCM services SHOULD support paging; stable paging is not required.

Closure over links

The SCM data model is one with an arbitrarily nested structure. In order to allow consumers efficient access to hierarchic data such as a tree of directories and files in a baseline, SCM extends the OSLC Core definition of oslc.properties as follows.

nested_prop       ::= link_property closure? "{" member_properties "}"
closure           ::= "*" | "!"
link_property     ::= property
member_properties ::= properties

A nested property requested with the "*" closure option provides unlimited transitive closure over the named link property - so for example oslc.properties=rdfs:member*{dcterms:name} indicates that the members of the subject resource should be fetched, and the members of those members, recursively, until all members have been found, and that the dcterms:name property of the subject resource and of each of these members should be shown. Providers SHOULD detect cycles in the graph rather than failing or returning a never-ending response.

A nested property requested with the "!" closure option provides a potentially limited closure. The semantics are the same as for "*" except that the scope of the closure is limited and determined by the operation and the provider, as defined below.

SCM providers SHOULD support the closure syntax with the oslc.properties query string when used with rdfs:member as the link property, and MAY also support this closure syntax with other link properties and/or on the oslc.select query string.

Configuration Context

A single object in an SCM repository MAY be represented by more than one OSLC SCM resource - so the resources returned from two or more different URIs might represent the same underlying SCM object, and might have the same identity property. Two different OSLC SCM resources MAY represent the same SCM object seen in a specific context; in such cases, the two different resources MAY show different properties other than the identity property. For example, a single version of an SCM object representing a file system directory might have different members in different configuration contexts, in which case different resources would be used to represent the directory version in each context, and these multiple resources would have the same value for the dcterms:identifer property, but might have different rdfs:member properties.

The URI's returned as values for the member property of an SCM baseline or configuration SHOULD already imply that baseline or configuration as a context. For URI's obtained in other ways, a client can construct the URI for a resource representing the same underlying SCM object in some specific context by adding the oslc_scm.context query string and the context URI to the base URI. If the given object does not appear in that context, there is no such resource, and a GET would fail with the normal 404 error.

oslc_scm.context  ::= "oslc_scm.context=" uri_ref_esc

Example:

 GET http://synergyserver:8888/oslc/directory/src/17/7.2?oslc_scm.context=configuration/src/17/7.2&oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,rdfs:member*{dcterms:name,oslc_scm:status} 

Resource Comparison

As defined later in this specification, a client can request the construction of a resource representing the difference between two other resources, by appending the oslc_scm.delta query string to the URI of the first resource to be compared; the second resource is identified either by an explicit URI in the oslc_scm.delta value, or implicitly by the provider if no URI value is given.

oslc_scm.delta ::= "oslc_scm.delta" | "oslc_scm.delta=" uri_ref_esc

Example:

 GET http://synergyserver:8888/oslc/baseline/2010-02-16_12:13:08_4532?oslc_scm.delta=oslc/baseline/2010-01-27_10:23:17_3891 

OSLC SCM Resources

SCM services MUST accept well-formed GET and HEAD requests on the resources defined in this section. On these requests, SCM services SHOULD support optional use of the oslc.properties query string, and the closure of properties over links, configuration context, and resource comparison URI search strings described in the previous section.

SCM services MUST support GET requests on the Query Capabilities resources defined later in this specification.

SCM services MAY fail to accept POST, PUT, and DELETE requests; if such requests are accepted, the semantics are not defined by this specification, but providers SHOULD map such requests to the logically equivalent create, update, and delete operations on SCM resources.

SCM Data Model

Definition of terms

Object version
A resource representing a specific version of an object that is being controlled in the SCM system. In some SCM systems, this concept is called a configuration item. Objects frequently represent files and directories, but might also represent other resources such as requirements, models, assets, etc. Note that providers might restrict resources of some types to having a single version - for example, frequently change sets have only a single version, whereas files typically might have many versions.
Configuration
A resource representing a set of object versions arranged in a hierarchy. A configuration has links to specific versions of any number of objects as immediate members forming the top level of the hierarchy. Each of those top-level objects versions may have links to any number of other object versions, with potentially a variety of containment relationships. For example, a configuration might contain a specific version of a file system directory object, and under that specific versions of any number of subdirectories and files.
The members of a configuration are defined as both the immediate top-level members and the members of those members, recursively, but excluding the members of any sub-configurations (members that are themselves configurations).
The contents of a configuration is not necessarily frozen; the contents of and properties of the members might change, and the versions of the members might change. Some providers might support only a single version of a configuration, other might support multiple versions of a configuration, with each version containing a different set of object versions, in a potentially different hierarchy. With some providers, directories can contain symbolic links and configurations (sub-configurations) as well as files and subdirectories. Providers may support other types of resources as members of a configuration, such as requirements, test cases, etc.
Baseline
A frozen configuration. If you look at the same baseline in the future, it will normally have the same members (not all providers can guarantee complete immutability - for example, administrative actions might modify data). In some providers, baselines might be able to contain other baselines, while with other providers that might not be possible. Some providers might support only a single version of a baseline.
Component
A configuration or set of configurations may be divided into components representing some user-defined set of object versions and/or sub-configurations; for example, components might be used to represent physical components or software modules. A provider is not required to implement components; they are used only as a way of limiting the scope of the closure over links. Components might or might not be resources; they might be dynamic sets of object versions chosen by other criteria such as property values. A provider can also treat each configuration and sub-configuration in a hierarchy as being separate components.
Change set
A set of changes to be made to one or more configurations, where each change is described in terms of members (direct or indirect) that should be added to, replaced in, or removed from some configurations.
Directory version or file version
A resource describing some specific version of a directory or file in the SCM system. Directories can contain files, subdirectories, and (in some providers) symbolic links and sub-configurations.
Directory or file
A resource representing all versions of some particular directory or file.
Symbolic link version
A kind of object version representing some specific version of a symbolic link, as used in UNIX file systems. A symbolic link holds a string property containing an absolute or relative file system path; this path might or might not point to a file system representation of some other SCM resource.

SCM services may restrict the set of members in a container in various ways. For example, the entries in one directory version may have to be unique. This specification does not define such restrictions, since they may not only vary between providers, but may also depend on the client or operating system used to view the configuration. For example, the names of files in a directory must be unique, but how uniqueness is determined varies between file systems: on UNIX, case is considered, while on Windows it is ignored, and on Mac OS X, files must be unique ignoring case using Unicode NFC.

The diagram below shows one possible data model using the above concepts, with directories and files as the objects in the SCM system. An SCM provider MAY allow other object types, with the same or different containment relationships; clients should not assume that any linked resource is an SCM object version or has some specific type (see Oslc Core Links). The arrows from change sets represent the 'has associated changed objects' relationship; all other arrows represent the common rdfs:member relationship. Although these relationships might be many-to-many in the underlying provider, OSLC SCM 1.0 services only expose one to many relationships.

OSLC_SCM_model.png

Common SCM Resource Properties

The following table shows properties that SHOULD be common to all SCM resources, unless otherwise specified for the resource types described below.

Prefixed Name Occurs Value-type Representation Range Description
OSLC Core properties
dcterms:title zero-or-one XMLLiteral n/a n/a Title (reference: Dublin Core) of the resource represented as rich text in XHTML content; this SHOULD include only content that is valid inside an XHTML <span> element. SCM providers SHOULD use this property for a human readable number, name, or synopsis of the object version.
dcterms:description zero-or-one XMLLiteral n/a n/a Descriptive text (reference: Dublin Core) about resource represented as rich text in XHTML content; this SHOULD include only content that is valid and suitable inside an XHTML <div> element. SCM providers SHOULD use this property for a human-readable description of the object version, or a comment about the change in this version of the object.
dcterms:creator zero-or-many Resource either any Creator or creators of resource (reference: Dublin Core). It is likely that the target resource is a foaf:Person but that is not necessarily the case.
dcterms:contributor zero-or-many Resource either any Contributor or contributors to resource (reference: Dublin Core). SCM resources often use this to show the current owner - the entity responsible for this resource. It is likely that the target resource is a foaf:Person but that is not necessarily the case.
dcterms:created zero-or-one DateTime n/a n/a Timestamp of resource creation (reference: Dublin Core)
dcterms:modified zero-or-one DateTime n/a n/a Timestamp of the latest resource modification (reference: Dublin Core)
rdf:type one-or-many Resource reference n/a The resource type URI
oslc:instanceShape zero-or-one Resource reference oslc:ResourceShape Resource Shape that specifies allowed and required fields. All persistent SCM resources SHOULD have an instance shape.
oslc:serviceProvider zero-or-one Resource reference oslc:ServiceProvider A link to the resource's OSLC Service Provider.
SCM properties
dcterms:identifier zero-or-one String n/a n/a An internal identifier, possibly assigned by the SCM system. All persistent SCM resources SHOULD have an identifier, and this identifier MUST be unique amongst all currently existing object versions from this service provider. The string is not necessarily intended to be conveniently readable to humans.
dcterms:name zero-or-one String n/a n/a A short name that is often used for an abbreviated identifier and used for presentation to end-users.
oslc_scm:fullName zero-or-one String n/a n/a A full human-readable name of the object, unique amongst all current existing object versions from this service provider.
oslc_scm:status zero-or-one String n/a n/a A string indicating the current status of the object version.
rdfs:member zero-or-many Resource reference any A member resource that is a member of the the given container. Where the container resource is an SCM object version (such as a Baseline, Configuration, or DirectoryVersion), the member resource is also typically an SCM object version. Note this property may have multiple values, to show multiple members of the parent object. Different resources representing the same underlying directory version but as seen in different contexts may have different member property values. Note that this property identifies objects that are direct members of the parent object, as opposed to those that are members of members; indirectly included object versions may be returned as nested properties, possibly using the closure syntax.

Change Set and Change

A change set is a unit of change in an SCM system. A change set might indicate object versions to be added to, replaced in, or removed from, a configuration. In most SCM systems, change sets are intended to be indivisible: either all of the associated changed object versions should be applied to a configuration, or none. Simple version control systems may not provide change sets. For SCM systems that do provide change sets, it is often impossible or an error to have a change set partially applied to a configuration. However, partially applied change sets are possible in many systems, due to manual intervention, conflicting dependencies, etc. Change sets have some properties of their own - for example, it is common to have an identifier for the change set, as well as some readable description of the purpose of the change. In some systems, a change set might be aggregated from several other change sets, perhaps representing a group of changes to be applied to some configuration.

Change sets often identify the modifications made for one logical change. For example, in languages such as C or C++, it would be common for a logical change to affect a header file that defines some API, and both the source file that implements the API and one or more source files where the API is used; a single change set can be associated with all these changes to ensure that they are applied as a unit.

In OSLC SCM, a change set contains zero or more Change resources; each Change describes a single object version that has been added to, replaced in, or removed from, a configuration; the exact nature of change may vary between providers. A Change MAY be obtainable as a separate resource, or a provider MAY represent Change resources purely as inlined properties of a change set.

Change sets may also be associated with specific stream or branches where that change is or should be applied.

Many SCM services provide only a single version of a change set.

Change Set Resource
Name ChangeSet
Type URI http://open-services.net/ns/scm#ChangeSet

Change Type
Name Change
Type URI http://open-services.net/ns/scm#Change

Change Set and Change Properties

A change set has the following properties in addition to the common SCM properties:

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:change zero-or-many Resource either oslc_scm:Change Either a local oslc_scm:Change property, or a reference to a Change resource. Providers MAY choose not to represent changes as gettable resources, but instead always inline this property.
oslc_scm:stream zero-or-many Resource reference any A reference to a resource defining the stream or branch to which this change set is or should be applied; this specification does not define the properties of a stream or branch resource. Note this property may have multiple values, to show multiple streams to which the change set might be applied.

A change has the following properties, and need not have any of the common SCM properties:

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:changeType zero-or-many String n/a n/a A string representing the nature of the change. The value and meaning of this string varies between providers. Providers that do not distinguish different types of change may omit this property.
oslc_scm:changedObject one-or-many Resource n/a n/a The object versions associated with this change; note there MUST be at least one such object version. Some SCM providers MAY represent rename operations by associating a change with two object versions; the oslc_scm:changeType string indicates this in some provider-specific manner.

Change Set Methods

A client uses the normal http GET or HEAD methods to request information about a change set. From the returned information, or using the oslc.properties nested property syntax, the client may retrieve information about the changes associated with this change set, and also the object versions immediately associated with those changes. Since many SCM systems require a configuration context to determine the specific versions of members of directories, it might not be possible to use the closure syntax to recurse any further down a hierarchy from a change set through associated directory versions to file and subdirectory versions.

Note that a change set might not be associated with any object versions (perhaps because the change set is in the process of being set up, or because the associated changes were deleted), in which case the oslc_scm:change property is absent.
Example:

 GET http://synergyserver:8888/oslc/changeset/1234?oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,oslc_scm:change{oslc_scm:changeType,oslc_scm:changedObject{dcterms:title,dcterms:description}} 

Rersources of the oslc_scm:Change type MAY be represented only as inlined resources within change set resources, and hence might not have URIs.

Baseline

One purpose of an SCM system is to maintain collections of specific versions of objects - for example, the exact set of sources (and often the build artifacts as well) that were used to construct a specific version of your software, or the exact set of chapter document versions that were used in some version of a book. This hierarchy of specific versions of a set of objects is called a configuration. In many SCM systems, the versions of members of a configuration may vary over time, so at one moment a book contains version 1 of chapter 2, and a few days later the configuration is updated to contain version 2 of chapter 2. To reproduce an earlier state for testing, or for audit trail reasons, etc., it is often important to have a permanent record of the state of a configuration at some specific point in time. This frozen record of a configuration is called a baseline. Not all providers can guarantee complete immutability of baselines - for example, administrative actions might modify data. In some providers, baselines might be able to contain other baselines, while with other providers that might not be possible.

As just described, a baseline is or contains a configuration, so a baseline has links to a fixed hierarchy of specific object versions. In many SCM systems, a baseline is also associated with the change sets used to construct that baseline; these change sets normally represent the difference between this baseline and some previous baseline (which might or might not still exist). Since change sets are often linked to other OSLC resources such as change requests, and directly or indirectly to requirements, a client might be able to report on the defects fixed in a baseline, or the requirements satisfied in a baseline.

An SCM provider might use an earlier baseline during the development and construction of a newer baseline, but not all SCM systems keep track of such previous baselines thereafter; for this reason, no 'baseline baseline' property is defined in this specification, but providers MAY supply such a property if appropriate.

Baseline Resource
Name Baseline
Type URI http://open-services.net/ns/scm#Baseline

Baseline Properties

A baseline has the following properties in addition to the common SCM properties:

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:build zero-or-many Resource reference any A reference to a resource defining a build; this specification does not define the properties of a build resource.
oslc_scm:stream zero-or-one Resource reference any A reference to a resource defining the stream or branch in which this baseline was created; this specification does not define the properties of a stream or branch resource.
oslc_scm:subBaseline zero-or-many Resource reference any A reference to a resource representing a sub-baseline contained in this baseline; note this property may have multiple values, to show multiple sub-baselines of the parent object. It is likely that the target resource is an oslc_scm:Baseline but that is not necessarily the case.
oslc_scm:changeSetAdded zero-or-many Resource either any A reference to a resource representing a change set added in this baseline; note this property may have multiple values, to show multiple changesets added in the baseline. It is likely that the target resource is an oslc_scm:ChangeSet but that is not necessarily the case.
oslc_scm:changeSetModified zero-or-many Resource either any A reference to a resource representing a change set modified in this baseline; note this property may have multiple values, to show multiple changesets modified in the baseline. It is likely that the target resource is an oslc_scm:ChangeSet but that is not necessarily the case.
oslc_scm:changeSetRemoved zero-or-many Resource either any A reference to a resource representing a change set removed in this baseline; note this property may have multiple values, to show multiple changesets removed in the baseline. It is likely that the target resource is an oslc_scm:ChangeSet but that is not necessarily the case.

Baseline Methods

A client uses the normal http GET or HEAD methods to request information about a baseline. From the returned information, or using the oslc.properties nested property syntax, the client may retrieve information about the members of this baseline and the change sets associated with it.. Recursion down through the rdfs:member relationship (such as a configuration/directory/file hierarchy) is possible using the closure syntax. Limited closure using the "!" closure operator may stop at a component boundary, as defined by the service provider.
Example:

GET http://synergyserver:8888/oslc/baseline/2010-02-16_12:13:08_4532?
         oslc.properties=oslc_scm:changeset{dcterms:title,dcterms:description},
         rdfs:member!{dcterms:name,dcterms:title,oslc_scm:status}

Baseline Comparison

By adding the oslc_scm.delta query string to a baseline URI, a client can request a new resource representing the difference between the subject baseline and some other resource; the request MAY fail if the second resource is not also an SCM baseline.

If the optional URI value is provided, it provides the URI of the baseline that is to be compared with the subject baseline. If no URI is provided, the service provider determines an appropriate predecessor baseline . By default, OSLC SCM providers MUST return a BaselineComparison as described below, and MAY support other representations.

Baseline Comparison
Name BaselineComparison
Type URI http://open-services.net/ns/scm#BaselineComparison

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:baseline1 exactly-one Resource reference any The resource used as the basis for the comparison; this is the provider-defined previous baseline by default, or the baseline specified in the oslc_scm.delta query string. This resource is likely to be a oslc_scm:Baseline but that is not necessarily the case.
oslc_scm:baseline2 exactly-one Resource reference any The resource used as the target of the comparison; this is the baseline that was the self resource of the comparison request. This resource is likely to be a oslc_scm:Baseline but that is not necessarily the case.
oslc_scm:change zero-or-many Resource either any A resource describing a single change between baselines, represented either inline or as a reference. Providers MAY choose not to represent changes as gettable resources, but instead always inline this property. This resource is likely to be a oslc_scm:Change resource, but that is not necessarily the case.

A BaselineComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

Configuration

As defined earlier, a configuration is a resource describing a set of object versions arranged into some hierarchy.

Configuration Resource
Name Configuration
Type URI http://open-services.net/ns/scm#Configuration

Configuration Properties

A configuration has the following properties in addition to the common SCM properties:

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:stream zero-or-many Resource reference any A reference to a resource defining the stream or branch to which this configuration belongs; this specification does not define the properties of a stream or branch resource. Note this property may have multiple values, to show multiple streams to which the configuration might belong.

Configuration Methods

A client uses the normal http GET or HEAD methods to request information about a configuration. From the returned information, or using the oslc.properties nested property syntax, the client may retrieve information information about the members of this configuration. Recursion down through the rdfs:member relationship (such as a configuration/directory/file hierarchy) is possible using the closure syntax. Limited closure using the "!" closure operator may stop at a component boundary, as defined by the service provider.
Example:

 GET http://synergyserver:8888/oslc/configuration/mainproject/17/7.2?oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,rdfs:member*{dcterms:title,dcterms:description} 

Directory, File, and Symlink Resources

SCM services MAY provide resources representing all versions of some specific object, such as a directory, a file, or a symbolic link; such resources would be of types Directory, File, and Symlink. Providers MAY also have versioned resources of other types. These resources SHOULD have the common SCM properties, and MAY have additional properties. A DirectoryVersion resource, as defined below, MAY contain references to resources representing all versions of its potential members.

Directory Version

A directory version resource refers to a specific version of a Directory resource, for SCM systems that control versions of directories.

Directory Version Resource
Name DirectoryVersion
Type URI http://open-services.net/ns/scm#DirectoryVersion

Directory Version Properties

A directory version has the following properties in addition to the common SCM properties:

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:memberIdentifier zero-or-many Resource reference any A URI representing the identity of a member (file, directory, symbolic link, or configuration) of this directory version, but not necessarily the specific version of that member; this property may have multiple values, to show multiple members of the parent object. Typically, the URI is that of a resource representing all versions of some object, such as a Directory, File, or Symlink resource. A client can compare the memberIdentifier properties of two different directory versions to see which members were added or removed.

Directory Version Methods

A client uses the normal http GET or HEAD methods to request information about a directory version. Recursion down through the rdfs:member relationship (such as a directory/file hierarchy) might be possible using the oslc.properties closure syntax; limited closure using the "!" closure operator may stop at a component boundary, as defined by the service provider. For some providers, this recursion MAY require that a configuration context is provided either in the URL path or using an oslc_scm.context query string. If no context baseline or configuration is provided, a directory version MAY have a number of oslc_scm:memberIdentifier properties and no rdfs:member properties, in which case no recursion through directory members is possible.

Example:

 GET http://synergyserver:8888/oslc/directory/src/17/7.2?oslc_scm.context=configuration/src/17/7.2&oslc.properties=dcterms:name,dcterms:title,oslc_scm:status,rdfs:member*{dcterms:name,oslc_scm:status} 

Directory Version Comparison

By adding the oslc_scm.delta query string to a directory version URI, a client can request a new resource representing the difference between the subject directory version and some other resource; the request MAY fail if the second resource is not also an SCM directory version.

If the optional URI value is provided, it provides the URI of the directory version that is to be compared with the subject directory version. If no URI is provided, the service provider determines an appropriate predecessor directory version (typically, the predecessor version of the same directory). By default, OSLC SCM providers MUST return a DirectoryVersionComparison as described below, and MAY support other representations.

Directory Version Comparison
Name DirectoryVersionComparison
Type URI http://open-services.net/ns/scm#DirectoryVersionComparison

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:directoryVersion1 exactly-one Resource reference any The resource used as the basis for the comparison; this is the provider-defined previous directory version by default, or the directory version specified in the oslc_scm.delta query string. This resource is likely to be a oslc_scm:DirectoryVersion but that is not necessarily the case.
oslc_scm:directoryVersion2 exactly-one Resource reference any The resource used as the target of the comparison; this is the directory version that was the self resource of the comparison request. This resource is likely to be a oslc_scm:DirectoryVersion but that is not necessarily the case.
oslc_scm:memberAdded zero-or-many Resource reference any A URI representing the identity of a member (file, directory, symbolic link, or configuration) added to this directory version, but not necessarily the specific version of that member. Typically, the URI is that of a resource representing all versions of some object, such as a Directory, File, or Symlink resource, just as in the memberIdentifier property of a DirectoryVersion.
oslc_scm:memberRemoved zero-or-many Resource reference any A URI representing the identity of a member (file, directory, symbolic link, or configuration) removed from this directory version, but not necessarily the specific version of that member. Typically, the URI is that of a resource representing all versions of some object, such as a Directory, File, or Symlink resource, just as in the memberIdentifier property of a DirectoryVersion.

A DirectoryVersionComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

File Version

A file version resource refers to a specific version of a File resource.

File Version Resource
Name FileVersion
Type URI http://open-services.net/ns/scm#FileVersion

File Version Properties

A file version has the following properties in addition to the common SCM properties:

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:content exactly-one Resource reference any A reference to the byte contents of the file version.
oslc_scm:mimeType zero-or-one String n/a n/a The MIME type of the file version content.

File Version Methods

A client uses the normal http GET or HEAD methods to request information about a file version. The file content may be retrieved using the link in the oslc_scm:content property.
Example:

 GET http://synergyserver:8888/oslc/file/1234?oslc.properties=dcterms:name,oslc_scm:status,oslc:creator

File Version Comparison

By adding the oslc_scm.delta query string to a file version URI, a client can request a new resource representing the difference between the subject file version and some other resource; the request MAY fail if the second resource is not also an SCM file version.

If the optional URI value is provided, it provides the URI of the file version that is to be compared with the subject file version. If no URI is provided, the service provider determines an appropriate predecessor file version (typically, the predecessor version of the same file). By default, OSLC SCM providers MUST return a FileVersionComparison as described below, containing a unified diff, and MAY support other representations.

File Version Comparison
Name FileVersionComparison
Type URI http://open-services.net/ns/scm#FileVersionComparison

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:fileVersion1 exactly-one Resource reference any The resource used as the basis for the comparison; this is the provider-defined previous file version by default, or the file version specified in the oslc_scm.delta query string. This resource is likely to be a oslc_scm:FileVersion but that is not necessarily the case.
oslc_scm:fileVersion2 exactly-one Resource reference any The resource used as the target of the comparison; this is the file version that was the self resource of the comparison request. This resource is likely to be a oslc_scm:FileVersion but that is not necessarily the case.
oslc_scm:unifiedDiff exactly-one String n/a n/a The unified diff between the contents of the two file versions, describing the changes made from fileVersion1 to fileVersion2.

A FileVersionComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

Symlink Version

A symlink version resource refers to a specific version of a Symlink resource.

Some SCM systems have direct support for symbolic links, as provided on UNIX file systems. Service providers that support symbolic links MUST use the SymlinkVersion resource type for such a specific version of such an object. Note that service providers that do support symbolic links MAY return resources of this type to clients running on systems that do not support symbolic links; for example, a UNIX provider can return SymlinkVersion resources to a client running on Windows.

SCM 1.0 does not define a resource type for links to other SCM resources, as opposed to symbolic links whose target is a file system paths; if a provider needs to represent links to other SCM resources, a separate resource type MUST be defined (using a resource shape in the Query Capability and/or Creation Factory).

SymlinkVersion Resource
Name SymlinkVersion
Type URI http://open-services.net/ns/scm#SymlinkVersion

Symlink Version Properties

A symlink version has the following properties in addition to the common SCM properties.

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:target exactly-one String n/a n/a The target of the symbolic link, as a string containing a relative or absolute file system path.

Symlink Version Methods

A client uses the normal http GET or HEAD methods to request information about a symlink version.

Symlink Version Comparison

By adding the oslc_scm.delta query string to a symlink version URI, a client can request a new resource representing the difference between the subject symlink version and some other resource; the request MAY fail if the second resource is not also an SCM symlink version.

If the optional URI value is provided, it provides the URI of the symlink version that is to be compared with the subject symlink version. If no URI is provided, the service provider determines an appropriate predecessor symlink version (typically, the predecessor version of the same symlink). By default, OSLC SCM providers MUST return a SymlinkVersionComparison as described below, containing a unified diff, and MAY support other representations.

Symlink Version Comparison
Name SymlinkVersionComparison
Type URI http://open-services.net/ns/scm#SymlinkVersionComparison

Prefixed Name Occurs Value-type Representation Range Description
oslc_scm:symlinkVersion1 exactly-one Resource reference any The resource used as the basis for the comparison; this is the provider-defined previous symlink version by default, or the symlink version specified in the oslc_scm.delta query string. This resource is likely to be a oslc_scm:SymlinkVersion but that is not necessarily the case.
oslc_scm:symlinkVersion2 exactly-one Resource reference any The resource used as the target of the comparison; this is the symlink version that was the self resource of the comparison request. This resource is likely to be a oslc_scm:SymlinkVersion but that is not necessarily the case.
oslc_scm:unifiedDiff exactly-one String n/a n/a The unified diff between the targets of the two symlink versions, describing the changes made from symlinkVersion1 to symlinkVersion2.

A SymlinkVersionComparison is only defined to have the properties listed above, and need not have any of the common SCM properties.

OSLC SCM Service Provider Capabilities

Resource Shapes

OSLC SCM services providers MUST support Resource Shapes as defined in the OSLC Core Specification

Service Provider Resource

OSLC SCM service providers MUST provide a Service Provider Resource that can be retrieved at a implementation dependent URI.

OSLC SCM service providers MAY provide a Service Provider Catalog Resource that can be retrieved at a implementation dependent URI.

OSLC SCM service providers MUST provide a oslc:serviceProvider property for their defined resources that is the URI to a Service Provider Resource.

OSLC SCM service providers MUST supply a value of http://open-services.net/ns/scm# for the property oslc:domain on either oslc:Service or oslc:ServiceProviderCatalog resources.

Creation Factories

SCM providers MAY define creation factories compliant with the core specification, but none are required by this specification.

Query Capabilities

There MUST be at least one Query Capability entry in the Services definition for an OSLC SCM provider.

SCM services MUST implement the OSLC Core Query Syntax, and SHOULD support oslc.properties, oslc.prefix, oslc.where, and oslc.select query string; note that usage of oslc.properties and oslc.prefix is not limited to queries. SCM services MAY also support oslc.searchTerms and oslc.orderBy.

SCM services MUST support queries for baselines and change sets, and SHOULD support queries for any resource types.

Delegated User Interface Dialogs

See Delegated UIs.

SCM services SHOULD provide a picker (selection dialog) for baselines and one for change sets. Services MAY provide other selection dialogs.

SCM providers MAY define also define delegated creation dialogs, but none are required by this specification.

Appendix A: Examples

This appendix is informative.

TBD.

Appendix B: Resource Shapes

This appendix is informative.

TBD.

Appendix C: Notices and References

This appendix is informative.

Contributors

Reporting Issues on the Specification

The working group participants who author and maintain this specification monitor a distribution list where issues or questions can be raised, see Oslc-Scm Mailing List

Also the issues found with this specification and their resolution can be found at ScmSpecIssuesV1.

Intellectual Property Covenant

The members of the Working Group (or as appropriate, their employers) have documented a Patent Non-Assertion Covenant for implementations of the SCM 1.0 Specification, as described in the open-services.net Terms of Use. Details of the Covenant may be found here.

Supporting Documents

These non-normative documents do not form part of the specification, but provide examples and references, and document the use cases, design decisions, and rationale that led to the OSLC SCM 1.0 specification. In any discrepancy between what is described in these documents and the actual specifications, the specification prevails.

Document TBD: Temporary comments - remove before finalization
Drill Down Story Frozen for SCM 1.0
SCM Terminology Out of date - needs work

References

Topic attachments
I Attachment Action Size Date Who Comment
pngpng OSLC_SCM_model.png manage 19.8 K 12 Apr 2010 - 10:59 NickCrossley SCM data model example
Topic revision: r39 - 11 May 2011 - 14:06:51 - NickCrossley
 
This site is powered by the TWiki collaboration platform Copyright by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Contributions are governed by our Terms of Use
Ideas, requests, problems regarding this site? Send feedback