[rishitank]

What/Why/How?

Redoc v3 renders its XML examples with sample(schema, { format: 'xml' }, spec). I ported my old Redoc PR (Redocly/redoc#2347, XML/CSV examples) to v3 and compared its XML with Redoc v3's. I found cases where the XML sample is not well-formed, throws, or drops data. Each "Before" below is reproduced on main (1.7.8).

Case	Before	After
Root object with xml.name and a single property	<foo>string</foo>: root and name lost	<Thing><foo>string</foo></Thing>
Root xml.prefix / xml.namespace (non-$ref root)	dropped: <Pet>	<p:Pet xmlns:p="…">
Root array of strings	<root><0>s</0><1>t</1><2>r</2>…</root>	<root>string</root>
Root example array, e.g. { xml: { name: 'X' }, example: ['a', 'b'] }	<X>a</X><X>b</X>: two document elements	<X><X>a</X><X>b</X></X>
Root object whose only property is an unwrapped array	<book>…</book><book>…</book>: two document elements	<root><book>…</book><book>…</book></root>
Property example/default array, e.g. tags: { type: 'array', items: { type: 'string' }, example: ['a', 'b'] }	<0>a</0><1>b</1>	<tags>a</tags><tags>b</tags>
Example array under an allOf, e.g. allOf: [$ref Tags] next to xml	<root>a</root>…, or <0>a</0> inline	<tags>a</tags><tags>b</tags>
Example array whose items is a $ref	<0>…</0> on a property; two document elements at the root	items named after the $ref, as when sampled
Wrapped example array with items.xml.name	items named after the wrapper	items named by items.xml.name
allOf: [$ref Base, {properties…}]	extra <Base> wrapper around the ref's properties	properties merged into one element
Root composed allOf without xml.name	<root><p:Animal>…</p:Animal><age>…</age></root>	<p:Animal xmlns:p="…">…<age>…</age></p:Animal>: named after its first $ref
Root array whose items are allOf: [$ref Item, {properties…}]	one <item> with the other properties spilled beside it	one <item> per item, with all of its properties
allOf: [$ref Pet] with its own xml: { name: 'Critter' }	override ignored: <p:Animal>	<Critter>…</Critter>
allOf: [$ref Base] next to the schema's own properties	own properties spill into the parent	one element with both
Composed allOf / inline oneOf object property	its fields spill into the parent element	its own <prop> element
oneOf property with a scalar first variant	silently dropped	<code>string</code>
allOf: [$ref] or oneOf: [$ref] property with its own example/default	scalar dropped; object spills into the parent	its own element
allOf: [$ref] + skipReadOnly (Redoc request samples)	throws Cannot convert a Symbol value to a string	readOnly props skipped
allOf: [$ref User, { properties: { tenant_id: { readOnly: true } } }] + skipReadOnly (the PatchUser schema from #140)	throws Cannot convert a Symbol value to a string	<PatchUser><username>string</username></PatchUser>
Unwrapped nullable property array (type: ['array', 'null'])	<tags><tags>string</tags></tags>	<tags>string</tags>
Root scalar: 0 / "" / true / "a"	throws / throws / "" / <0>a</0>	<root>0</root> etc.

Why existing snapshots change

• Root element. In the OpenAPI 3.2.1 "XML Arrays" examples, a schema with xml: { name: document } and a single animals property serializes to <document>…</document>. The existing nodeType tests use those schemas. The sampler dropped that root whenever only one child element was left. Six snapshots are updated (the person, document ×4 and Item cases); their schemas are unchanged.
• Two document elements. Two snapshots ("array with defined parent and item names" and "undefined parent and defined item names without wrapper") produced <book>test1</book><book>test2</book>. That is two document elements, so it is not well-formed XML (XML 1.0, §2.1, production [1]). They are now wrapped in <root>.
• Example arrays. Three snapshots are the example-array cases. "Defined parent and undefined item names" rendered <0>test1</0>. The two "defined item name" wrapped cases ignored items.xml.name.

Using each spec example's dataValue as the property example, all six OAS 3.2.1 "XML Arrays" examples now produce exactly the spec's XML. On main, none of them do.

How

• convertJsonToXml:
  • A root schema with xml.name (and no nodeType other than element) names the document element, with its prefix and namespace.
  • Scalars and repeated elements are wrapped in root.
  • A root composed allOf without xml.name is named after its first $ref.
  • A root $ref is left alone, because traverse() already names it from the $ref and its siblings.
• Literal arrays (example, default, const, enum, examples), at the root, on properties and under an allOf:
  • Items are named by items.xml.name, else by the $ref's xml.name or component name.
  • Otherwise unwrapped arrays use the property name (the array's own xml.name is ignored), and wrapped arrays use the array's own name.
  • A $ref that can't be resolved under an example (missing, external, or no spec) is skipped rather than looked up.
  • A null or scalar value of an array property keeps its element.
• sampleArray: an unnamed scalar item takes the array's name (or root) instead of being spread into the result object, which is what split strings into characters. An unnamed composed allOf item is named after its first $ref.
• allOfSample:
  • The children of a composed allOf are traversed with flattenXmlRef, so object $ref children merge into one element. A $ref typed as an array keeps its own nodes.
  • allOf: [$ref] with only annotation siblings (isAnnotatedRef) is still named like a plain $ref.
  • stripSkipped removes skipped properties nested under a ref wrapper. It copies instead of writing, so frozen specs work and examples are never modified.
• resolveNodeType:
  • A composed allOf is an element, unless it is sampled as an array.
  • An allOf/oneOf/anyOf with its own value is an element.
  • Otherwise a oneOf/anyOf takes its node type from its first (sampled) variant.
  • type: ['array', 'null'] counts as an array. A schema without type: "array" keeps the element default, as the spec says.
• resolveRef (utils) is shared by traverse() and the XML naming, including the fix: apply keywords that are siblings of $ref #224 sibling merge.

Every behavioural change is behind format === 'xml'. JSON output is identical to main for 31,720 schema and option combinations, generated by two separate harnesses. They cover OpenAPI 3.0, 3.1 and 3.2, Swagger 2 and no version, with skipReadOnly, skipWriteOnly, skipNonRequired and maxSampleDepth.

Not changed (known limitations)

• A root object without xml.name and with a single (non-array) property still renders without a wrapper. XML Node Names says an inline media-type schema MUST have an xml.name.
• An unnamed scalar array nested directly in another array, or under additionalProperties, falls back to the element name root.
• A oneOf whose first variant is { type: 'null' } renders an empty element. The spec suggests xsi:nil="true".
• A root xml.prefix without a namespace produces an unbound prefix, as it already does for properties.
• Literal values are not mapped through per-property XML settings:
  • an object example's properties don't become attributes or text nodes;
  • prefixItems names aren't applied to example arrays;
  • arrays nested directly inside an example array aren't named;
  • an item schema whose own example is an array still renders <0> (an existing snapshot, unchanged).
• A sampled wrapped array with its own xml.name names unnamed items after the property, not the wrapper as the spec's last XML Arrays example does. This is unchanged from main; example arrays follow the spec.
• An array of $ref items with minItems > 1 still renders a single item, as on main.
• Objects with nodeType: 'text' or 'cdata' (not valid usage) are still not rendered correctly.
• An allOf that mixes an array or scalar with an object (not valid; the sampler already warns) still renders badly, sometimes worse than on main.
• A property $ref to an array component still gets an extra <root> element around its items, as on main.

Reference

• Found while porting Response example generation for XML and CSV redoc#2347 to Redoc v3. The Redoc side (CSV examples) is feat: render CSV request and response examples redoc#2869.
• Relates to readOnly and writeOnly are not honored when used in an allOf #140: the issue's PatchUser schema no longer throws when sampled as XML with skipReadOnly. JSON samples already honoured it.
• OpenAPI 3.2.1: XML Object (name, nodeType), XML Node Names, and the XML Arrays examples.

Testing

• npm test (oxlint + vitest): 236 tests pass, and npm run build is clean. The new XML tests are in test/xml.spec.js (68). The only changes to integration.spec.js are 11 updated snapshots. There are unit tests for stripSkipped, isArraySchema and isAnnotatedRef.
• Run against main, 68 of the 236 tests fail: 52 of the 68 XML tests, the 11 updated snapshots, and 5 unit tests for the new helpers.
• Every snapshot in test/xml.spec.js parses with xmllint.
• Fuzz: two generators, 34,000 XML cases in total (some deep-frozen), each compared with main.
  • No new throws.
  • No changes to input objects.
  • About 5,600 outputs went from malformed to well-formed.
  • The only outputs that went the other way are objects with nodeType: 'text'/'cdata', and allOfs mixing an array or scalar with an object (see the limitations).

Check yourself

• Code is linted
• Tested
• All new/updated code is covered with tests

Security

• Security impact of change has been considered
• Code follows company security practices and guidelines

🤖 Generated with Claude Code

https://claude.ai/code/session_01117LuacuBxMJUn1wJkfdyL

[makare11a]

Could we trim this to 2-3 lines? Changesets are copied word for word into CHANGELOG.md, and the detailed list already lives in the PR description and the tests

[rishitank]

Trimmed to two sentences, in the style of the 1.7.7/1.7.8 entries.

[makare11a]

The same comment already exists in utils.js:97. Additionally, some tests already describe this behavior so I'd dropt this comment

[rishitank]

Removed.

[makare11a]

This condition requires two-line comment before anyone can read it. Please consider creating an intermediate value:

  const isComposed = !!schema?.allOf && !isAnnotatedRef(schema);
  const xmlSource = isComposed && !schema.xml?.name ? firstRefXml(schema.allOf, spec) : schema;
  const { name, prefix, namespace } = getXMLAttributes(xmlSource);

[rishitank]

Done, with your intermediate values, and isComposedAllOf is now a small helper in utils because applyXMLAttributes needs it too.

One addition: a root $ref is excluded first (const rootSchema = schema?.$ref ? undefined : schema). After #224/#227, traverse() already names it from the $ref and its siblings, so naming it again doubled the element (e.g. the spec's StoredDocument example).

[makare11a]

The comment restates the condition, and the xml document root tests cover it

[rishitank]

Removed.

[makare11a]

prefix:name is now built in four places: here, samplers/array.js:34, utils.js:180, and for xmlns. Could prefixed move to utils.js and be reused?

[rishitank]

Moved to utils as prefixed(name, prefix), and used in convertJsonToXml, literalArrayToXml, sampleArray and applyXMLAttributes. The xmlns:prefix attribute is now built in one place, withNamespace.

[makare11a]

With a deep-frozen spec, sample(schema, { format: 'xml' }, spec) now throws Cannot assign to read only property 'tags'. With a normal spec, it silently replaces arrays inside the user’s examples. value[key] = stripSkipped(value[key]) also runs on plain example objects, because mergeDeep keeps references to them, and for arrays it assigns a new copy. Writing only when there’s something to delete should fix it

[rishitank]

Thanks, confirmed. It happened even without skipReadOnly, for any XML allOf whose example held an object with an array in it. stripSkipped now copies only the objects it removes something from and returns everything else as is, so it never writes to the spec. The tests sample a deep-frozen schema and spec without throwing, and check that the example's objects and arrays are untouched (xml spec objects in test/xml.spec.js, plus unit tests).

[makare11a]

The ternary says exactly this, and “should not wrap a composed allOf that is sampled as an array twice” test covers it, please consider dropping this comment

[rishitank]

Removed.

[makare11a]

// The first variant is the one that gets sampled, so it decides the node type would be enough

[rishitank]

Done, word for word.

[makare11a]

A literal array on a property still produces <0>a</0><1>b</1>, which isn’t well-formed XML. For example, { tags: { type: 'array', items: { type: 'string' }, example: ['a', 'b'] } } gives <Doc><0>a</0><1>b</1></Doc>, and default isn’t handled here at all

[rishitank]

Fixed for example and default, and for const, enum and examples too. An unwrapped literal array on a property now names its items by items.xml.name, else by the $ref's name, else by the property name. The array's own xml.name is ignored, as the name field says for nodeType none. A wrapped literal array names unnamed items after itself, as in the spec's last XML Arrays example. Your example now gives <Doc><tags>a</tags><tags>b</tags></Doc>.

The same applies to an example array reached through an allOf, e.g. allOf: [$ref Tags] next to xml (the 3.0 way to annotate a $ref). That rendered <root>a</root><root>b</root> on main, and <0>a</0> for an inline array.

This changes three existing snapshots in integration.spec.js; their schemas are unchanged. One was pinning <0>test1</0>. The other two were wrapped arrays that ignored items.xml.name (<booksLibrary><booksLibrary> instead of <booksLibrary><book>). I also used each example's dataValue as the property example for the six OAS 3.2.1 "XML Arrays" examples, and all six now produce exactly the spec's XML.

[makare11a]

This adds about 880 lines to a file that was already about 2,000 lines. Could the new describe blocks move to test/xml.spec.js or something like that?

[rishitank]

Moved. The six new describe blocks and the new tests are in test/xml.spec.js (68 tests). The only changes left in integration.spec.js are the 11 updated snapshots.

[makare11a]

Hello, @rishitank. Thanks, this will be a big improvement for XML samples. I suggested some improvements to your approach, please consider implementing them

[rishitank]

Thanks for such a careful review, @makare11a. The frozen-spec and property-example-array points were real bugs, and the rest made the code a lot clearer. I've merged main (#224–#228) into the branch and pushed the changes (c40b76b to 4c77b3b). There's a reply on each thread.

A few things beyond the threads, found while re-checking:

• A regression from the merge, now fixed. With fix: apply keywords that are siblings of $ref #224/fix(realm): ref sibling #227, a root $ref with an xml sibling (the spec's StoredDocument example) got its document element twice. Only traverse() names a root $ref now, so the output matches main, including OpenAPI 3.0 ignoring the sibling.
• Arrays without type: "array" are elements again. The spec gives nodeType a default of none only when type: "array" is present, so an untyped items schema is an element, rendered as main renders sampled ones. This PR had started treating it as an unwrapped array. type: ['array', 'null'] is still an array.
• Examples whose $ref can't be resolved. traverse() never resolves a $ref under an example or default, so it can be missing or external. Item and root naming now fall back to the property name or root there, instead of throwing.
• Two more data-loss fixes, which I'm happy to split out.
  • An allOf: [$ref] or oneOf: [$ref] property with its own example or default was dropped (a scalar) or spilled into its parent (an object), on main too.
  • The allOf items of a root array were merged into one element. They're now one element each, named after their first $ref.

Checks:

• npm test passes (236 tests).
• JSON output is identical to main for 31,720 schema and option combinations.
• Two fuzzers (34,000 generated XML cases, some deep-frozen) found no new throws and no changes to input objects.
• The only cases that went from well-formed to malformed are objects with nodeType: 'text' or 'cdata', and allOfs that mix an array or scalar with an object. Neither is valid usage (the sampler already warns about the second), and main doesn't render them correctly either.

I've also corrected the description, which overstated a couple of spec references.