JSON to XML conversion: root elements, arrays and invalid tag names

The array with no name — a top-level JSON array that has to become a single-rooted XML document, and the wrapper element that appears

JSON can begin with `[1,2]`; XML cannot begin with two peer document elements. ToolAcre therefore wraps a root array in the selected root name and writes each member as a repeated `<item>` child. The warning names that convention, because the wrapper and item names were not present in the source.

Choosing `numbers` yields one `<numbers>` document element containing two item elements. The conversion is deterministic, but not canonical: another system might require `<number>` or an attribute-bearing collection. Set the root deliberately and compare the result with the receiver’s required XML contract.

XML needs exactly one root — why every conversion invents or asks for a root element name

An XML document must have exactly one root element. A JSON object with exactly one ordinary top-level key can use that key directly. A multi-key object, array, scalar or null has no single supplied name, so the writer encloses it in `root` unless the user provides another legal name.

The wrapper rule is implemented before serialization and surfaced as a warning. It is not discovered by a schema and does not claim that `<root>` has meaning to the legacy service. Naming the envelope is part of integration design, while the converter only guarantees well-formed structure under its own mapping.

Arrays have no XML equivalent — repeating an element per item, and how arrays of scalars and arrays of arrays are represented

Arrays become repeated elements. At the document root, members use `<item>` beneath the wrapper. Inside an object, an array stored under `line` becomes repeated `<line>` siblings. Arrays of objects create repeated elements with child fields; nested arrays have no domain names and inherit the generic structure produced by the builder.

This loses the distinction between one array member and a scalar with the same element name after a later XML-to-JSON read. XML provides occurrences, not an independent array marker. If stable cardinality matters, a schema or application mapping must supply it; a generic serializer cannot prove it from JSON-shaped element names alone.

Keys that cannot be element names — names starting with a digit, containing spaces or punctuation, or beginning with 'xml', and how converters rename or escape them

The outline suggested converters may rename or escape illegal keys. ToolAcre explicitly refuses them. A key with a space, one beginning with a digit or hyphen, or one beginning with the reserved letters `xml` triggers `UNSUPPORTED_SHAPE` and names the offending path. Silent renaming would produce XML that matches no agreed schema.

Valid names may begin with a letter, underscore or namespace-style prefix and may contain digits, periods, underscores, colons and hyphens after the start. Attribute keys use `@` only as the JSON convention; the remaining attribute name must pass the same check. Rename the source key intentionally or choose another target format.

Keys that cannot be element names are refused, never renamed or escaped

Numbers and booleans are serialized as element text, so their JSON type is no longer declared by XML. The default reverse reader consequently returns strings. Null has no XML representation here: it becomes an empty element, indistinguishable from an empty string, and the writer reports how many values underwent that change.

This means `{ "a": null, "b": "" }` can produce two empty elements that read back alike. Calling that round trip lossless would be false. Attributes, `#text` and `#cdata` preserve the converter’s structural convention, but they do not add a general XML type system.

Types become XML text, while null becomes an admitted empty-element ambiguity

Use `{"order":{"@id":"A-7","customer":"Ada","line":[{"sku":"P1","qty":2},{"sku":"P2","qty":1}],"note":null}}`. The single `order` key becomes the root, `@id` becomes an attribute, each line object becomes a repeated `<line>`, and null becomes an empty `<note></note>` with a warning.

Read the output back with inference disabled. Attribute id, quantity and text values are strings, and line is an array because it appears twice. This demonstrates the exact supported inverse while exposing the lost null and numeric types. A receiving order schema may demand other names or ordering, which this example does not validate.

What this does not cover — producing XML that matches a given XSD or namespace, which needs a mapping written by hand

The writer does not consume an XSD, assign namespace URIs or decide element order from a business schema. It writes an XML declaration and never emits a DOCTYPE. Keys containing namespace prefixes are preserved literally, but that is not namespace resolution or proof that the prefix is declared correctly.

Generating XML accepted by a specific service can require attributes, sequence constraints, choice groups and qualified names. Use its current schema or documentation to build that mapping. A generic conversion is suitable for inspection and simple data-centric documents, not a substitute for contract-aware serialization.

Takeaway: predict the shape before you depend on it — and how the Syntax converters panel shows the XML structure a JSON document produces

Predict the envelope, item names and type loss before depending on the result. ToolAcre wraps values lacking one root, repeats arrays, maps `@` keys to attributes, replaces null with empty text and refuses illegal names rather than guessing replacements. Every non-obvious change appears in output or warnings.

Test the smallest object that includes a top-level array, repeated records, null, numeric text and an awkward key. A refusal is useful evidence that manual mapping is required. A successful file still needs validation by the actual receiver, because well-formed XML and schema-valid XML are different claims.

After the receiver accepts a specimen, add a reverse inspection only where the mapping is expected to survive. Attributes and repeated children can round-trip under ToolAcre’s own convention, while null and scalar types cannot. Recording that distinction prevents a successful happy-path example from being generalized to every order document your integration may produce.