DynamoDB Converter Tool

DynamoDB JSON Format - Here's What You Need to Know

DynamoDB does not use the classical JSON format to store items internally. Instead, it uses a "marshalled" format. DynamoDB wraps all the attribute values in objects where the key indicates its type and attribute value stays as-is. For instance: { value: 3 } becomes { value: { N: "3" } }.

The ten DynamoDB data type descriptors

• S - String. "hello" becomes { "S": "hello" }
• N - Number, sent as a string. 3 becomes { "N": "3" }
• B - Binary, base64 encoded. the bytes for hi becomes { "B": "aGk=" }
• BOOL - Boolean. true becomes { "BOOL": true }
• NULL - Null. null becomes { "NULL": true }
• M - Map, an object. { a: 1 } becomes { "M": { "a": { "N": "1" } } }
• L - List, an array. [1, "x"] becomes { "L": [{ "N": "1" }, { "S": "x" }] }
• SS - String Set. a set of "a" and "b" becomes { "SS": ["a", "b"] }
• NS - Number Set. a set of 1 and 2 becomes { "NS": ["1", "2"] }
• BS - Binary Set. a set of byte arrays becomes { "BS": ["aGk="] }

Things that catch people out

• Numbers travel as strings. { "N": "3" } is correct, { "N": 3 } is not. AWS sends them this way "to maximize compatibility across languages and libraries", and DynamoDB still treats them as numbers for maths.
• Numbers can be positive, negative or zero, with up to 38 digits of precision. The positive range is 1E-130 to 9.99...E+125 and the negative range mirrors it. Exceeding 38 digits raises an exception, and leading and trailing zeroes are trimmed. A JavaScript number cannot represent that whole range, so this tool writes values out in full decimal form and warns you when one is too precise to convert without rounding.
• Sets are not lists. SS, NS and BS hold unique, unordered values of a single type, and they cannot be empty. Plain JSON has no set type, so this tool shows them as arrays. Converting that array back gives you an L, not a set. Binary loses its type the same way: B is shown as its base64 text, and converting back gives you an S.
• NULL takes the value true, which reads oddly. { "NULL": true } means the attribute is null.
• Binary is base64 encoded in JSON, so B and S can look identical on the wire. The type key is the only thing that distinguishes them.
• Empty strings and empty binary values are allowed, as long as the attribute is not a table or index key, and they are also allowedinside a set, list or map. What is not allowed is an empty set itself. Empty lists and maps are fine.
• Lists and maps can be nested within each other up to 32 levels deep.

Related resources

• Import CSV to DynamoDB
• Import JSON to DynamoDB
• Export DynamoDB to CSV
• Export DynamoDB to JSON
• Export DynamoDB to S3