--- type: "datatype" title: "Attachment" datatype: "Attachment" --- # Attachment - [Datatypes](/datatypes) - [Definitions](/datatypes-definitions#Attachment) - [Examples](/datatypes-examples#Attachment) - [Mappings](/datatypes-mappings#Attachment) - [Profiles](/datatypes-profiles#Attachment) ## Overview See also [Examples](datatypes-examples#Attachment), [Detailed Descriptions](datatypes-definitions#Attachment), [Mappings](datatypes-mappings#Attachment), [Profiles](datatypes-profiles#Attachment) and [Extensions]([%extensions-location%]extensions-datatypes#Attachment) This type is for containing or referencing attachments - additional data content defined in other formats. The most common use of this type is to include images or reports in some report format such as PDF. However, it can be used for any data that has a MIME type. \[%dt Attachment 1%\] The actual content of an Attachment can be conveyed directly using the `data` element or a `URL` reference can be provided. If both are provided, the reference SHALL point to the same content as found in the data. The reference can never be reused to point to some different data (i.e., the reference is version specific). The `URL` reference SHALL point to a location that resolves to actual data; some URIs such as cid: meet this requirement. If the URL is a relative reference, it is interpreted in the same way as a [resource reference](references#references). The `contentType` element SHALL always be populated when an Attachment contains `data`, and MAY be populated when there is a `url`. It can include charset information and other mime type extensions as appropriate. If there is no character set in the `contentType` then the correct course of action is undefined, though some media types may define a default character set and/or the correct character set may be able to be determined by inspection of the content. The `hash` is included so that applications can verify that the content returned by the URL has not changed. The `hash` and `size` relate to the data before it is represented in base64 form. The hash is not intended to support digital signatures. Where protection against malicious threats a digital signature should be considered, see [Provenance.signature](provenance-definitions#Provenance.signature) for mechanism to protect a resource with a digital signature. Attachment `data` are not constrained, and therefore can be of any content type and encoding. Therefore extra care needs to be taken to validate the content against malicious or malformed content. For more details see [Security of Narrative](security#narrative). In many cases where Attachment is used, the cardinality is >1. A valid use of repeats is to convey the same content in different mime types and languages. Guidance on the meaning of repeating elements SHALL be provided in the definition of the repeating resource element or extension that references this type. The language element describes the language of the attachment using the [codes defined in BCP 47](http://tools.ietf.org/html/bcp47). **Constraints** \[%dt.constraints Attachment%\] If neither `data` nor a `URL` is provided, the value should be understood as an assertion that no content for the specified `mimeType` and/or `language` is available for the combination of `language` and `contentType`. The context of use may frequently make rules about the kind of attachment (and therefore, the kind of mime types) that can be used. \[%tx Attachment%\] Attachment is used in the following places: \[%dtusage Attachment%\] ## Elements - **[Attachment.contentType](/datatypes-definitions#Attachment.contentType)** [0..1]: [code](/code) Identifies the type of the data in the attachment and allows a method to be chosen to interpret or render the data. Includes mime type parameters such as charset where appropriate - **[Attachment.language](/datatypes-definitions#Attachment.language)** [0..1]: [code](/code) The human language of the content. The value can be any valid value according to BCP 47 - **[Attachment.data](/datatypes-definitions#Attachment.data)** [0..1]: [base64Binary](/base64Binary) The actual data of the attachment - a sequence of bytes, base64 encoded - **[Attachment.url](/datatypes-definitions#Attachment.url)** [0..1]: [url](/url) A location where the data can be accessed - **[Attachment.size](/datatypes-definitions#Attachment.size)** [0..1]: [integer64](/integer64) The number of bytes of data that make up this attachment (before base64 encoding, if that is done). - **[Attachment.hash](/datatypes-definitions#Attachment.hash)** [0..1]: [base64Binary](/base64Binary) The calculated hash of the data using SHA-1. Represented using base64. - **[Attachment.title](/datatypes-definitions#Attachment.title)** [0..1]: [string](/string) A label or set of text to display in place of the data - **[Attachment.creation](/datatypes-definitions#Attachment.creation)** [0..1]: [dateTime](/dateTime) The date that the attachment was first created - **[Attachment.height](/datatypes-definitions#Attachment.height)** [0..1]: [positiveInt](/positiveInt) Height of the image in pixels (photo/video) - **[Attachment.width](/datatypes-definitions#Attachment.width)** [0..1]: [positiveInt](/positiveInt) Width of the image in pixels (photo/video) - **[Attachment.frames](/datatypes-definitions#Attachment.frames)** [0..1]: [positiveInt](/positiveInt) The number of frames in a photo. This is used with a multi-page fax, or an imaging acquisition context that takes multiple slices in a single image, or an animated gif. If there is more than one frame, this SHALL have a value in order to alert interface software that a multi-frame capable rendering widget is required - **[Attachment.duration](/datatypes-definitions#Attachment.duration)** [0..1]: [decimal](/decimal) The duration of the recording in seconds - for audio and video - **[Attachment.pages](/datatypes-definitions#Attachment.pages)** [0..1]: [positiveInt](/positiveInt) The number of pages when printed ## Bindings - **Attachment.contentType**: `MimeType` - **Attachment.language**: `Language` ## Summary Elements - **Attachment.contentType**: In _summary view - **Attachment.language**: In _summary view - **Attachment.url**: In _summary view - **Attachment.size**: In _summary view - **Attachment.hash**: In _summary view - **Attachment.title**: In _summary view - **Attachment.creation**: In _summary view ## Examples - **Attachment.contentType**: text/plain; charset=UTF-8, image/png - **Attachment.language**: en-AU - **Attachment.url**: http://www.acme.com/logo-small.png - **Attachment.title**: "Official Corporate Logo" ## Requirements - **Attachment.contentType**: Processors of the data need to be able to know how to interpret the data - **Attachment.language**: Users need to be able to choose between the languages in a set of attachments - **Attachment.data**: The data needs to able to be transmitted inline - **Attachment.url**: The data needs to be transmitted by reference - **Attachment.size**: Representing the size allows applications to determine whether they should fetch the content automatically in advance, or refuse to fetch it at all - **Attachment.hash**: Included so that applications can verify that the contents of a location have not changed due to technical failures (e.g., storage rot, transport glitch, incorrect version) - **Attachment.title**: Applications need a label to display to a human user in place of the actual data if the data cannot be rendered or perceived by the viewer. - **Attachment.creation**: This is often tracked as an integrity issue for use of the attachment ## Comments - **Attachment.data**: The base64-encoded data SHALL be expressed in the same character set as the base resource XML or JSON - **Attachment.url**: If both data and url are provided, the url SHALL point to the same content as the data contains. Urls may be relative references or may reference transient locations such as a wrapping envelope using cid: though this has ramifications for using signatures. Relative URLs are interpreted relative to the service url, like a resource reference, rather than relative to the resource itself. Urls may also be URIs only resolvable within a Bundle containing the resource with the attachment type. If a URL is provided, it SHALL resolve to actual data. - **Attachment.size**: The number of bytes is redundant if the data is provided as a base64binary, but is useful if the data is provided as a url reference - **Attachment.hash**: The hash is calculated on the data prior to base64 encoding, if the data is based64 encoded. The hash is not intended to support digital signatures. Where protection against malicious threats a digital signature should be considered, see [[[Provenance.signature]]] for mechanism to protect a resource with a digital signature - **Attachment.title**: May sometimes be derived from the source filename - **Attachment.frames**: if the number of frames is not supplied, the value may be unknown. Applications should not assume that there is only one frame unless it is explicitly stated - **Attachment.duration**: The duration might differ from occurrencePeriod if recording was paused ## Mappings - **Attachment.contentType**: RIM Mapping: ./mediaType, ./charset - **Attachment.contentType**: v2 Mapping: ED.2+ED.3/RP.2+RP.3. Note conversion may be needed if old style values are being used - **Attachment.language**: RIM Mapping: ./language - **Attachment.data**: RIM Mapping: ./data - **Attachment.data**: v2 Mapping: ED.5 - **Attachment.url**: RIM Mapping: ./reference/literal - **Attachment.url**: v2 Mapping: RP.1+RP.2 - if they refer to a URL (see v2.6) - **Attachment.size**: RIM Mapping: N/A (needs data type R3 proposal) - **Attachment.hash**: RIM Mapping: .integrityCheck[parent::ED/integrityCheckAlgorithm="SHA-1"] - **Attachment.title**: RIM Mapping: ./title/data - **Attachment.creation**: RIM Mapping: N/A (needs data type R3 proposal) - **Attachment.height**: RIM Mapping: .outboundRelationship[typeCode="COMP].target[classCode="OBS", moodCode="EVN",code=""].value - **Attachment.width**: RIM Mapping: .outboundRelationship[typeCode="COMP].target[classCode="OBS", moodCode="EVN",code=""].value - **Attachment.frames**: RIM Mapping: .outboundRelationship[typeCode="COMP].target[classCode="OBS", moodCode="EVN",code=""].value - **Attachment.duration**: RIM Mapping: .outboundRelationship[typeCode="COMP].target[classCode="OBS", moodCode="EVN",code=""].value