DynamoDB JSON

Warnings

• breaking Older versions of dynamodb-json (pre-1.3) might have compatibility issues with Python 3.4+ due to changes in `.next()` iterator syntax. Specifically, version 1.2 addressed Python 3.4+ compatibility and version 1.3 addressed Python 3.5+ compatibility by changing `.next()` to `next()`.
  Fix: Upgrade to dynamodb-json version 1.3 or higher (`pip install --upgrade dynamodb-json`) to ensure full compatibility with modern Python 3 environments.
• gotcha DynamoDB does not natively support floating-point numbers and expects numerical values to be represented as `Decimal` types to avoid precision issues. While `dynamodb-json` handles this conversion during marshalling/unmarshalling, users must ensure their Python applications use `Decimal` for numbers that might otherwise be floats.
  Fix: Always use `decimal.Decimal` objects for numerical values in your Python data when interacting with DynamoDB via `dynamodb-json` to maintain precision and prevent DynamoDB `ValidationException` errors.
• gotcha DynamoDB has specific data type representations (e.g., `{'S': 'string'}`, `{'N': '123'}`). Manually constructing or parsing DynamoDB JSON without `dynamodb-json` can lead to `ValidationException` errors if the format or types are incorrect.
  Fix: Always use `dynamodb_json.json_util.dumps` and `dynamodb_json.json_util.loads` for converting between Python objects and DynamoDB's specific JSON format to ensure correct type marshalling and unmarshalling.

Install

• pip install dynamodb-json Install latest version

Imports

• json_util

  from dynamodb_json import json_util as json

  The primary functionality is exposed via the 'json_util' module, which is commonly aliased as 'json' for consistency with Python's standard json library.

Quickstart

This quickstart demonstrates how to use `dynamodb-json` to convert a standard Python dictionary containing various data types (including `datetime` and `Decimal`) into the DynamoDB-specific JSON format (`dumps`) and then convert a DynamoDB JSON string back into a Python dictionary (`loads`). This is crucial for interacting with the AWS DynamoDB API which expects this specific format.

import os
from datetime import datetime
from decimal import Decimal
from dynamodb_json import json_util as json

# Example Python object with various data types
python_object = {
    "Id": 123,
    "Name": "Example Item",
    "IsActive": True,
    "Price": Decimal('99.99'), # DynamoDB expects Decimal for numbers
    "CreatedAt": datetime.now(),
    "Tags": ["aws", "python", "json"],
    "Details": {
        "Key": "Value",
        "Number": 456
    }
}

# 1. Marshal Python object to DynamoDB JSON format
dynamodb_json_format = json.dumps(python_object)
print("DynamoDB JSON Format:")
print(dynamodb_json_format)

# Example DynamoDB JSON string (as if received from DynamoDB)
# Note: datetime objects are converted to ISO 8601 strings during dumps
# and then parsed back to datetime during loads if possible.
# Decimals are preserved.
db_json_string = '{"Id": {"N": "123"}, "Name": {"S": "Example Item"}, "IsActive": {"BOOL": true}, "Price": {"N": "99.99"}, "CreatedAt": {"S": "2026-04-10T18:54:00.000000"}, "Tags": {"L": [{"S": "aws"}, {"S": "python"}, {"S": "json"}]}, "Details": {"M": {"Key": {"S": "Value"}, "Number": {"N": "456"}}}}'

# 2. Unmarshal DynamoDB JSON format back to Python object
python_object_from_db = json.loads(db_json_string)
print("\nPython Object from DynamoDB JSON:")
print(python_object_from_db)
print(f"Type of Price: {type(python_object_from_db['Price'])}")
print(f"Type of CreatedAt: {type(python_object_from_db['CreatedAt'])}")