Known Limitations

Non-inline primitive arrays require an explicit item tagname

For non-inline arrays of primitive types, the element schema must carry an explicit tagname via xml.root(schema, { tagname: "…" }), otherwise encoding throws "tagname is not defined". Model arrays are fine because the model's root tagname is resolved automatically from the ZodObject.

// ✅ works — explicit item tagname
models: z.array(xml.root(z.string(), { tagname: "model" }));

// ❌ throws at encode time — no tagname on item schema
names: z.array(z.string());

TypeDoc does not show inherited fields from .extend() subclasses

TypeDoc resolves the merged Zod schema of a subclass (produced by .extend()) back to the original field declarations in the parent schema. As a result, fields like vin, make, or year only appear on the parent class (Vehicle) in the API reference — they are not listed again under Car or SportCar, even though those classes carry them.

This is a TypeDoc limitation: it does not understand the Zod-specific inheritance pattern and cannot tell that the fields were intentionally re-exposed on the subclass. There is no TypeDoc option to force field re-listing for this case.

Workaround: document inherited fields in the parent class JSDoc comments, and note in the subclass description that it inherits fields from the parent (e.g. @see Vehicle).