assets.texi (2265B)
1 @anchor{assets} 2 @chapter Media assets 3 4 Any entry may contain one or more media assets as @emph{attachments}. These allow for detailed documentation of the transaction the entry represents. 5 6 Attachments are not limited to any specific type of content, but are usually a @emph{receipt}, an @emph{invoice} or a @emph{proof of payment}. 7 8 9 @section Structure 10 11 The attachment is defined by the following data: 12 13 @itemize 14 @item A @strong{slug} and @strong{extension}, together defining a filesystem-safe string appropriate for use as a file name. (i.e. the substrings @emph{"picture"} and @emph{"png"} from @file{/foo/bar/picture.png} respectively) 15 @item A (preferably succint) @strong{description} of what the asset represents. 16 @item An optional @emph{external reference}, intended to override the external reference in the @code{entry} element (e.g. if different parties refer to the same transaction with different identifiers). 17 @item Zero or more @strong{lookup} elements, specifying the @emph{lookup key} and the @xref{method} used to generate the lookup key. 18 @item A @strong{mime type} string. 19 @item A @strong{uuid} string. 20 @end itemize 21 22 23 @anchor{method} 24 @subsection Lookup methods 25 26 The method may or may not be verifiable from the content. 27 28 At a minimum, any implementation should accommodate the following methods: 29 30 @itemize 31 @item @code{sha256} and @code{sha512}, for which the @emph{lookup value} is the corresponding digest according to those algorithms. 32 @item @code{uuid}@footnote{Note that uuid should not be used alone, as the value domain may carry the risk of collisions}, for which the key is a @emph{uuid string} that may or may not be related to a @emph{content digest}. 33 @end itemize 34 35 Any implementation is free to define any method it wishes, but should refrain from using well-known method strings like the above. 36 37 If the lookup element is missing from an asset, any matching resolvers should be attempted in turn. 38 39 40 @subsubsection Metadata 41 42 The lookup method @emph{should} provide the @strong{mime type} of the contents (e.g. @code{Content-Type} header over @strong{http}). 43 44 It @emph{can} also provide @strong{file name} (e.g. @code{Content-Disposition} header over @strong{http}), aswell as other metadata defined in the @strong{Attachment} schema.