About

DynamoDB stores attributes using typed descriptors: a simple value like 42 becomes {"N": "42"}, and a nested object becomes an M-wrapped map. Manual construction of these schemas is error-prone and tedious, especially with nested structures exceeding 3 - 4 levels of depth. A mistyped descriptor letter or a forgotten string coercion on numbers silently corrupts your data. This tool implements the full dataToItem and itemToData conversion algorithms, handling all DynamoDB attribute types: S, N, BOOL, NULL, L, M, SS, NS, and BS. It also generates UpdateExpression parameters from delta objects, automatically escaping all 573 DynamoDB reserved words into ExpressionAttributeNames. Values of undefined produce REMOVE actions; defined values produce SET actions. The tool approximates the behavior of the dynamo-converters npm package but runs entirely in your browser with zero dependencies.

Formulas

The dataToItem function applies a recursive type-mapping function T to each value v in the input object:

T(v) =

{

{S: v} if typeof v = "string"{N: String(v)} if typeof v = "number"{BOOL: v} if typeof v = "boolean"{NULL: TRUE} if v = NULL{L: v.map(T)} if Array.isArray(v){M: mapValues(v, T)} if typeof v = "object"omitted if v = undefined

The reverse function T⁻¹ inspects the single key of each attribute descriptor and unwraps accordingly. For N types, the string is parsed via Number() to restore the numeric value.

The deltaToUpdateParams function partitions keys into three action sets:

UpdateExpression = REMOVE k₁, k₂ SET k₃ = :k₃ ADD k₄ :k₄

Where k ∈ R (the set of 573 DynamoDB reserved words) triggers aliasing: the key is replaced with #k in the expression and mapped in ExpressionAttributeNames.

Reference Data

JS Type	DynamoDB Descriptor	DynamoDB Example	Notes
`string`	`S`	`{"S": "hello"}`	Non-empty strings only
`number`	`N`	`{"N": "42"}`	Stored as string representation
`boolean`	`BOOL`	`{"BOOL": true}`	Native boolean
`null`	`NULL`	`{"NULL": true}`	Explicit null marker
`undefined`	-	Omitted	Stripped from output; triggers REMOVE in delta
`object` (plain)	`M`	`{"M": {"a": {"S": "x"}}}`	Recursive map wrapping
`Array`	`L`	`{"L": [{"N": "1"}]}`	Heterogeneous list
`string[]` (set)	`SS`	`{"SS": ["a", "b"]}`	Homogeneous string set (opt-in)
`number[]` (set)	`NS`	`{"NS": ["1", "2"]}`	Homogeneous number set (opt-in)
`Buffer[]` (set)	`BS`	`{"BS": ["dGVzdA=="]}`	Binary set, base64 encoded
`Date`	`S`	`{"S": "2024-01-01T00:00:00.000Z"}`	With date serialization enabled
Empty string `""`	`S`	`{"S": ""}`	Allowed since DynamoDB update 2020
`NaN`	-	Error	Not a valid DynamoDB number
`Infinity`	-	Error	Not a valid DynamoDB number
Nested depth > 32	`M`/`L`	Deep nesting	DynamoDB supports up to 32 levels
Item size	-	-	Max 400 KB per item

Frequently Asked Questions

DynamoDB uses arbitrary-precision decimal encoding internally. Transmitting numbers as strings (e.g., {"N": "3.14"}) avoids floating-point precision loss during JSON serialization. The SDK and this converter handle the String ↔ Number coercion automatically. Be aware that JavaScript Number has IEEE 754 double-precision limits: integers beyond 2^53 − 1 will lose precision upon reconversion.

They are distinct. A null value produces {"NULL": true} in the DynamoDB schema - the attribute exists with an explicit null marker. An undefined value is omitted entirely from the output item. In deltaToUpdateParams mode, undefined triggers a REMOVE action (deleting the attribute), while null triggers a SET action with the NULL descriptor.

DynamoDB sets (SS for string sets, NS for number sets) enforce uniqueness and are homogeneous - all elements must be the same type. Lists (L) allow mixed types and duplicates. Use sets when you need atomic add/delete operations via ADD in update expressions. This converter offers a "Treat homogeneous arrays as sets" option. Without it, all arrays become L descriptors.

DynamoDB has 573 reserved words (e.g., "status", "name", "count", "data", 'object'). Using them directly in UpdateExpression causes a ValidationException. The deltaToUpdateParams function checks every key against the full reserved words list and automatically creates ExpressionAttributeNames aliases (e.g., #status → status). This is transparent - the output includes the alias mapping.

This tool does not enforce the 400 KB limit because accurate size calculation requires DynamoDB's internal encoding rules (attribute name lengths + value encoding overhead), which differ from JSON byte size. The tool will show a warning if the serialized JSON output exceeds 350 KB as a rough heuristic, but you should validate exact sizes using the AWS SDK's marshalling utilities for production writes.

DynamoDB supports a maximum nesting depth of 32 levels for map (M) and list (L) attributes. This converter enforces a safety limit of 50 recursion levels to prevent stack overflow in the browser. If your object exceeds 32 levels, the conversion will succeed but DynamoDB will reject the item on write. The tool displays a warning when depth exceeds 32.