Notices
Copyright ©
OASIS Open
2021.
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 specification is published under the Attribution 4.0 International (CC BY 4.0).
Portions of this specification are also provided under the Apache License 2.0.
All contributions made to this project have been made under the
OASIS Contributor License Agreement (CLA).
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
Open Projects IPR Statements page.
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 Open Project or 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 Project Specification
or OASIS Standard, to notify the 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 Open Project 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 Open Project 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.
1. Introduction
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.
Example 1
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.
Example 2
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.
1.1 Terminology
Terminology uses and extends the terminology and capabilities of
OSLC Core Overview, W3C Linked Data Platform [LDP], W3C's Architecture of
the World Wide Web [WEBARCH], Hyper-text Transfer Protocol [HTTP11].
- Attachment
- A LDP-NR whose lifecycle is coupled with the attaching resource.
- Attachment Container
- A LDPC that contains Attachments for a resource.
- Attachment Descriptor
- A LDP-RS that contains additional data about an Attachment.
1.3 Typographical Conventions and Use of RFC Terms
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", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
"RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL"
in this specification are to be interpreted as described in
BCP 14
[RFC2119] [RFC8174]
when, and only when, they appear in all capitals, as shown here.
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#>.
4. Working with Attachments
This section is non-normative.
The following examples illustrate how a client can work with attachments.
4.1 Find the Attachments for a Resource
Clients get the attachments for a resource by:
- Finding the attachment container for a resource using an HTTP OPTIONS method and Link header
- Getting the container for the list of attachments
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.
Example 3
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.
Example 4
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.
Example 5
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.
Example 6
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.
4.2 Get the Attachment Content
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.
Example 7
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.
Example 8
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]4.3 Create an Attachment
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.
Example 9
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 [RFC8288] 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.
Example 10
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: 04.4 Update an Attachment
To update an attachment, PUT the attachment content to the attachment resource.
Example 11
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.
Example 12
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: 04.5 Remove an Attachment
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.
Example 13
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.
Example 14
HTTP/1.1 204 No Content
Content-Length: 0
4.6 Include Attachment Information Inline with a Resource
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.
Example 15
@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" .
6. Resource Constraints
6.1 Resource: AttachmentDescriptor
This document applies the following constraints to the
OSLCCoreVocab vocabulary terms.
An OSLC server providing the Attachments capability MUST implement the vocabulary defined in this section.
[AT-22]
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.
- Describes:
http://open-services.net/ns/core#AttachmentDescriptor
- Summary: LDP-RS to contain data about a LDP-NR(Attachment)
AttachmentDescriptor Properties
| 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 [AT-23]. |
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. |
