.. _file-message-format:

File Message Format
###################

This page describes a format for transporting a file in a xbus message.

The message is divided in Two parts:

Header
------

The header is a single json object.

Its fields are the file metadata.

The standard metadata are:

- filename (required)
- type (MIME type)
- size
- encoding
- hash: A list of strings of the following format: "<digest>:<hash>".
  Example: ["sha256:7509e5bda0c762d2bac7f90d758b5b2263fa01ccbc542ab5e3df163be08e6ca9"]
- location (see below)

Typical custom metadata would be:
- customtype

Location
''''''''

The location is an optional object describing where to find the file data.

The only mandatory field is "type": one of "embedded", "s3", "http"

Depending on the type, other fields are needed:

embedded
~~~~~~~~

This is the default location type. The file data are appended in the message after the header.

http
~~~~

The file data is available at a given URL.

Specific fields:

- url: the file URL. Can be http or https

s3
~~

The file is stored in a s3 bucket.

Specific fields:

- provider (optional): the api endpoint url
- region (optional): the region name
- bucket-name
- objectid

The actors that need to access the file are supposed to know the credentials.

Body
----

If the file is embedded, the remaining chunks contain the raw data of the file.


Examples
--------

Simple text file
''''''''''''''''

chunk1: ``{"filename":"simple.txt","type":"text/plain","size":12}``
chunk2: ``Hello World!``