FREE TOOL

DynamoDB JSON Converter

Convert DynamoDB JSON to plain JSON and JSON back to DynamoDB JSON. It runs in your browser, nothing you paste is sent anywhere.

{
 "id": {
  "S": "order-1001"
 },
 "total": {
  "N": "49.9"
 },
 "paid": {
  "BOOL": true
 },
 "items": {
  "L": [
   {
    "S": "book"
   },
   {
    "S": "pen"
   }
  ]
 },
 "customer": {
  "M": {
   "name": {
    "S": "Jane Doe"
   },
   "email": {
    "NULL": true
   }
  }
 }
}

DynamoDB Item Size Calculator → DynamoDB Expression Builder →DynamoDB TTL Converter →Data types legend →

One item uses put-item, several use batch-write-item in requests of up to 25 items.

aws dynamodb put-item \
  --table-name YourTable \
  --item '{
  "id": {
    "S": "order-1001"
  },
  "total": {
    "N": "49.9"
  },
  "paid": {
    "BOOL": true
  },
  "items": {
    "L": [
      {
        "S": "book"
      },
      {
        "S": "pen"
      }
    ]
  },
  "customer": {
    "M": {
      "name": {
        "S": "Jane Doe"
      },
      "email": {
        "NULL": true
      }
    }
  }
}'

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

// The document client takes plain JSON and converts it to DynamoDB JSON itself.
const client = DynamoDBDocumentClient.from(new DynamoDBClient({}));

const item = {
  "id": "order-1001",
  "total": 49.9,
  "paid": true,
  "items": [
    "book",
    "pen"
  ],
  "customer": {
    "name": "Jane Doe",
    "email": null
  }
};

await client.send(new PutCommand({TableName: "YourTable", Item: item}));

import json
from decimal import Decimal

import boto3

table = boto3.resource('dynamodb').Table("YourTable")
item = json.loads(r"""{
  "id": "order-1001",
  "total": 49.9,
  "paid": true,
  "items": [
    "book",
    "pen"
  ],
  "customer": {
    "name": "Jane Doe",
    "email": null
  }
}""", parse_float=Decimal)

table.put_item(Item=item)

Working with DynamoDB? It is a core topic of the AWS Developer Associate examTry free DVA-C02 practice questions with answers and explanations.DVA-C02 questions →

What is DynamoDB JSON?

DynamoDB JSON is the format the DynamoDB API uses for items: every value is wrapped in an object whose only key is a type descriptor - S for a string, N for a number, M for a map and so on. The same item in plain JSON and in DynamoDB JSON:

{"id": "order-1001", "total": 49.9, "paid": true}

{
  "id": {"S": "order-1001"},
  "total": {"N": "49.9"},
  "paid": {"BOOL": true}
}

You meet it wherever the low-level API shows through:

AWS CLI commands - get-item, scan and query print it, and put-item and batch-write-item expect it;
the low-level SDK clients, such as DynamoDBClient in the AWS SDK for JavaScript v3 or boto3.client('dynamodb');
DynamoDB Streams records and exports to Amazon S3;
the DynamoDB console, whose JSON view switches between both formats with "View DynamoDB JSON".

Creating an item in the DynamoDB console with View DynamoDB JSON switched on — Creating an item in the DynamoDB console, JSON view with "View DynamoDB JSON" on

DynamoDB JSON data types

Type	Descriptor	Example
String	`S`	`{"S": "Jane"}`
NumberAlways written as a string, so no precision is lost (up to 38 digits).	`N`	`{"N": "49.9"}`
Boolean	`BOOL`	`{"BOOL": true}`
Null	`NULL`	`{"NULL": true}`
BinaryBase64-encoded.	`B`	`{"B": "aGVsbG8="}`
ListOrdered, values of any type.	`L`	`{"L": [{"S": "book"}, {"N": "2"}]}`
MapNested attributes.	`M`	`{"M": {"name": {"S": "Jane"}}}`
String setUnique values, never empty.	`SS`	`{"SS": ["red", "blue"]}`
Number set	`NS`	`{"NS": ["1", "2.5"]}`
Binary set	`BS`	`{"BS": ["aGVsbG8=", "d29ybGQ="]}`

What the converter accepts

a single item, or an array of items, in either format;
AWS CLI output as it is printed: {"Item": ...} from get-item and {"Items": [...]} from scan and query;
a DynamoDB export to Amazon S3 file, one {"Item": ...} per line.

Numbers too large for a JavaScript number, such as 20-digit ids, stay exact: they come out as strings instead of losing digits. Sets become JSON arrays, and JSON arrays become lists (L) - DynamoDB cannot tell from plain JSON that an array was meant as a set, so change L to SS or NS yourself where you need one. Everything runs in your browser; nothing you paste is sent anywhere.

An item can be at most 400 KB - check yours with the DynamoDB item size calculator.

How to convert DynamoDB JSON in code

JavaScript and TypeScript (AWS SDK v3)

@aws-sdk/util-dynamodb converts in both directions. Numbers beyond JavaScript's safe integer range need wrapNumbers, and removeUndefinedValues skips undefined properties instead of failing.

import {marshall, unmarshall} from '@aws-sdk/util-dynamodb';

const item = unmarshall(dynamoDbJsonItem, {wrapNumbers: true});
const dynamoDbJson = marshall(plainObject, {removeUndefinedValues: true});

For reads and writes you rarely need either: DynamoDBDocumentClient from @aws-sdk/lib-dynamodb takes and returns plain JavaScript objects and converts them itself.

Python (boto3)

boto3.dynamodb.types converts one attribute value at a time. boto3 rejects floats, so load JSON numbers as Decimal.

import json
from decimal import Decimal

from boto3.dynamodb.types import TypeDeserializer, TypeSerializer

item = {key: TypeDeserializer().deserialize(value) for key, value in dynamodb_json_item.items()}

plain = json.loads(plain_json_text, parse_float=Decimal)
dynamodb_json = {key: TypeSerializer().serialize(value) for key, value in plain.items()}

The resource interface, boto3.resource('dynamodb').Table(...), converts on its own, like the document client.

Frequently asked questions

Why are numbers strings in DynamoDB JSON?

DynamoDB stores numbers with up to 38 digits of precision, more than a JSON number keeps in most languages. Sending them as strings lets every SDK read them without rounding.

Can I paste the output of the AWS CLI directly?

Yes. The converter unwraps Item and Items and ignores Count, ScannedCount, LastEvaluatedKey and ConsumedCapacity.

Is it safe to paste production data?

Yes. The conversion runs in your browser: what you paste is not uploaded, not processed on a server, not stored and not logged. The page only counts that the converter was used, never what you converted.

How do I write the converted items to a table?

Use the code under the converter: it gives the AWS CLI command (put-item for one item, batch-write-item for up to 25 at a time) and the same write in JavaScript and Python.

References

Supported data types and naming rules in Amazon DynamoDB
DynamoDB low-level API