Beginner7 min read

DynamoDB JSON & Marshalling

The first time you read raw data from the DynamoDB API, it doesn't look like the JSON you put in. A plain object like {"status": "open", "priority": 3} comes back as {"status": {"S": "open"}, "priority": {"N": "3"}}.

Every value is wrapped in a one-key object naming its type. That wrapping is DynamoDB JSON, and converting to and from it is called marshalling.

What is DynamoDB JSON?

It is the type-tagged wire format of the DynamoDB API. The tag is what lets DynamoDB carry types plain JSON can't express (sets, binary) and keep numbers exact.

  • Every value carries its type: {"S": "..."} for a string, {"N": "..."} for a number, and so on through the ten DynamoDB data types: S, N, B, BOOL, NULL, L, M, SS, NS, BS.
  • Marshalling = plain JSON → DynamoDB JSON. Unmarshalling = the reverse.
  • Numbers are strings on the wire: {"N": "3"}, not {"N": 3}.
  • Don't write it by hand. The SDK's document client (or marshall()) does it for you; read it raw only when debugging a low-level request or a log line.

The problem: plain JSON isn't enough

JSON has string, number and boolean scalars, plus null, arrays and objects.

DynamoDB has more: binary, and three set types (string set, number set, binary set) that JSON can't express at all. A JSON array can't say whether it is a list or a set.

Numbers are the other gap. Without a tag, the string "3" could be a String or a Number, so the tag states which one DynamoDB should store. The tag is how every request and response states each value's exact type, losslessly.

How the encoding works

Every attribute value becomes a single-key object whose key is a type descriptor: S, N, B, BOOL, NULL, L, M, SS, NS or BS. The data types guide has the full table with an example of each, and which types can be keys.

Lists and maps nest the same descriptors all the way down, so a deeply structured item becomes deeply wrapped. The format is defined in the AWS low-level API reference.

Numbers ride the wire as strings on purpose. DynamoDB keeps up to 38 digits of precision, while most JSON parsers, JSON.parse among them, read a JSON number as an IEEE-754 double, good for about 15 to 17 significant digits.

Worked example: an audit-log entry

Plain JSON you'd write in your app:

{
  "actor": "u-204",
  "action": "ticket.close",
  "ticketId": 8842,
  "tags": ["billing", "urgent"],
  "redacted": false
}

Marshalled to DynamoDB JSON for the API:

{
  "actor": {"S": "u-204"},
  "action": {"S": "ticket.close"},
  "ticketId": {"N": "8842"},
  "tags": {"SS": ["billing", "urgent"]},
  "redacted": {"BOOL": false}
}

ticketId became N with a string value. tags as a string set (SS) is a modeling choice: a generic converter fed plain JSON emits L, because a JSON array is ordered and can repeat, while SS dedupes and is unordered.

No converter can make that call for you, so you make it in code, as the next section shows.

Converting in code

In JavaScript, @aws-sdk/util-dynamodb converts in both directions, and @aws-sdk/lib-dynamodb (the document client) runs the same conversion on every request and response:

import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
import {DynamoDBDocumentClient, PutCommand} from '@aws-sdk/lib-dynamodb';
import {marshall, unmarshall} from '@aws-sdk/util-dynamodb';

// A JS Set marshals to SS (or NS); an array marshals to L.
const item = {actor: 'u-204', ticketId: 8842, tags: new Set(['billing', 'urgent'])};
marshall(item); // { actor: {S: 'u-204'}, ticketId: {N: '8842'}, tags: {SS: ['billing', 'urgent']} }
unmarshall({ticketId: {N: '8842'}}); // { ticketId: 8842 }

const doc = DynamoDBDocumentClient.from(new DynamoDBClient({}), {
  marshallOptions: {removeUndefinedValues: true}
});
await doc.send(new PutCommand({TableName: 'AuditLog', Item: item}));

On the way back, plain unmarshall turns {"N": "3.14159265358979323846"} into 3.141592653589793 without an error; a large integer comes back as a BigInt, and a large decimal throws. Where precision matters, pass wrapNumbers: true (unmarshallOptions on the document client) to get every number as a NumberValue holding the exact string.

Other SDKs ship the same pair: in Python, boto3's resource layer and TypeSerializer/TypeDeserializer do this job.

Without code, paste plain JSON into the DynamoDB JSON converter to marshal it (and back). When you're assembling a request, the DynamoDB expression builder emits the correctly marshalled attribute-value map alongside the expression.

Low-level client vs document client

The AWS SDK for JavaScript offers two layers:

LayerInput shapeWho marshals
@aws-sdk/client-dynamodb (low-level)DynamoDB JSON AttributeValue mapsYour code or helper
@aws-sdk/lib-dynamodb (document)Plain JS objectsSDK on send/receive

Default to the document client. It marshals Item, Key and the ExpressionAttributeValues of any command, so hand-written update expressions take plain values too. You need raw AttributeValue maps only on the low-level client.

Expression attribute values are marshalled too

On the low-level client, ConditionExpression, UpdateExpression and FilterExpression placeholders (:val, :inc) map to marshalled values in ExpressionAttributeValues:

{
  ":status": {"S": "open"},
  ":count": {"N": "1"}
}

Send "open" without the S wrapper and the request fails: DynamoDB can't read a bare string as an attribute value. The expression builder emits the map alongside the expression string, so placeholders and types stay aligned.

Attribute names that collide with reserved words use ExpressionAttributeNames (#st) instead; the checker tool outputs the alias map ready to paste.

Marshalling failures in tests

  • Empty sets: DynamoDB rejects an empty SS/NS/BS. Omit the attribute instead.
  • Floats in N: send "3.14" as a string, not a JSON number, on the wire.
  • Binary in Node: a Uint8Array in SDK code; base64 in raw JSON.
  • Undefined values: the document client drops a top-level attribute set to undefined, but throws Pass options.removeUndefinedValues=true to remove undefined values from map/array/set. on one inside a map or list.
  • The fix for undefined: marshall() throws even at the top level, so set removeUndefinedValues: true, as in the snippet above, to strip them all.
  • Empty strings in keys: allowed on non-key attributes since 2020, rejected on table and index key attributes.
  • The fix for empty keys: for a GSI or LSI key, omit the attribute instead of writing ""; the item stays out of that index (a sparse index) and the write succeeds. For a table key, use a non-empty sentinel value.

When a Lambda logs raw API responses, paste one item into the DynamoDB JSON converter to get readable plain JSON before diffing against fixtures.

Do the type tags make items bigger?

On the wire, yes; in the item, no. The audit-log entry above is 102 bytes of plain JSON and 138 bytes once marshalled, about 35% more request payload.

DynamoDB doesn't store or bill those tags. An item's size is the sum of its attribute names and values, so the same entry is 65 bytes, and a boolean flag costs its name plus 1 byte. The item size limit guide has the full accounting.

Before bulk-loading marshalled items, check a sample in the item-size calculator. A BatchWriteItem takes up to 25 put or delete requests, each item up to 400 KB, and usually the count of 25 binds first.

AWS words the 16 MB cap two ways. The constraints page counts "the total size of all the items written"; the API reference rejects a batch when "The total request size exceeds 16 MB", and under that reading the type tags count too.

DynamoDB Local 3.3.1 follows the request reading: 25 items billed at about 197 KB each (long lists of numbers) made a 16.8 MB request, and it was refused.

So chunk tag-heavy items (long number lists, many small attributes) by serialized size as well as by count, which keeps a batch under the cap on either reading.

Converting in DynoTable

In the app, the item editor shows plain values by default and marshals them when you commit. To debug an item from CloudWatch logs, switch the editor to its DynamoDB JSON view to see the exact tags, then back to Plain JSON to edit.

From the grid's right-click menu, Copy as → JSON or Copy as → DynamoDB-JSON puts either form on your clipboard for a ticket or a test fixture.

DynoTable showing an item as plain values, with the raw DynamoDB JSON available.
DynoTable showing an item as plain values, with the raw DynamoDB JSON available.

Pitfalls + next steps

  • Numbers are strings in DynamoDB JSON: {"N": "3"}. Quoting matters; don't emit a bare number.
  • Sets vs lists is a modeling decision the encoding makes visible. Pass a Set when you mean SS/NS (see data types).
  • Prefer the document client over hand-marshalling in app code, with removeUndefinedValues on, and wrapNumbers wherever precision matters.
  • Omit empty key attributes rather than writing "" to them.

To read items as plain values instead of decoding type tags by eye, download DynoTable and open any item in the editor.

By Dmitriy · Updated