SCM Spec Issues for V1.0

This page is for discussion of issues with the SCM 1.0 spec.

SCM Open Issues

1. Required query capabilities should be defined: suggestion is to require queries for baselines and change sets, and recommend queries for other resource types.
2. Do we need a resource type for ConfigurationFamily, to represent all versions of a Configuration - or should we rename Configuration to ConfigurationVersion and add Configuration to mean a family of configurations?
3. There is no Dublin Core property dcterms:name. This has to be removed, or changed to oslc:shortTitle.
4. Recommendations and/or requirements need to be made for OSLC SCM Tracked Resource Sets
5. This specification probably uses version-specific links in too many places - we should review and see where it would be better to be more version-agnostic
6. This specification should be reconciled with the versioning Core Extension proposal from the PLM-ALM group

Editorial actions for Nick:

1. Update the ScmTerminology terminology page
2. Create namespace links
3. Add examples
4. Add resource shapes

Resolved Issues

1. Do we define a common set of properties, to be mapped to the conceptually equivalent underlying property by each SCM provider? If so, which ones? If not, how can the client query and navigate? Should the service description provide any mappings?
   RESOLVED - Yes, we have defined a common set of properties, including link properties, and SCM providers are required to map these properties to the appropriate equivalents.
2. Do we need to represent an object vs. an object version as separate resources?
   RESOLVED - For SCM v1, we have no real need to represent all versions of a object as a single resource; the operations and queries we are defining mostly return specific versions of objects. Nonetheless, we will use the terms object version, file version, etc., as distinct from object, file, etc., so that we can introduce the concept of a resource describing all versions (or no specific version) in future releases of the spec.
3. How do we control recursion through tree structures?
   RESOLVED - Useful limits appear to be 0, 1, infinity, and down to a component/subcomponent boundary, as determined by a query parameter.
4. What is the diff format to be used for comparing file version contents?
   RESOLVED - Unified diff
5. Are configurations and components object version types, or something different?
   RESOLVED - Configurations and components are just types of versioned object. Note that for any resource type, a provider can restrict the number of versions to be one, representing a non-versioned object.
6. Should we represent the type of a containment relationship, and if so, how? How many relationship names/types should the spec define?
   RESOLVED - There appears to be no requirement for the SCM spec to define more than one containment relationship. The meaning of that relationship might vary according to the type of the container and the contained objects - for example, the meaning of a component in a configuration is slightly different from the meaning of a file in a directory. Providers may add multiple containment relationships if appropriate.
7. How does a client discover which links are provided by which OSLC services?
   RESOLVED - this information is not provided in the current round of OSLC services; clients must have other sources of such knowledge, possibly in configuration files that would have to be set up to be specific to the actual set of providers in a given installation.
8. Do we need to keep the concept of incremental baselines?
   RESOLVED - No, OSLC SCM will expose only the end result of a baseline, and will not expose implementation details such as incremental construction of a baseline.
9. Should OSLC SCM require JSON as well as RDF+XML? What about other formats such as Turtle and Atom?
   RESOLVED - SCM will require RDF+XML and JSON; other formats may be offered by providers
10. Should SCM 1.0 queries support impact analysis - that is, finding all configurations and baselines that contain a given change set or versioned object?
    RESOLVED - No. While this is a useful capability and should be supported in the future, we do not have the time and resources to expand the scope of SCM 1.0.
11. Sort out the distinction between configuration and component. Are both concepts required?
    RESOLVED - Yes, both concepts are required, but previous usage has been simplified. Component is used just for recursion, and might not necessarily map to any specific SCM resource - component boundaries might be established from attribute values, etc.
12. Providers must map the properties defined in this spec to those of the underlying implementation. Should a client be able to access properties without any name or type mapping, and if so, how?
    RESOLVED The spec will not attempt to define how such unmapped access might work. However, providers must support queries for and returning values of additional provider-specific properties that are not defined in the spec. Since they are likely to do so using some provider-specific namespace, it is likely that clients could use this provider-specific namespace to query for any property, including those that are also mapped to OSLC defined properties.
13. How do we handle GET requests with selected properties, when not all objects in the result set have any/all of the requested properties?
    RESOLVED - A property that does not exist is treated as an optional property - that is, it is simply not returned in the results. No indication of this is given in the http response code.
14. Need to define the result of the baseline compare operation.
    RESOLVED - 4 lists: object versions added, object versions removed; change sets added, removed. As with the list of change sets linked to a baseline, the link properties MAY identify change sets fully included, partially included, or modified. The spec will not return any list of objects where the same version is used in the two baselines, but the object version content or properties were modified between the creation of the two baselines.
15. How do SCM URLs provide a configuration resource as context? For example, if you want to know the specific file versions and subdirectory versions used in a given directory, a context must be provided.
    RESOLVED - Context MAY be defined by passing a second resource URL in the oslc_scm:context query parameter. Providers MUST also support encoding any necessary context within a URI, and the resource representation returned from baseline or configuration membership queries MUST include that baseline or configuration context.
16. How should the selection delegates work?
    RESOLVED - OSLC SCM shall define two UI pickers - one for baselines and one for change sets. Providers MAY supply others, such as for configurations and object versions. These UI pickers shall be defined as per the core spec or the guidance document, if that is created, or text shall be copied and edited appropriately from the relevant part of another spec (such as RM).
17. How do we handle GET requests with no selected properties? We agree we do not want to return all properties of the relevant resources, since doing so might result in huge result sets, especially if all nested (inlined) properties were also to be returned.
    RESOLVED - Define simple and extended properties. If oslc.properties is not set, requests return the simple properties, but omit the extended properties. A client can ask for all properties using a parameter oslc.properties=*.
18. There is a need for reverse service discovery - that is, given a URL for an OSLC resource, how does a client find the service description for the provider of that resource? A client probably needs this information, so it an look up the resource shape, find the UI delegate for operations on resources of that type, etc.
    RESOLVED - every OSLC resource has a scope attribute pointing back to its service provider resource.
19. Do we want to allow creation factories, put, post, etc.?
    RESOLVED - yes. A client can use the specification versioning to help resolve any incompatibilities between extensions to version 1 of the SCM specification and any creation factories, dialogs, and operations defined in later revision of the specification.
20. Description vs. comment, and long/full name, and do we allow rich text in name, or elsewhere?
    RESOLVED - we agreed to use dc:description for both description and comment, as appropriate for each resource type, and to add a new property to hold a full name. Neither short nor long object names will permit rich text, but descriptions/comments shall allow rich text.
21. Using an explicit resource type for symbolic links.
    RESOLVED - we agreed to introduce a specific resource type for symlinks to paths, and we agreed to drop support for symlinks to other resources. A provider can of course add their own resource type to describe symbolic links to other resources if desired.
22. The issue of getting resource (file/document) content vs. resource description and properties has been addressed in the Asset Management spec, providing both a reference to the resource content and an inline-able property containing the bytes of the content. That approach was been copied into the SCM spec, but should be reviewed in the light of the core spec as that evolves.
    RESOLVED - we decided to offer only a reference to the file content. Inlining file content did not seem useful.
23. How should changes in change sets and between baselines be represented? For Jazz SCM, they need to represent additions, modifications, and removals, and possibly also the before and after state.
    RESOLVED - we have introduced a new resource type called Change. This new type might not be a gettable resource, and might not be a subtype of object version. Some providers might always inline this property.
24. Updates to Core Spec for versioning.
    RESOLVED - versioning has been simplified so that only a core spec version header is used in both requests and responses, and versioning has been removed from the namespaces.
25. Updates to Core Spec common properties.
    RESOLVED - oslc:scope has been replaced by oslc:instanceShape and oslc:serviceProvider
26. The concept of extended properties has been rejected.
    RESOLVED - the spec has been updated to remove all usage of extended properties, and advice on use of oslc.properties has been added.
27. We need to define which query parameters (oslc.select, oslc.from, oslc.where, oslc.searchTerms, oslc.orderBy) are required - the core spec is leaving them all optional.
    RESOLVED - updated spec requires oslc.select, oslc.from, oslc.where.
28. For query purposes, consider the need to add flattened member lists as well as hierarchical member lists. You can write an OSLC query of the form oslc.where=oslc_scm:member{oslc_scm:member{oslc_scm:member{dc:title="some string"}}}, but what if you want to find members at any arbitrary depth?
    RESOLVED - leave this for SCM 2.0 or later.
29. What's the meaning of including both oslc_scm.recurse and oslc.properties=dc:title,oslc_scm:member{dc:name} - does it return dc:title for the recursive members, or dc:name, or both, or should that be illegal?
    RESOLVED - replace oslc_scm.recurse with closure syntax on oslc.properties.
30. Define DirectoryVersionComparison, FileVersionComparison, and SymlinkVersionComparison resources
    RESOLVED - updated spec has these resources.
31. Operations on symlinks to get content imply file system access, so are not suitable for server-side API. Drop them?
    RESOLVED - dropped from spec.
32. Jazz SCM requires that the changeType property of a Change can occur zero or many times, not just zero or one.
    RESOLVED - the spec has been updated.
33. What's the meaning of including both oslc.properties and oslc_scm.delta in a GET request - do we make the unified diff result just another property to be shown in the result together with the requested properties of the requested object, or should that be illegal? Either way, we need to define more exactly the return value so that it can be mapped to RDF/XML or JSON - unless we say a diff request only returns simple text and not a resource format at all.
    RESOLVED - The resource types DirectoryVersionComparison, FileVersionComparison, and SymlinkVersionComparison have been defined (see earlier issue), so now it is intuitive that the oslc.properties parameter applies to the properties of these comparison resources.
34. The oslc_scm:changeSetState property does not match the core OSLC direction.
    RESOLVED - drop the changeSetState property, split the oslc_scm:changeset link in baselines into three separate links indicating change sets that were added, modified or removed in a baseline.
35. Do we need to differentiate oslc_scm:baseline1 from oslc_scm:directoryVersion1, etc? Can't all of the comparison objects have a oslc_scm:object1 and oslc_object2?
    RESOLVED - they could, but since the various comparison resources have other differing properties, they cannot all be merged to a single type, so there seems little value in having the two object properties have a common but less meaningful name.
36. The spec was reworded to be more in line with other web-centric, linked data specifications
37. Introduced Directory, File, and Symlink resource types and use URIs to those resources in place of undefined strings in the DirectoryVersion memberIdentifier property
38. Used dcterms:contributor instead of oslc_scm:owner
39. Used rdfs:member instead of oslc_scm:member
40. Relaxed some cardinality constraints (dcterms:identifier is now zero-or-one, not exactly-one, and oslc_scm:build is now zero-or-many)
41. Reduced some constraints from MUST to SHOULD (support for oslc.properties, support for transitive closure over rdfs:member
42. Some properties that were previously strings have been made resources (oslc_scm:memberIdentifier, oslc_scm:stream and oslc_scm:build)
43. Constraints on the types of resources at the ends of links have largely been removed, following updated core spec guidelines
44. Stream has been added as a property for configurations - zero-or-many.
45. Support for POST queries has been removed from the core and SCM specs (at least temporarily)
46. The spec did not previously define the required value for oslc:domain in the ServiceProvider resources.
    RESOLVED - The spec now defines the required value as http://open-services.net/ns/scm#.