XMLJSONConverter

A small, efficient tool to convert JSON to XML and XML to JSON in a streamed way.

Features

• Streamed Conversion: Uses ijson and lxml.etree.iterparse to handle large files without loading them entirely into memory.
• Unopinionated XML to JSON: Automatically detects and groups repeated elements into JSON arrays.
• Configurable:
  • Support for custom root tags and array element tags in JSON-to-XML.
  • Configurable attribute and text value mapping in XML-to-JSON.
  • Option to include or exclude the XML root element in JSON output.
• CLI Support: Easy-to-use command-line interface with click.

Installation

Ensure you have uv installed.

uv sync

Usage

The tool provides a CLI named xmljsonconverter.

JSON to XML

By default, the tool provides the json2xml subcommand.

# Using stdin/stdout
echo '{"name": "John", "age": 30}' | uv run xmljsonconverter json2xml

# Specifying files
uv run xmljsonconverter json2xml input.json output.xml

# Custom root and array tags
echo '{"tags": ["a", "b"]}' | uv run xmljsonconverter json2xml --root data --array-tag element
# Output: <data><tags><element>a</element><element>b</element></tags></data>

XML to JSON

Use the xml2json subcommand to convert XML back to JSON.

# Basic conversion
echo '<root><user>John</user><user>Jane</user></root>' | uv run xmljsonconverter xml2json
# Output: {"user": ["John", "Jane"]}

# Including the root element
echo '<root><name>John</name></root>' | uv run xmljsonconverter xml2json --include-root
# Output: {"root": {"name": "John"}}

# Handling attributes
echo '<root><user id="1">John</user></root>' | uv run xmljsonconverter xml2json
# Output: {"user": {"_attributes": {"id": "1"}, "_value": "John"}}

# Custom attribute and value keys
echo '<root><user id="1">John</user></root>' | uv run xmljsonconverter xml2json --attr-key "@" --value-key "#"
# Output: {"user": {"@": {"id": "1"}, "#": "John"}}

CLI Subcommands and Options

json2xml

• INPUT: Input file (default: - for stdin).
• OUTPUT: Output file (default: - for stdout).
• --root TEXT: Root XML tag (default: root).
• --array-tag TEXT: XML tag name for JSON array elements (default: item).

xml2json

• INPUT: Input file (default: - for stdin).
• OUTPUT: Output file (default: - for stdout).
• --attr-key TEXT: JSON key for XML attributes (default: _attributes).
• --value-key TEXT: JSON key for XML text value when attributes are present (default: _value).
• --include-root: Include the XML root element in the JSON output.

Development

Running Tests

uv run pytest

Linting and Formatting

uv run ruff check .
uv run ruff format .

Type Checking

uv run mypy src

License

Distributed under the GPLv3 License. See LICENSE for more information.