Install & Compatibility
Where this runs
tested against v0.2.2 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
13MB installed
● package 13MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
JSONCodec
✓ from smithy_json import JSONCodec
✗ from smithy_json.emitters import JsonEmitter
JSONDocument
✓ from smithy_json import JSONDocument
Codec
✓ from smithy_json import Codec
This quickstart demonstrates how to create a Smithy `Node` object (representing a JSON structure) and then use `smithy_json.emitters.JsonEmitter` to serialize it into a JSON string. This process is central to generating JSON based on Smithy models.
import io
from smithy_python_types.main import Node
from smithy_json.emitters import JsonEmitter
# Create a Smithy Node representing a complex JSON object
node = Node.object({
"greeting": Node.string("Hello, Smithy!"),
"count": Node.number(123),
"enabled": Node.boolean(True),
"items": Node.array([
Node.string("item1"),
Node.object({"id": Node.number(1)}),
Node.null()
])
})
# Instantiate the JSON Emitter
emitter = JsonEmitter()
# Create a buffer to write the JSON output to
output_buffer = io.BytesIO()
# Emit the Node as JSON into the buffer
emitter.emit(node, output_buffer)
# Get the bytes from the buffer and decode to a string
json_output = output_buffer.getvalue().decode('utf-8')
print("Generated JSON:")
print(json_output)
# Example of parsing (optional)
# from smithy_json.parser import JsonParser
# parser = JsonParser()
# input_json = b'{"parsed_key": "parsed_value"}'
# parsed_node = parser.parse(io.BytesIO(input_json))
# print("\nParsed Node:", parsed_node)
Debug
Known issues
breakingThe `smithy-json` library, being in a 0.x.x version series, is subject to frequent API changes. Backwards compatibility is not guaranteed between minor versions (e.g., 0.2.x to 0.3.x).fixAlways pin your `smithy-json` dependency to a specific minor version (e.g., `smithy-json==0.2.*`) and review release notes carefully when upgrading. Consult the latest documentation and examples for API usage.
affects: All versions < 1.0.0
gotcha`smithy-json` is tightly coupled with `smithy-python-codegen-core` and `smithy-python-types`. Mismatched versions of these packages can lead to runtime errors or unexpected behavior.fixEnsure all `smithy-python` ecosystem packages are installed at compatible versions. Generally, `pip install smithy-json` will handle compatible dependencies, but manual installations or different package managers might require explicit version alignment. Refer to the `pyproject.toml` in the `smithy-python` monorepo for definitive compatibility.
affects: All versions
Upgrade
Version history
0.2.2latest on PyPI · released Apr 7, 2026
Audit
Dependencies
smithy-python-codegen-corerequiredCore components for Smithy code generation, essential for tooling.
smithy-python-typesrequiredDefines the fundamental Smithy AST Node types used for JSON representation.