Attachments for Change Requests

Completed Working Draft The results of this are being evolved into the OSLC-CM 3.0 Specification.

Contents

• Motivation
• Proposed Approach
  • Terminology
  • Conceptual Model
    • Resource ChangeRequest
    • Resource AttachmentDescriptor
  • Attachment Creation
  • Sample Usage
    • Retrieve an Attachment for a Change Request
    • Fetch Attachment container
    • Create an Attachment
• Alternative Approaches
  • Intermediate Resource for Attachment Metadata
  • Embedded Attachment Content
  • AttachmentList
  • No AttachmentList
• Next Steps
  • Notes

Motivation

Common use case is to have potentially many and possibly large attachments associated with a Change Request type resource.

Things to consider:

• Alignment with concepts in the W3C LDP working group
• Other than the attachment (file), what properties exist for this attachment? There are typically some automatically added: creation date, owner, size, perhaps content type, id. Others are typically added: name, description. What of these really need to be specified to support the scenarios?
• What operations are needed on attachments: view, create, delete, update?
  • create, view are primary ones.
• Support for bulk / multiple upload of attachments? Seems like a nice feature but really required?
  • Primary need is a single attachment file upload / create
• Support in existing CM providers: need to consider limitations of mapping to existing models? For example: Attachments are typically considered resources that one of its property is the actual “file”. Attachments have properties that can be modified individually and some that are system defined/computed.
• Need to know CM tool size limits upfront to prevent sending file too big and then getting rejected.

Some existing behavior:

• W3C LDP ISSUE-15 Sharing binary resources and metadata
• ClearQuest supports POSTing the actual content of a file or files to the ChangeRequest’s attachment property URI. It accepts multipart content for multiple files and optionally a description property for the resources. Files can only be attached directly to a ChangeRequest.
• RTC supports POSTing the actual content of a file to the repository. A 2nd request is needed to create the “attachment descriptor” resource that links the ChangeRequest to the file attachment. There is a background job that cleans up any files that have not been linked after some point in time. It also allows multiple bindings per file.
• Rational Change doesn’t provide a way to add attachments via its REST interface (maybe fetch). Only support to add attachment is from user interface.
• Bugzilla has REST support for Attachments as well. There are some additional properties that it has: encoding (base64 only one supported), comment, flags, is_obsolete, is_patch, is_private, update_token which seem to be “extra”.

Motivating use cases and other reference material:

• Attaching Source Scan results to an existing ChangeRequest
• Attaching Log file, screenshots, source file to an existing ChangeRequest from a minimal CM client
• V2 Technical Priorities
• OSLC Core Discussion on Attachments
• OslcCoreAttachments

Proposed Approach

Note: The CM WG has converged on an approach and the follow represents that. This will be moved into the 3.0 specification.

The additions to CM proposed here are minimal, and the model is optimized for the most common scenarios: creating and viewing attachments. Other operations, including deleting and updating, can also be supported.

Terminology

• Attachment - a resource whose content can be anything such as an image, a document, a log file or a source control patch.
• Attachment descriptor - information about an attachment. These are an W3C LDP-R and OSLC Resource.

Conceptual Model

The additions to the conceptual model for CM consist of a ChangeRequest multi-valued property that links to the attachment (binary) resource and describes a method to associate a descriptor resource to the attachment resource.

Resource ChangeRequest

ChangeRequest will have a have a new property linking to its attachments.

If resource paging is used for oslc_cm:attachment, then LDP-Container paging SHOULD be used.

Resource AttachmentDescriptor

AttachmentDescriptor resource type used to describe the binary resource (or non-LDP-Resource) associated with a particular Change Request. When a client POSTs an attachment content to a server, the server stores the attachment content and assigns a URI just like any other type of resource creation but it may also create an AttachmentDescriptor resource to contain data about the attachment.

• Name: AttachmentDescriptor
• Type URI http://open-services.net/ns/cm#AttachmentDescriptor

There is no restriction on the content of each attachment resource. For example, it could be a photo of a kitten, an installation manual, a log fil, or a source code patch. Since the attachment cannot be expected to contain additional client or server supplied data, a typical set of properties for each attachment is included with the AttachmentDescriptor resource itself. Thus, the object of each oslc_cm:attachment statement is the binary attachment. Issuing an HTTP HEAD or GET operation on that binary attachment resource URL should produce an HTTP response with a header value of Link: rel='meta' to indicate the URL of the oslc_cm:AttachmentDescriptor resource. The properties for the AttachmentDescriptor resource are indicated in the table below.

AttachmentDescriptor properties, that is not read-only, MAY be updated via an HTTP PUT or PATCH operation.

Attachment Creation

An attachment is added to a ChangeRequest via a simple POST request to the appropriate LDP-Container resource. The entity body becomes the content of the attachment resource. The attachment is automatically associated with the Change Request via an oslc_cm:attachment statement. Statements are also automatically added to the oslc_cm:AttachmentDescriptor resource. The property values are assigned by the CM provider or can be determined from standard headers of the POST. The following table maps the HTTP request headers from the POST request to create the attachment resource to what SHOULD be used as the initial values in the indicated oslc_cm:AttachmentDescriptor resource:

When a CM Provider successfully creates an attachment resource, it MUST respond with an HTTP status code of 201 (created) with the URI of the newly created attachment resource in the HTTP response Location header. Additional, if the CM Provider created an associated oslc_cm:AttachmentDescriptor resource, the URI for this resource should be listed in the HTTP response Link header with rel= describes see RFC5988 and RFC6892.

A CM consumer can include an Slug header in the attachment-creating POST to specify a hint for a name for the resource as part of that single request. This can be important as some CM systems require a name at the time the attachment is created. Different systems may have different requirements for valid attachment names, so the value of the Slug header should be interpreted as a hint in this context. If the given name can not be used as specified, it SHOULD be transformed into a valid name. If that is not possible or the header is not specified, an arbitrary value SHOULD be assigned. Failure due to an invalid name is undesirable because of the potentially large size of an attachment resource.

An Slug header SHOULD also be included by a CM provider in the response to a GET on an attachment resource. If a consumer wishes to store the content as a file, this value provides a hint as to the file name to use (subject, of course, to any file system restrictions). In the absence of an Slug header, the consumer may use the last segment of the resource’s URI as a hint, or just choose an arbitrary file name.

Sample Usage

Retrieve an Attachment for a Change Request

This involves two GET requests (if you don’t have the attachment URI available and do have the Change Request’s URI): the first to find the URI of ChangeRequest, the second is it fetch the attachment itself (based on the Change Request’s property values).

Request #1

GET http://example.com/bugs/2314?oslc.properties=oslc_cm:attachment
Accept: text/turtle

Response #1

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Length: 183
ETag: "_87e52ce291112"

@prefix oslc_cm: <http://open-services.net/ns/cm#> .
@prefix ldp: <http://w3.org/ns/ldp#> .

<>
   a oslc_cm:ChangeRequest ;
   oslc_cm:attachment
      <attachments/1>,
      <attachments/2> .

<attachments>
   a ldp:Container;
   ldp:membershipPredicate oslc_cm:attachment;
   ldp:membershipSubject <.>.

Request #2

GET http://example.com/bugs/2314/attachments/1
Accept: */*

Response #2

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 53622
Link: <http://example.com/bugs/2314/attachments/meta/1>;rel=describes
ETag: "_87e52ce295556"

[binary content]

Fetch Attachment container

Request

GET http://example.com/bugs/2314/attachments
Accept: text/turtle

Response

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Length: 944
ETag: "_87e52ce293334"

@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix oslc_cm: <http://open-services.net/ns/cm#> .
@prefix ldp: <http://w3.org/ns/ldp#> .
@prefix wdrs: <http://www.w3.org/2007/05/powder-s#> .

<>
   a ldp:Container ;
   ldp:membershipPredicate oslc_cm:attachment;
   ldp:membershipSubject <http://example.com/bugs/2314>.

<http://example.com/bugs/2314>
   oslc_cm:attachment <1>, <2> .

<http://example.com/bugs/2314/attachments/meta/1>
   a oslc_cm:AttachmentDescriptor ;
   dcterms:title "screenshot.png" ;
   dcterms:identifier "1" ;
   dcterms:format <http://purl.org/NET/mediatypes/image/png> ;
   oslc_cm:attachmentSize "53622" ;
   dcterms:creator <http://example.com/users/steve> ;
   dcterms:created "2011-07-18T13:22:30.45-05:00" .

<http://example.com/bugs/2314/attachments/1> wdrs:describedBy <http://example.com/bugs/2314/attachments/meta/1>.

<http://example.com/bugs/2314/attachments/meta/2>
   a oslc_cm:AttachmentDescriptor ;
   dcterms:title "fix.patch" ;
   dcterms:identifier "2" ;
   dcterms:format <http://purl.org/NET/mediatypes/text/x-diff> ;
   oslc_cm:attachmentSize "9196" ;
   dcterms:creator <http://example.com/users/dave> ;
   dcterms:created "2011-07-19T15:03:54.00-05:00" .

<http://example.com/bugs/2314/attachments/2> wdrs:describedBy <http://example.com/bugs/2314/attachments/meta/2>.

Create an Attachment

Once the attachment container URI for a Change Request is known, this is accomplished with a single POST request.

Request

POST http://example.com/bugs/2314/attachments
Slug: design.odt
Content-Type: application/vnd.oasis.opendocument.text
Content-Length: 18124

[binary content]

Response

HTTP/1.1 201 CREATED
Location: http://example.com/bugs/2314/attachments/3
Link: <http://example.com/bugs/2314/attachments/meta/3>; rel="describes"
Content-Length: 0

Alternative Approaches

Several other approaches were considered during the evolution of this draft. Following is a summary of these alternatives, along with the drawbacks of each. Note: these ideas are interrelated; they are not all mutually exclusive.

Intermediate Resource for Attachment Metadata

Initially, an attachment was actually conceived as an RDF resource describing the attachment. Such a resource would use all of the metadata properties described above, along with oslc_cm:content to reference the actual attachment content, which would be available as another resource.

This approach would complicate attachment creation, since two separate resources would need to be transmitted to the CM provider and somehow associated. Moreover, many CM systems actually require the attachment content and metadata at the same time, so the typical RESTful pattern (POST the content, obtain the resulting resource’s URI, POST the metadata including the content URI) would not be possible. As a result, a single POST using multipart/mixed content was considered. This would seem a considerable complication compared to the current proposal, especially given the amount of overlap between the properties of the intermediate metadata resource and the standard HTTP headers.

Embedded Attachment Content

With the original model of an attachment as an RDF resource, an alternative to having a separate content resource would be to embed the content in the RDF resource as the value of an oslc_cm:content statement (base64 encoding was proposed for binary content). This approach would eliminate the above drawbacks, but seems particularly unRESTful. Moreover, it would complicate the process of retrieving the attachment content, requiring an RDF resource to be parsed and the content to be extracted and possibly decoded, and would be ill-suited to streaming.

AttachmentList

This proposal had a property on the ChangeRequest of oslc_cm:attachmentList of type oslc_cm:AttachmentList, which had members of oslc_cm:attachment whose objects were that of the actual binary file/attachment. Data about the attachment was included within the response of the attachmentList.

This has too many levels of indirection and didn’t align with recent resolution of LDP WG, which has a way to navigate between attachment (binary) with link header and the RDF-based resource.

No AttachmentList

Rather than having an AttachmentList resource, the attachments would be referenced directly via oslc_cm:attachment statements in the ChangeRequest. This approach would require an external factory to create attachments, which would introduce the problem of how to link attachments to change requests. One proposal was to require the POSTed attachment (originally conceived as an RDF resource containing attachment metadata) to specify the associated change request, but there was concern that such a restriction would seem arbitrary and non-obvious to consumers. In particular, it treats the change request as subordinate to the attachment when, in most CM systems, the reality is the other way around.

Next Steps

1. Identify scenarios (done)
2. Define conceptual model (done)
3. Expand on samples to support scenario (done)
4. Explore alternative approaches (done)
5. Explore any existing standards / vocabularies (done)
6. Finalize specification contributions (in progress)

Notes

Decided issues (2011/08/17)

• We don’t need a secondary name property; dcterms:title will do as the file name.
• Content-Type header parameters like character set need not also be represented here.
• No need to specify a link to a comment. Mylyn Scenario doesn’t actually expect that.

Category:Supporting documents