This document registers tags for serializing a currency and a money amount in Concise Binary Object Representation (CBOR) (ref. 1).
Financial software has the requirement to store and transmit currencies and amounts of money. In order to encode and decode this data semantically using CBOR, it is necessary to tag this values. This document proposes two new tags for a single currency and for a combination of a number and a currency.
Almost every software that processes monetary amounts of different currency has its own types to store these values. To ensure interoperality with CBOR, it is necessary to tag the values semantically.
A currency in CBOR has tag 164 and is encoded as a text string or a positive integer. The text string is the ISO 4217 currency code. The integer is the ISO 4217 currency number.
Implementations must support currencies encoded as a text string. Support for encoding a currency as number is optional.
A money amount in CBOR has tag 165 and is encoded as an array of length 2. The first element is the currency encoded as a text string or a positive integer with the same semantics as above. The second element of the array is the numeric value of the money amount.
The numeric value can be a positive integer (major type 0), a negative integer (major type 1), a positive bignum (tag 2), a negative bignum (tag 3), a decimal fraction (tag 4), a bigfloat (tag 5) or a rational number (tag 30). Implementations must support positive integers, negative integers and decimal fractions. Support for bignums, bigfloats and rational numbers is optional.
A CBOR decoder can treat data items with tag 164 or 165 that don't meet the criteria above as an error, but this specification doesn't define how a CBOR implementation ought to behave in this case. Section 3.4 of RFC 7049 (ref. 1) details this kind of error-handling behavior.
The following example shows how the currency "USD" is encoded.
D8 A4 # tag(164)
63 # text(3)
555344 # "USD"
The following example shows how the money amount "85 EUR" is encoded.
D8 A5 # tag(165)
82 # array(2)
63 # text(3)
455552 # "EUR"
18 55 # unsigned(85)
Ref. 1. Bormann, C. and Hoffman, P. "Concise Binary Object Representation (CBOR)". RFC 7049, October 2013.
Jörg Richter (joerg.richter at pdv-fs dot de)
Any copyright to this specification is released to the Public Domain. http://creativecommons.org/publicdomain/zero/1.0/