Binary or text documents may be considered attachments to other resources. This specification describes a minimal way to manage attachments related to web resources using LDP-Containers and Non-RDF Source [LDP].
This document was last revised or approved by the OASIS OSLC Lifecycle Integration Core (OSLC Core) TC on the above date. The level of approval is also listed above. Check the “Latest version” location noted above for possible later revisions of this document. Any other numbered Versions and other technical work produced by the Technical Committee (TC) are listed at https://www.oasis-open.org/committees/tc_home.php?wg_abbrev=oslc-core#technical.
TC members should send comments on this specification to the TC’s email list. Others should send comments to the TC’s public comment list oslc-core-comments@lists.oasis-open.org, after subscribing to it by following the instructions at the “Send A Comment” button on the TC’s web page at https://www.oasis-open.org/committees/oslc-core/.
This Committee Specification Public Review Draft is being developed under the RF on Limited Terms Mode of the OASIS IPR Policy, the mode chosen when the Technical Committee was established. For information on whether any patents have been disclosed that may be essential to implementing this specification, and any offers of patent licensing terms, please refer to the Intellectual Property Rights section of the TC’s web page (https://www.oasis-open.org/committees/oslc-core/ipr.php).
Note that any machine-readable content (Computer Language Definitions) declared Normative for this Work Product is provided in separate plain text files. In the event of a discrepancy between any such plain text file and display content in the Work Product's prose narrative document(s), the content in the separate plain text file prevails.
[OSLC-Attachments-3.0]
OSLC Core Version 3.0. Part 5: Attachments.
Edited by Jim Amsden.
31 May 2018.
OASIS Committee Specification Draft 03 / Public Review Draft 03.
http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/csprd03/part5-attachments/oslc-core-v3.0-csprd03-part5-attachments.html.
Latest version: http://docs.oasis-open.org/oslc-core/oslc-core/v3.0/oslc-core-v3.0-part5-attachments.html.
Copyright © OASIS Open 2018. All Rights Reserved.
All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to OASIS, except as needed for the purpose of developing any document or deliverable produced by an OASIS Technical Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must be followed) or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an "AS IS" basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
OASIS requests that any OASIS Party or any other party that believes it has patent claims that would necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard, to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification.
OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of any patent claims that would necessarily be infringed by implementations of this specification by a patent holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that produced this specification. OASIS may include such claims on its website, but disclaims any obligation to do so.
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to rights in any document or deliverable produced by an OASIS Technical Committee can be found on the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any information or list of intellectual property rights will at any time be complete, or that any claims in such list are, in fact, Essential Claims.
The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be used only to refer to the organization and its official outputs. OASIS welcomes reference to, and implementation and use of, specifications, while reserving the right to enforce its marks against misleading uses. Please see https://www.oasis-open.org/policies-guidelines/trademark for above guidance.
This section is non-normative.
Various tools handle the association and creation of related resources in conceptually similar ways, but often differ in details on how it is accomplished. The Linked Data Platform (LDP) already defines a model by which it is possible to relate resources to another, even if they are not RDF-based. This specification defines the method to create associated attachments to a given resource and understand if that resource supports the attaching of attachments.
As an example of how to create an attachment, simply HTTP POST the attachment content to the attachment
container for the resource. The request should have a
Content-Type
header describing the attachment's media type.
The optional Slug
header is used to give the attachment a
name.
POST /bugs/2314/attachments HTTP/1.1 Slug: design Content-Type: application/vnd.oasis.opendocument.text Content-Length: 18124 [binary content]
The response contains a Link to the new attachment in the
Location
header. This server has also included a Link to the
oslc:AttachmentDescriptor
for the attachment in the HTTP
response, which contains metadata about the attachment.
HTTP/1.1 201 Created Allow: GET,HEAD,OPTIONS,POST Location: http://example.com/bugs/2314/attachments/3 Link: <http://example.com/bugs/2314/attachments/meta/3>; rel="describedby"; anchor="http://example.com/bugs/2314/attachments/3", <http://www.w3.org/ns/ldp#Resource>; rel="type" Content-Length: 0
The following sections detail how to leverage LDP to accomplish the ways in which to discovery, get, create, update or delete attachments and associate with a web resource.
Terminology uses and extends the terminology and capabilities of OSLC Core Overview [OSLCCore3], W3C Linked Data Platform [LDP], W3C's Architecture of the World Wide Web [WEBARCH], Hyper-text Transfer Protocol [HTTP11].
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MUST, MUST NOT, REQUIRED, SHOULD, SHOULD NOT, RECOMMENDED, MAY, and OPTIONAL in this specification are to be interpreted as described in [RFC2119].
The namespace for OSLC Core is
http://open-services.net/ns/core#
.
Sample resource representations are provided in text/turtle
format [turtle].
Commonly used namespace prefixes:
@prefix dcterms: <http://purl.org/dc/terms/>. @prefix ldp: <http://www.w3.org/ns/ldp#>. @prefix oslc: <http://open-services.net/ns/core#>. @prefix oslc_cm: <http://open-services.net/ns/cm#>. @prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>. @prefix wdrs: <http://www.w3.org/2007/05/powder-s#> . @prefix xsd: <http://www.w3.org/2001/XMLSchema#>.
This section is non-normative.
Most users of lifecycle tools have the need to easily create attachments across a variety of integrated tools and associate them to some lifecycle resource in context to some scenario. Some specific scenarios where this touches cross tool integration:
This section is non-normative.
Attachments are added to a resource via a simple POST request to the
appropriate LDP-Container resource. The entity body becomes the content of
the attachment resource. The attachment may automatically be associated with
the resource via some membership relationship, which may use the oslc:attachment
membership predicate.
Statements are also automatically added to the
oslc:AttachmentDescriptor
resource. The property values are
assigned by the server 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 can
be used to derive the initial values in the indicated
oslc:AttachmentDescriptor
resource:
HTTP Request Header | Prefixed Name |
---|---|
Slug |
dcterms:title |
Content-Type |
dcterms:format |
Content-Length |
oslc:attachmentSize |
This section is non-normative.
The following examples illustrate how a client can work with attachments.Clients get the attachments for a resource by:
Each resource that supports attachments has an attachment container, which is an LDP container. Clients discover the attachment container through an HTTP Link header. A client can use GET or HEAD to get the Link header, but OPTIONS is often more efficient because the server does not have to calculate the ETag or content length of the response. LDP resources must support HTTP OPTIONS, and responses to all HTTP requests for resources that support attachments must have the Link header.
OPTIONS /bugs/2314 HTTP/1.1 Host: example.com
The response contains a Link to the attachment container with Link relation
http://open-services.net/ns/core#AttachmentContainer
. Note
that other Link headers are in the response. In fact, LDP requires
additional Link headers, which is why the response has a Link with relation
type
and target URI
http://www.w3.org/ns/ldp#Resource
.
HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS,PUT,DELETE Link: <http://www.w3.org/ns/ldp#Resource>; rel="type", <http://example.com/bugs/2314/attachments>; rel="http://open-services.net/ns/core#AttachmentContainer"
Now the client requests the attachment container to see the attachments for
this resource. It's a good practice to include an HTTP Prefer
header to explicitly ask the server for the LDP containment triples.
GET /bugs/2314/attachments HTTP/1.1 Host: example.com Accept: text/turtle Prefer: return=representation; include="http://www.w3.org/ns/ldp#PreferContainment"
The response is an LDP container for the attachments. It can be any LDP
container such as an ldp:BasicContainer
or an
ldp:DirectContainer.
This example uses an
ldp:BasicContainer
. The attachment container only contains
attachments for a single resource.
HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS,POST Content-Length: 323 Content-Type: text/turtle ETag: W/"2773fef2237e91273bde782a43925458" Link: <http://www.w3.org/ns/ldp#Resource>; rel="type", <http://www.w3.org/ns/ldp#Container>; rel="type", Preference-Applied: return=representation Vary: Accept,Prefer @prefix oslc: <http://open-services.net/ns/core#> . @prefix ldp: <http://w3.org/ns/ldp#> . <http://example.com/bugs/2314/attachments> a oslc:AttachmentContainer , ldp:BasicContainer ; ldp:contains <http://example.com/bugs/2314/attachments/2> , <http://example.com/bugs/2314/attachments/1> .
Clients can look at the ldp:contains
property on the container
for the attachments.
Once clients have the attachment URI, they can get the attachment by simply making an HTTP GET request to the attachment URI.
A Slug
header can be included by a server in the
response to a GET
on an attachment resource. If a client 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 client may use the last segment of
the resource's URI as a hint, or just choose an arbitrary file name.
GET /bugs/2314/attachments/1 HTTP/1.1 Host: example.com
The response body is the attachment content. Servers should set the response
Content-Type
to describe the media type of the attachment. The
response may have a Content-Disposition
header with a filename
parameter, although this isn't required. This example also contains a Link
with relation describedby
, which links to the
oslc:AttachmentDescriptor
for the attachment.
HTTP/1.1 200 OK Allow: GET,HEAD,OPTIONS,PUT,DELETE Content-Disposition: attachment; filename="screenshot.png" Content-Length: 53622 Content-Type: image/png ETag: W/"678609cdee68e0fb8aea5f252b84a511" Link: <http://example.com/bugs/2314/attachments/meta/1>; rel="describedby", <http://www.w3.org/ns/ldp#Resource>; rel="type", <http://www.w3.org/ns/ldp#NonRDFSource>; rel="type" [binary content]
To create an attachment, POST the attachment content to the attachment
container for the resource. The request should have a
Content-Type
header describing the attachment's media type and subtype as specified in Media Types.
The optional Slug
header is used to give the attachment a
name. The Content-Length
header is used to initialize the attachment size.
A client can set a 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 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 is transformed into a
valid name. If that is not possible or the header is not specified, an
arbitrary value is assigned. Failure due to an invalid name is undesirable
because of the potentially large size of an attachment resource.
The client can provide the attachment size in the Content-Length
header and this can be used to initialize the oslc:AttachmentDescriptor
oslc:attachmentSize
property. The server may compute a different attachment size than that provided by the client if the client specified value is incorrect or not provided.
POST /bugs/2314/attachments HTTP/1.1 Slug: design Content-Type: application/vnd.oasis.opendocument.text Content-Length: 18124 [binary content]
The response contains a Link to the new attachment in the
Location
header. This server has also included a Link to the
oslc:AttachmentDescriptor
for the attachment in the HTTP
response, which contains metadata about the attachment.
When a server successfully creates an attachment resource, it
responds with an HTTP status code of 201 (created)
with the URI of the newly created attachment resource in the HTTP response
Location
header. Additionally, if the server created an
associated oslc:AttachmentDescriptor
resource, the URI for
this resource should be listed in the HTTP response Link
header [RFC5988] with rel="describedby"
[LDP].
Properties for the AttachmentDescriptor that are not readOnly, such as its title and description, can be updated using the usual HTTP PUT
method.
HTTP/1.1 201 Created Allow: GET,HEAD,OPTIONS,POST Location: http://example.com/bugs/2314/attachments/3 Link: <http://example.com/bugs/2314/attachments/meta/3>; rel="describedby"; anchor="http://example.com/bugs/2314/attachments/3", <http://www.w3.org/ns/ldp#Resource>; rel="type" Content-Length: 0
To update an attachment, PUT the attachment content to the attachment resource.
PUT /bugs/2314/attachments/3 HTTP/1.1 Content-Type: application/vnd.oasis.opendocument.text Content-Length: 19377 [binary content]
The server typically responds with a 204 No Content status if the request
succeeds. It also updates an associated attachment metadata in the
oslc:AttachmentDescriptor
in the describedby
link. For example, the client could have included a Slug
header on the update request in order to rename the attachment.
HTTP/1.1 204 No Content Link: <http://example.com/bugs/2314/attachments/meta/3>; rel="describedby"; anchor="http://example.com/bugs/2314/attachments/3", <http://www.w3.org/ns/ldp#Resource>; rel="type" Content-Length: 0
To remove an attachment, make a DELETE request on the attachment URI. This removes the attachment from the container and deletes the content and attachment metadata from the server.
DELETE /bugs/2314/attachments/3 HTTP/1.1 Host: example.com
The server typically responds with 204 No Content status if the request was successful.
HTTP/1.1 204 No Content Content-Length: 0
Servers can choose to include the attachment information directly in the
HTTP response for a resource although this isn't required. Here is an
example defect resource that contains attachments. The attachment container
is an ldp:DirectContainer
where the membership resource is the
defect itself. The membership predicate is oslc:attachment
,
although this predicate is not required. The following example shows the results
of an HTTP GET
on http://example.com/bugs/2314
.
@prefix oslc: <http://open-services.net/ns/core#> . @prefix oslc_cm: <http://open-services.net/ns/cm#> . @prefix dcterms: <http://purl.org/dc/terms/> . @prefix ldp: <http://w3.org/ns/ldp#> . @prefix wdrs: <http://www.w3.org/2007/05/powder-s#> . <http://example.com/bugs/2314> a oslc_cm:Defect ; oslc:attachment <http://example.com/bugs/2314/attachments/2> , <http://example.com/bugs/2314/attachments/1> ; dcterms:title "A serious bug!" ; dcterms:identifier "2314" . <http://example.com/bugs/2314/attachments> a ldp:DirectContainer , oslc:AttachmentContainer ; ldp:contains <http://example.com/bugs/2314/attachments/2> , <http://example.com/bugs/2314/attachments/1> ; ldp:hasMemberRelation oslc:attachment ; ldp:membershipResource <http://example.com/bugs/2314> . <http://example.com/bugs/2314/attachments/1> wdrs:describedBy <http://example.com/bugs/2314/attachments/meta/1> . <http://example.com/bugs/2314/attachments/meta/1> a oslc:AttachmentDescriptor ; oslc:attachmentSize "53622"^^<http://www.w3.org/2001/XMLSchema#integer> ; dcterms:created "2011-07-18T13:22:30.45-05:00"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; dcterms:creator <http://example.com/users/steve> ; dcterms:format <http://purl.org/NET/mediatypes/image/png> ; dcterms:identifier "1" ; dcterms:title "screenshot.png" . <http://example.com/bugs/2314/attachments/2> wdrs:describedBy <http://example.com/bugs/2314/attachments/meta/2> . <http://example.com/bugs/2314/attachments/meta/2> a oslc:AttachmentDescriptor ; oslc:attachmentSize "9196"^^<http://www.w3.org/2001/XMLSchema#int> ; dcterms:created "2011-07-19T15:03:54.00-05:00"^^<http://www.w3.org/2001/XMLSchema#dateTime> ; dcterms:creator <http://example.com/users/dave> ; dcterms:format <http://purl.org/NET/mediatypes/text/x-diff> ; dcterms:identifier "2" ; dcterms:title "fix.patch" .
oslc:AttachmentContainer
that holds attachments for
that resource.
http://open-services.net/ns/core#AttachmentContainer
,
and the target URI is the URI of an
oslc:AttachmentContainer
resource.
Content-Disposition
header
[RFC2183] with disposition type attachment
and a
filename parameter. The filename is often the Slug
header value used to create the attachment with an appropriate file
extension added for the attachment's media type.
oslc:AttachmentDescriptor
, responses to HTTP requests
for the attachment URI MUST include a Link header [RFC5988]
where the context URI is the attachment URI, the Link relation is
describedby
, and the target URI is the URI of the
oslc:AttachmentDescriptor
.
oslc:AttachmentDescriptor
properties of the associated attachment descriptor.
oslc:AttachmentDescriptor
resources.
oslc:AttachmentContainer
MUST be a conformant
Linked Data Platform Container (LDPC).
Slug
request header
[RFC5023] to suggest a name when creating an attachment. If
present, the Slug
header SHOULD NOT include a file
extension.
oslc:AttachmentContainer
solely because it does not
contain a Slug
header.
oslc:AttachmentContainer
solely because they cannot
use the Slug
value unchanged. Servers SHOULD instead
modify the Slug
value as needed or assign a different
name.
oslc:AttachmentDescriptor
, the server MUST include an
HTTP Link header in the response where the context URI is the
newly-created attachment URI, the link relation is
describedby
, and the link target is the
oslc:AttachmentDescriptor
URI.
oslc:AttachmentContainer
by including an
HTTP Link header where the target URI is
http://www.w3.org/ns/ldp#NonRDFSource
and the link
relation is type
. In this case, Servers MUST honor the
client's requested interaction model and treat the resource as an
LDP-NR.
oslc:AttachmentContainer
.
oslc:AttachmentDescriptor
to
describe properties of the attachment such as its name, media type,
and size.
oslc:AttachmentDescriptor
MUST have an explicit
rdf:type
set to
http://open-services.net/ns/core#AttachmentDescriptor
in its RDF representations. It MAY have additional
rdf:type
values.
oslc:AttachmentDescriptor
MUST be a conforming
Linked Data Platform RDF Source (LDPR).
dcterms:title
of the
oslc:AttachmentDescriptor
SHOULD be the value of the client-supplied HTTP Slug
header.
Content-Type
header value from
an attachment creation request to determine the
dcterms:format
property value in the newly-created
attachment's oslc:AttachmentDescriptor
. The
dcterms:format
value SHOULD be a [PURLMediaTypes] media-type resource.
oslc:AttachmentDescriptor
MUST conform to the shape
defined in 6.1 Resource: AttachmentDescriptor.
This document applies the following constraints to the [OSLCCoreVocab] vocabulary terms.
The oslc:AttachmentDescriptor
resource type is used to describe
the binary resource (or non-RDF Resource) associated with a particular
resource. 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
oslc:AttachmentDescriptor
resource to contain data about the
attachment.
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
file, 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
oslc:AttachmentDescriptor
resource itself. Thus, the object of
each oslc: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='describedBy'
to indicate the URL of the
oslc:AttachmentDescriptor
resource. The properties for the
oslc:AttachmentDescriptor
resource are indicated in the table
below.
AttachmentDescriptor
http://open-services.net/ns/core#AttachmentDescriptor
Prefixed Name | Occurs | Read-only | Value-type | Representation | Range | Description |
---|---|---|---|---|---|---|
dcterms:created |
Zero-or-one | true | dateTime | N/A | Unspecified | Timestamp of attachment creation. |
dcterms:creator |
Zero-or-many | true | AnyResource | Either | Unspecified | Creator or creators of the attachment. Likely a foaf:Person , but not necessarily so. |
dcterms:description |
Zero-or-one | false | XMLLiteral | N/A | Unspecified | Descriptive text about the attachment. |
dcterms:format |
Zero-or-one | true | unspecified | Either | Unspecified | MIME type of the attachment content. SHOULD be a PURL media-type resource. |
dcterms:identifier |
Zero-or-one | true | string | N/A | Unspecified | System-assigned identifier. |
dcterms:title |
Zero-or-one | false | string | N/A | Unspecified | Client-specified file name or title. |
oslc:attachmentSize |
Zero-or-one | true | integer | N/A | Unspecified | Size in bytes of the attachment content. |
This section is non-normative.
Revision | Date | Editor | Changes Made |
01 | 04 April 2017 | Jim Amsden | CS was approved and published. |
03 | 31 May 2018 | Jim Amsden | No changes in this document. |