awsjson
awsjson: The Complete Guide to JSON Handling Across the AWS Ecosystem (2025 Edition)
JSON is the lingua franca of modern cloud infrastructure. Nowhere is this more evident than in AWS, where every major service—from Lambda and API Gateway to DynamoDB and CloudFormation—relies on JSON as its primary serialization format. Yet "awsjson" isn't a single specification. It's an umbrella term that spans multiple protocols, SDK conventions, and service-specific behaviors. This guide dissects every layer.
Key Takeaways
- AWS JSON protocol (v1 & v2) is the wire-format standard for most modern AWS APIs, distinct from the older query-based protocol.
- apiGatewayHttp and aws-json-1.0 / aws-json-1.1 are media-type conventions used by API Gateway and SDK clients respectively.
- Lambda expects JSON-shaped handler signatures; both the invocation payload and response must serialize cleanly as JSON.
- DynamoDB uses a custom type-serialization layer (
M,L,N) that sits on top of JSON, not raw JSON. - CloudFormation templates are JSON (or YAML) documents that describe infrastructure declaratively.
- PartiQL brings SQL-style queries to JSON-capable stores like DynamoDB and Amazon Veneur.
- Content-Type negotiation matters:
application/jsonvsapplication/vnd.aws.apigateway+jsonare not interchangeable.
What Exactly Is "awsjson"?
Not a Single Format — A Family of Conventions
The term awsjson does not map to one RFC or AWS specification. Instead, it refers to a cluster of related JSON serialization strategies that AWS services use to exchange data. Understanding the distinction between them is critical for architects who need to build robust integrations across services.
The AWS JSON Protocol (v1 and v2)
AWS defines two formal JSON wire protocols for service-to-service communication:
- AWS JSON 1.0 — Used by legacy-first-generation services (e.g., early CloudWatch Logs, CodeBuild). Payloads follow the structure
{"X-Amz-Target": "...", "input": {...}}. - AWS JSON 1.1 — An evolved version used by newer services with richer error shapes and streaming support. It removes the
X-Amz-Targetheader in favor of path-based routing.
These protocols are negotiated at the SDK level. When you call describeInstances() via the AWS SDK for JavaScript, the SDK wraps your request in the appropriate JSON envelope before signing it with SigV4.
Comparing AWS JSON Serialization Formats Across Services
The table below breaks down how each major AWS service handles JSON serialization, the protocol variant in use, and the expected Content-Type for both inbound and outbound traffic.
| Service | Protocol / Media Type | Inbound Content-Type | Outbound Content-Type | Notes |
|---|---|---|---|---|
| API Gateway (REST) | aws-json-1.0 / aws-json-1.1 | application/json | application/json | Integration request/response mapping uses velocity templates or passthrough. |
| API Gateway (HTTP API) | apiGatewayHttp | application/json | application/json | Lighterweight than REST; native JSON payloads without wrapper envelopes. |
| AWS Lambda | Native JSON event model | application/json | application/json | Handler receives a plain JS object after SDK parsing; response must be JSON-serializable. |
| DynamoDB | DynamoDB JSON (custom types) | application/x-amz-json-1.0 | application/x-amz-json-1.0 | Uses M, L |
| CloudFormation | CloudFormation JSON | application/json | application/json | Declarative template schema. UTF-8 encoded. 64 KB limit on inline templates via CLI. |
| SNS | aws-json-1.0 | application/json | application/json | Messages arrive wrapped in an SNS envelope; subscriber receives parsed JSON object. |
| Kinesis Data Streams | Kinesis protocol (custom binary + JSON metadata) | application/x-ndjson | application/x-ndjson | Each record carries a base64-encoded payload; metadata is JSON. |
| Step Functions | Amazon States Language (JSON) | application/json | application/json | State machines defined as JSON; $$. context objects available at runtime. |
| EventBridge | CloudEvents-compatible JSON | application/json | application/json | Structured events follow CloudEvents spec with AWS extensions. |
| SQS | Text-based JSON messages | text/plain / application/json | text/plain | Sends raw strings; JSON parsing is client responsibility. |
API Gateway and the aws-json-1.0 / aws-json-1.1 Distinction
API Gateway is where most developers first encounter the nuance of AWS JSON formats. The platform supports two routing models, each with its own expectations:
REST APIs (aws-json-1.0)
REST APIs use the aws-json-1.0 protocol for Lambda integrations. The integration request mapping template typically transforms the incoming JSON into the shape Lambda expects. A common pitfall: forgetting that API Gateway sends all request parameters (path, query, headers, body) merged into a single object unless you explicitly separate them in the mapping template.
HTTP APIs (apiGatewayHttp)
HTTP APIs introduced a simpler model. The apiGatewayHttp protocol passes raw JSON directly to the Lambda handler without the wrapper envelope. This reduces latency and mapping complexity but sacrifices some features (stage variables, usage plans) available in REST APIs.
Choosing the Right Protocol
- Use REST API + aws-json-1.0 when you need advanced features: request validation, throttling per method, authorizers, and deployment stages.
- Use HTTP API + apiGatewayHttp when latency and cost are priorities and your payloads are straightforward JSON.