{"id":2488,"library":"dynamodb-json","title":"DynamoDB JSON","description":"dynamodb-json is a Python utility library designed to simplify the process of converting Python objects to and from the specific JSON format used by Amazon DynamoDB. It handles the marshalling and unmarshalling of various Python data types, including decimals and datetimes, into the DynamoDB-compatible JSON structure. The current version is 1.4.2 and it maintains an active release cadence, with recent updates focusing on compatibility and bug fixes.","status":"active","version":"1.4.2","language":"en","source_language":"en","source_url":"https://github.com/Alonreznik/dynamodb-json","tags":["DynamoDB","AWS","JSON","serialization","deserialization","data types","boto3"],"install":[{"cmd":"pip install dynamodb-json","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"The primary functionality is exposed via the 'json_util' module, which is commonly aliased as 'json' for consistency with Python's standard json library.","wrong":"import dynamodb_json","symbol":"json_util","correct":"from dynamodb_json import json_util as json"}],"quickstart":{"code":"import os\nfrom datetime import datetime\nfrom decimal import Decimal\nfrom dynamodb_json import json_util as json\n\n# Example Python object with various data types\npython_object = {\n    \"Id\": 123,\n    \"Name\": \"Example Item\",\n    \"IsActive\": True,\n    \"Price\": Decimal('99.99'), # DynamoDB expects Decimal for numbers\n    \"CreatedAt\": datetime.now(),\n    \"Tags\": [\"aws\", \"python\", \"json\"],\n    \"Details\": {\n        \"Key\": \"Value\",\n        \"Number\": 456\n    }\n}\n\n# 1. Marshal Python object to DynamoDB JSON format\ndynamodb_json_format = json.dumps(python_object)\nprint(\"DynamoDB JSON Format:\")\nprint(dynamodb_json_format)\n\n# Example DynamoDB JSON string (as if received from DynamoDB)\n# Note: datetime objects are converted to ISO 8601 strings during dumps\n# and then parsed back to datetime during loads if possible.\n# Decimals are preserved.\ndb_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\"}}}}'\n\n# 2. Unmarshal DynamoDB JSON format back to Python object\npython_object_from_db = json.loads(db_json_string)\nprint(\"\\nPython Object from DynamoDB JSON:\")\nprint(python_object_from_db)\nprint(f\"Type of Price: {type(python_object_from_db['Price'])}\")\nprint(f\"Type of CreatedAt: {type(python_object_from_db['CreatedAt'])}\")\n","lang":"python","description":"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."},"warnings":[{"fix":"Upgrade to dynamodb-json version 1.3 or higher (`pip install --upgrade dynamodb-json`) to ensure full compatibility with modern Python 3 environments.","message":"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()`.","severity":"breaking","affected_versions":"<1.3"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}