{"id":10233,"library":"smithy-json","title":"Smithy JSON","description":"smithy-json provides robust JSON serialization and deserialization capabilities specifically for Smithy tooling within the Python ecosystem. It allows conversion between Smithy's abstract syntax tree (AST) representation (Nodes) and JSON strings. As part of the broader `smithy-python` project, it currently stands at version 0.2.2 and undergoes active development with frequent releases aligning with the main project.","status":"active","version":"0.2.2","language":"en","source_language":"en","source_url":"https://github.com/smithy-lang/smithy-python/tree/develop/packages/smithy-json","tags":["smithy","json","serialization","deserialization","codegen","aws"],"install":[{"cmd":"pip install smithy-json","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Core components for Smithy code generation, essential for tooling.","package":"smithy-python-codegen-core","optional":false},{"reason":"Defines the fundamental Smithy AST Node types used for JSON representation.","package":"smithy-python-types","optional":false}],"imports":[{"symbol":"JsonEmitter","correct":"from smithy_json.emitters import JsonEmitter"},{"symbol":"JsonParser","correct":"from smithy_json.parser import JsonParser"},{"note":"Node is part of the smithy-python-types dependency, crucial for working with smithy-json.","symbol":"Node","correct":"from smithy_python_types.main import Node"}],"quickstart":{"code":"import io\nfrom smithy_python_types.main import Node\nfrom smithy_json.emitters import JsonEmitter\n\n# Create a Smithy Node representing a complex JSON object\nnode = Node.object({\n    \"greeting\": Node.string(\"Hello, Smithy!\"),\n    \"count\": Node.number(123),\n    \"enabled\": Node.boolean(True),\n    \"items\": Node.array([\n        Node.string(\"item1\"),\n        Node.object({\"id\": Node.number(1)}),\n        Node.null()\n    ])\n})\n\n# Instantiate the JSON Emitter\nemitter = JsonEmitter()\n\n# Create a buffer to write the JSON output to\noutput_buffer = io.BytesIO()\n\n# Emit the Node as JSON into the buffer\nemitter.emit(node, output_buffer)\n\n# Get the bytes from the buffer and decode to a string\njson_output = output_buffer.getvalue().decode('utf-8')\n\nprint(\"Generated JSON:\")\nprint(json_output)\n\n# Example of parsing (optional)\n# from smithy_json.parser import JsonParser\n# parser = JsonParser()\n# input_json = b'{\"parsed_key\": \"parsed_value\"}'\n# parsed_node = parser.parse(io.BytesIO(input_json))\n# print(\"\\nParsed Node:\", parsed_node)\n","lang":"python","description":"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."},"warnings":[{"fix":"Always 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.","message":"The `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).","severity":"breaking","affected_versions":"All versions < 1.0.0"},{"fix":"Ensure 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.","message":"`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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-17T00:00:00.000Z","next_check":"2026-07-16T00:00:00.000Z","problems":[{"fix":"Ensure `smithy-python-types` is installed. If you installed `smithy-json` directly, it should pull `smithy-python-types` as a dependency. If not, run `pip install smithy-python-types` or `pip install smithy-json`.","cause":"The `smithy-python-types` package, which defines the core `Node` types, is a required dependency but is not installed or not accessible.","error":"ModuleNotFoundError: No module named 'smithy_python_types'"},{"fix":"Convert your Python data structures into `smithy_python_types.main.Node` objects (e.g., `Node.object({'key': Node.string('value')})`, `Node.array([Node.number(1)])`) before using them with `JsonEmitter` or `JsonParser`.","cause":"You are attempting to pass a standard Python dictionary or list directly to `JsonEmitter` or `JsonParser`, but `smithy-json` expects `smithy_python_types.main.Node` objects.","error":"AttributeError: 'dict' object has no attribute 'json_kind'"},{"fix":"Remember that `JsonEmitter` and `JsonParser` are classes. You must instantiate them first (e.g., `emitter = JsonEmitter()`) and then call their respective methods (`emitter.emit(node, output_buffer)` or `parser.parse(input_buffer)`).","cause":"You are trying to call `JsonEmitter()` without its required `emit` method, or `JsonParser()` without its `parse` method, possibly confusing the class with a function.","error":"TypeError: 'JsonEmitter' object is not callable"}]}