From 5ec079037c13e50023a340154a0d7dc2760e5e04 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 14:43:53 -0400 Subject: [PATCH 01/10] cleanup --- .../libraries/xml/{guide.md => guide.mdx} | 461 +++++++----------- 1 file changed, 183 insertions(+), 278 deletions(-) rename website/src/content/docs/docs/libraries/xml/{guide.md => guide.mdx} (60%) diff --git a/website/src/content/docs/docs/libraries/xml/guide.md b/website/src/content/docs/docs/libraries/xml/guide.mdx similarity index 60% rename from website/src/content/docs/docs/libraries/xml/guide.md rename to website/src/content/docs/docs/libraries/xml/guide.mdx index 5c246f567db..37ca9e70f1f 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.md +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -2,9 +2,11 @@ title: Guide --- +import { Tabs, TabItem } from "@astrojs/starlight/components"; + ## Default encoding of scalars -As in Json we have some [default handling](https://typespec.io/docs/libraries/http/encoding#bytes) of the common scalars like `utcDateTime` +As in JSON, there is some [default handling](https://typespec.io/docs/libraries/http/encoding#bytes) of the common scalars like `utcDateTime`: | Scalar Type | Default Encoding | Encoding name | | ---------------- | ----------------- | --------------------------------------- | @@ -15,40 +17,31 @@ As in Json we have some [default handling](https://typespec.io/docs/libraries/ht | `duration` | `xs:duration` | `TypeSpec.Xml.Encoding.xmlDuration` | | `bytes` | `xs:base64Binary` | `TypeSpec.Xml.Encoding.xmlBase64Binary` | -## Examples +## 1. Array of primitive types -### 1. Array of primitive types +### 1.1 — Unwrapped primitive array - - - - - - - - - - - - + + + +### 1.2 — Wrapped primitive array with custom wrapper name - - - - - - + + + +### 1.3 — Unwrapped primitive array with custom item name - - - - - - + + + +### 1.4 — Wrapped primitive array with custom wrapper and item names - - - - - - - + + -
TypeSpecXmlOpenAPI3
+Each element is serialized using the property name as its XML element name. `@Xml.unwrapped` prevents wrapping in a container element. ```tsp -@encodedName("application/xml", "XmlPet") model Pet { @Xml.unwrapped tags: string[]; } ``` - + + ```xml - + abc def - + ``` - + + ```yaml Pet: @@ -60,39 +53,36 @@ Pet: type: string xml: name: tags - xml: - name: "XmlPet" ``` -
+Without `@Xml.unwrapped`, the array is wrapped in a container element. `@encodedName` on the property customizes the wrapper element name. ```tsp -@encodedName("application/xml", "XmlPet") model Pet { @encodedName("application/xml", "ItemsTags") tags: string[]; } ``` - + + ```xml - + abc def - + ``` - + + ```yaml Pet: @@ -107,40 +97,37 @@ Pet: type: string xml: name: string - xml: - name: "XmlPet" ``` -
+Using `@encodedName` on a named scalar controls the element name of each item. ```tsp @encodedName("application/xml", "ItemsName") scalar tag extends string; -@encodedName("application/xml", "XmlPet") model Pet { @Xml.unwrapped tags: tag[]; } ``` - + + ```xml - + abc def - + ``` - + + ```yaml Pet: @@ -152,42 +139,39 @@ Pet: type: string xml: name: tags - xml: - name: "XmlPet" ``` -
+Both the wrapper element and each item element have custom names via `@encodedName`. ```tsp @encodedName("application/xml", "ItemsName") scalar tag extends string; -@encodedName("application/xml", "XmlPet") model Pet { @encodedName("application/xml", "ItemsTags") tags: tag[]; } ``` - + + ```xml - + abc def - + ``` - + + ```yaml Pet: @@ -202,30 +186,18 @@ Pet: type: string xml: name: ItemsName - xml: - name: "XmlPet" ``` -
+## 2. Complex array types -### 2. Complex array types +### 2.1 — Unwrapped array of models - - - - - - - - - - - - + + - - - - - - + + + +### 2.3 — Unwrapped array of models with custom item name - - - - - - + + + +### 2.4 — Wrapped array of models with custom wrapper name - - - - - - - + + -
TypeSpecXmlOpenAPI3
+Each model item uses its model's XML name (`XmlTag`) when the array is unwrapped. ```tsp -@encodedName("application/xml", "XmlPet") model Pet { @Xml.unwrapped tags: Tag[]; @@ -237,19 +209,19 @@ model Tag { } ``` - + + ```xml - + string - + ``` - + + ```yaml Tag: @@ -269,19 +241,16 @@ Pet: - $ref: "#/definitions/Tag" xml: name: tags - xml: - name: "XmlPet" ``` -
+### 2.2 — Wrapped array of models (default) + +Without `@Xml.unwrapped`, the array is wrapped in a container element named after the property. ```tsp -@encodedName("application/xml", "XmlPet") model Pet { tags: Tag[]; } @@ -292,19 +261,21 @@ model Tag { } ``` - + + ```xml - - - string - - + + + + string + + + ``` - + + ```yaml Tag: @@ -326,19 +297,16 @@ Pet: name: XmlTag xml: wrapped: true - xml: - name: XmlPet ``` -
+Using `@encodedName` on the property overrides each item's element name, taking precedence over the model's XML name. ```tsp -@encodedName("application/xml", "XmlPet") model Pet { @encodedName("application/xml", "ItemsTag") @Xml.unwrapped @@ -351,19 +319,19 @@ model Tag { } ``` - + + ```xml - + string - + ``` - + + ```yaml Tag: @@ -383,19 +351,16 @@ Pet: - $ref: "#/definitions/Tag" xml: name: ItemsTag - xml: - name: "XmlPet" ``` -
+The wrapper element has a custom name via `@encodedName`; items use the model's XML name. ```tsp -@encodedName("application/xml", "XmlPet") model Pet { @encodedName("application/xml", "ItemsTags") tags: Tag[]; @@ -407,21 +372,21 @@ model Tag { } ``` - + + ```xml - + string - + ``` - + + ```yaml Tag: @@ -444,28 +409,16 @@ Pet: - $ref: "#/definitions/Tag" xml: name: XmlTag - xml: - name: "XmlPet" ``` -
+## 3. Nested models -### 3. Nested models +### 3.1 — Basic nested model - - - - - - - - - - - - - + + - - - - - - + + + +### 3.3 — Nested model with custom XML name on the property - - - - - - + + - +## 4. Attributes -
TypeSpecXmlOpenAPI3
+A property referencing another model is serialized as a nested XML element using the property name. ```tsp model Book { @@ -477,8 +430,8 @@ model Author { } ``` - + + ```xml @@ -488,8 +441,8 @@ model Author { ``` - + + ```yaml Book: @@ -504,12 +457,12 @@ Author: type: string ``` -
+### 3.2 — Nested model with custom XML name on the model + +When the referenced model has `@encodedName`, the property name still takes precedence for the XML element name. ```tsp model Book { @@ -522,8 +475,8 @@ model Author { } ``` - + + ```xml @@ -533,8 +486,8 @@ model Author { ``` - + + ```yaml Book: @@ -554,12 +507,12 @@ Author: name: "XmlAuthor" ``` -
+Using `@encodedName` on the property overrides the element name for the nested model. ```tsp model Book { @@ -572,8 +525,8 @@ model Author { } ``` - + + ```xml @@ -583,8 +536,8 @@ model Author { ``` - + + ```yaml Book: @@ -602,25 +555,14 @@ Author: type: string ``` -
+### 4.1 — XML attributes and element name override -### 4. Attributes - - - - - - - - - - - - - - - - + + -
TypeSpecXmlOpenAPI3
+`@Xml.attribute` serializes a property as an XML attribute instead of a child element. `@Xml.name` overrides the XML element name. ```tsp model Book { @@ -634,8 +576,8 @@ model Book { } ``` - + + ```xml @@ -644,8 +586,8 @@ model Book { ``` - + + ```yaml Book: @@ -663,25 +605,14 @@ Book: type: string ``` -
+## 5. Namespace and prefix (inline form) -### 5. Namespace and prefix (inline form) +### 5.1 — Namespace on the model - - - - - - - - - - - - - + + - - - - - - + + - +## 6. Namespace and prefix (normalized form) -
TypeSpecXmlOpenAPI3
+`@Xml.ns` on a model adds a namespace prefix and declaration to the root element. ```tsp @Xml.ns("http://example.com/schema", "smp") @@ -692,8 +623,8 @@ model Book { } ``` - + + ```xml @@ -703,8 +634,8 @@ model Book { ``` - + + ```yaml Book: @@ -721,12 +652,12 @@ Book: namespace: "http://example.com/schema" ``` -
+### 5.2 — Namespace on individual properties + +Properties can declare their own namespace with `@Xml.ns`, which may differ from the model's namespace. ```tsp @Xml.ns("http://example.com/schema", "smp") @@ -741,19 +672,19 @@ model Book { } ``` - + + ```xml - + 0 string string ``` - + + ```yaml Book: @@ -763,7 +694,7 @@ Book: type: integer title: type: string - xml: + xml: prefix: "smp" namespace: "http://example.com/schema" author: @@ -776,25 +707,14 @@ Book: namespace: "http://example.com/schema" ``` -
+### 6.1 — Using an `@Xml.nsDeclarations` enum -### 6. Namespace and prefix (normalized form) - - - - - - - - - - - - - - + + + +### 6.2 — Multiple namespaces via enum - - - - - - - - + + -
TypeSpecXmlOpenAPI3
+Declare namespaces in an enum to avoid repeating URIs. Reference enum members with `@Xml.ns`. ```tsp @Xml.nsDeclarations @@ -810,8 +730,8 @@ model Book { } ``` - + + ```xml @@ -821,8 +741,8 @@ model Book { ``` - + + ```yaml Book: @@ -843,12 +763,12 @@ Namespaces: - http://example.com/schema ``` -
+Multiple namespace declarations can be defined in a single enum and referenced on individual properties. ```tsp @Xml.nsDeclarations @@ -869,19 +789,19 @@ model Book { } ``` - + + ```xml - + 0 string string ``` - + + ```yaml Book: @@ -891,7 +811,7 @@ Book: type: integer title: type: string - xml: + xml: prefix: "smp" namespace: "http://example.com/schema" author: @@ -909,25 +829,14 @@ Namespaces: - http://example.com/ns2 ``` -
+## 7. Property setting the text of the node -### 6. Property setting the text of the node +### 7.1 — Text content with attributes - - - - - - - - - - - - - - - - -
TypeSpecXmlOpenAPI3
+`@Xml.unwrapped` on a scalar property makes it the text content of the parent element. Combined with `@Xml.attribute`, you can model elements that have both attributes and inline text. ```tsp model BlobName { @@ -936,20 +845,20 @@ model BlobName { } ``` - + + ```xml ...content... - + ``` - + + ```yaml -Book: +BlobName: type: object properties: language: @@ -960,9 +869,5 @@ Book: type: string ``` -
+ + From e382ce1f9096e8d55d80861f95838eb11227912d Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 14:54:50 -0400 Subject: [PATCH 02/10] add basic property example --- .../content/docs/docs/libraries/xml/guide.mdx | 219 ++++++++++++++++-- 1 file changed, 195 insertions(+), 24 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 37ca9e70f1f..5e9e868ffdf 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -17,9 +17,180 @@ As in JSON, there is some [default handling](https://typespec.io/docs/libraries/ | `duration` | `xs:duration` | `TypeSpec.Xml.Encoding.xmlDuration` | | `bytes` | `xs:base64Binary` | `TypeSpec.Xml.Encoding.xmlBase64Binary` | -## 1. Array of primitive types +## 1. Basic properties -### 1.1 — Unwrapped primitive array +### 1.1 — Simple model with scalar properties + +Properties of scalar types are serialized as child XML elements by default. + +```tsp +model Book { + id: integer; + title: string; + author: string; +} +``` + + + + +```xml + + 0 + string + string + +``` + + + + +```yaml +Book: + type: object + properties: + id: + type: integer + title: + type: string + author: + type: string +``` + + + + +### 1.2 — Renaming a property for XML + +`@encodedName("application/xml", ...)` or `@Xml.name(...)` changes how a property name appears in the XML output without affecting the TypeSpec model name. + + + + +```tsp +model Book { + id: integer; + + @Xml.name("book-title") + title: string; + + author: string; +} +``` + + + + +```tsp +model Book { + id: integer; + + @encodedName("application/xml", "book-title") + title: string; + + author: string; +} +``` + + + + + + + +```xml + + 0 + string + string + +``` + + + + +```yaml +Book: + type: object + properties: + id: + type: integer + title: + type: string + xml: + name: "book-title" + author: + type: string +``` + + + + +### 1.3 — Renaming the model for XML + +`@encodedName("application/xml", ...)` or `@Xml.name(...)` on a model changes the root element name in the XML output. + + + + +```tsp +@Xml.name("XmlBook") +model Book { + id: integer; + title: string; + author: string; +} +``` + + + + +```tsp +@encodedName("application/xml", "XmlBook") +model Book { + id: integer; + title: string; + author: string; +} +``` + + + + + + + +```xml + + 0 + string + string + +``` + + + + +```yaml +Book: + type: object + properties: + id: + type: integer + title: + type: string + author: + type: string + xml: + name: "XmlBook" +``` + + + + +## 2. Array of primitive types + +### 2.1 — Unwrapped primitive array Each element is serialized using the property name as its XML element name. `@Xml.unwrapped` prevents wrapping in a container element. @@ -58,7 +229,7 @@ Pet: -### 1.2 — Wrapped primitive array with custom wrapper name +### 2.2 — Wrapped primitive array with custom wrapper name Without `@Xml.unwrapped`, the array is wrapped in a container element. `@encodedName` on the property customizes the wrapper element name. @@ -102,7 +273,7 @@ Pet: -### 1.3 — Unwrapped primitive array with custom item name +### 2.3 — Unwrapped primitive array with custom item name Using `@encodedName` on a named scalar controls the element name of each item. @@ -144,7 +315,7 @@ Pet: -### 1.4 — Wrapped primitive array with custom wrapper and item names +### 2.4 — Wrapped primitive array with custom wrapper and item names Both the wrapper element and each item element have custom names via `@encodedName`. @@ -191,9 +362,9 @@ Pet: -## 2. Complex array types +## 3. Complex array types -### 2.1 — Unwrapped array of models +### 3.1 — Unwrapped array of models Each model item uses its model's XML name (`XmlTag`) when the array is unwrapped. @@ -246,7 +417,7 @@ Pet: -### 2.2 — Wrapped array of models (default) +### 3.2 — Wrapped array of models (default) Without `@Xml.unwrapped`, the array is wrapped in a container element named after the property. @@ -302,7 +473,7 @@ Pet: -### 2.3 — Unwrapped array of models with custom item name +### 3.3 — Unwrapped array of models with custom item name Using `@encodedName` on the property overrides each item's element name, taking precedence over the model's XML name. @@ -356,7 +527,7 @@ Pet: -### 2.4 — Wrapped array of models with custom wrapper name +### 3.4 — Wrapped array of models with custom wrapper name The wrapper element has a custom name via `@encodedName`; items use the model's XML name. @@ -414,9 +585,9 @@ Pet: -## 3. Nested models +## 4. Nested models -### 3.1 — Basic nested model +### 4.1 — Basic nested model A property referencing another model is serialized as a nested XML element using the property name. @@ -460,7 +631,7 @@ Author: -### 3.2 — Nested model with custom XML name on the model +### 4.2 — Nested model with custom XML name on the model When the referenced model has `@encodedName`, the property name still takes precedence for the XML element name. @@ -510,7 +681,7 @@ Author: -### 3.3 — Nested model with custom XML name on the property +### 4.3 — Nested model with custom XML name on the property Using `@encodedName` on the property overrides the element name for the nested model. @@ -558,9 +729,9 @@ Author: -## 4. Attributes +## 5. Attributes -### 4.1 — XML attributes and element name override +### 5.1 — XML attributes and element name override `@Xml.attribute` serializes a property as an XML attribute instead of a child element. `@Xml.name` overrides the XML element name. @@ -608,9 +779,9 @@ Book: -## 5. Namespace and prefix (inline form) +## 6. Namespace and prefix (inline form) -### 5.1 — Namespace on the model +### 6.1 — Namespace on the model `@Xml.ns` on a model adds a namespace prefix and declaration to the root element. @@ -655,7 +826,7 @@ Book: -### 5.2 — Namespace on individual properties +### 6.2 — Namespace on individual properties Properties can declare their own namespace with `@Xml.ns`, which may differ from the model's namespace. @@ -710,9 +881,9 @@ Book: -## 6. Namespace and prefix (normalized form) +## 7. Namespace and prefix (normalized form) -### 6.1 — Using an `@Xml.nsDeclarations` enum +### 7.1 — Using an `@Xml.nsDeclarations` enum Declare namespaces in an enum to avoid repeating URIs. Reference enum members with `@Xml.ns`. @@ -766,7 +937,7 @@ Namespaces: -### 6.2 — Multiple namespaces via enum +### 7.2 — Multiple namespaces via enum Multiple namespace declarations can be defined in a single enum and referenced on individual properties. @@ -832,9 +1003,9 @@ Namespaces: -## 7. Property setting the text of the node +## 8. Property setting the text of the node -### 7.1 — Text content with attributes +### 8.1 — Text content with attributes `@Xml.unwrapped` on a scalar property makes it the text content of the parent element. Combined with `@Xml.attribute`, you can model elements that have both attributes and inline text. From 07712839c1568589b2abf2579f1cf214f5038741 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 15:34:39 -0400 Subject: [PATCH 03/10] good 2. --- .../content/docs/docs/libraries/xml/guide.mdx | 460 +++++++++++++----- 1 file changed, 338 insertions(+), 122 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 5e9e868ffdf..f1d636e08dd 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -17,9 +17,9 @@ As in JSON, there is some [default handling](https://typespec.io/docs/libraries/ | `duration` | `xs:duration` | `TypeSpec.Xml.Encoding.xmlDuration` | | `bytes` | `xs:base64Binary` | `TypeSpec.Xml.Encoding.xmlBase64Binary` | -## 1. Basic properties +## 1. Primitive properties -### 1.1 — Simple model with scalar properties +### 1.1 — Default serialization Properties of scalar types are serialized as child XML elements by default. @@ -60,7 +60,7 @@ Book: -### 1.2 — Renaming a property for XML +### 1.2 — Renaming a property `@encodedName("application/xml", ...)` or `@Xml.name(...)` changes how a property name appears in the XML output without affecting the TypeSpec model name. @@ -126,7 +126,7 @@ Book: -### 1.3 — Renaming the model for XML +### 1.3 — Renaming the model `@encodedName("application/xml", ...)` or `@Xml.name(...)` on a model changes the root element name in the XML output. @@ -190,12 +190,54 @@ Book: ## 2. Array of primitive types -### 2.1 — Unwrapped primitive array +### 2.1 — Wrapped primitive array (default) -Each element is serialized using the property name as its XML element name. `@Xml.unwrapped` prevents wrapping in a container element. +By default, an array property is wrapped in a container element named after the property. Each item uses the scalar type name as its element name. ```tsp -model Pet { +model Book { + tags: string[]; +} +``` + + + + +```xml + + + abc + def + + +``` + + + + +```yaml +Book: + type: "object" + properties: + tags: + type: "array" + xml: + wrapped: true + items: + type: string + xml: + name: string +``` + + + + +### 2.2 — Unwrapped primitive array + +`@Xml.unwrapped` removes the wrapper element. Each item is serialized using the property name as its XML element name. + +```tsp +model Book { @Xml.unwrapped tags: string[]; } @@ -205,17 +247,17 @@ model Pet { ```xml - + abc def - + ``` ```yaml -Pet: +Book: type: "object" properties: tags: @@ -229,34 +271,50 @@ Pet: -### 2.2 — Wrapped primitive array with custom wrapper name +### 2.3 — Wrapped primitive array with custom wrapper name -Without `@Xml.unwrapped`, the array is wrapped in a container element. `@encodedName` on the property customizes the wrapper element name. +Without `@Xml.unwrapped`, the array is wrapped in a container element. `@Xml.name` or `@encodedName` on the property customizes the wrapper element name. + + + ```tsp -model Pet { +model Book { + @Xml.name("ItemsTags") + tags: string[]; +} +``` + + + + +```tsp +model Book { @encodedName("application/xml", "ItemsTags") tags: string[]; } ``` + + + ```xml - + abc def - + ``` ```yaml -Pet: +Book: type: "object" properties: tags: @@ -273,35 +331,50 @@ Pet: -### 2.3 — Unwrapped primitive array with custom item name +### 2.4 — Unwrapped primitive array with custom item name + +`@Xml.name` or `@encodedName` on the property controls the element name of each item when the array is unwrapped. -Using `@encodedName` on a named scalar controls the element name of each item. + + ```tsp -@encodedName("application/xml", "ItemsName") -scalar tag extends string; +model Book { + @Xml.name("tag") + @Xml.unwrapped + tags: string[]; +} +``` + + + -model Pet { +```tsp +model Book { + @encodedName("application/xml", "tag") @Xml.unwrapped - tags: tag[]; + tags: string[]; } ``` + + + ```xml - - abc - def - + + abc + def + ``` ```yaml -Pet: +Book: type: "object" properties: tags: @@ -309,43 +382,62 @@ Pet: items: type: string xml: - name: tags + name: tag ``` -### 2.4 — Wrapped primitive array with custom wrapper and item names +### 2.5 — Wrapped primitive array with custom wrapper and item names + +Both the wrapper element and each item element have custom names via `@Xml.name` or `@encodedName`. + + + + +```tsp +@Xml.name("ItemName") +scalar tag extends string; + +model Book { + @Xml.name("ItemsTags") + tags: tag[]; +} +``` -Both the wrapper element and each item element have custom names via `@encodedName`. + + ```tsp -@encodedName("application/xml", "ItemsName") +@encodedName("application/xml", "ItemName") scalar tag extends string; -model Pet { +model Book { @encodedName("application/xml", "ItemsTags") tags: tag[]; } ``` + + + ```xml - + - abc - def + abc + def - + ``` ```yaml -Pet: +Book: type: "object" properties: tags: @@ -356,7 +448,7 @@ Pet: items: type: string xml: - name: ItemsName + name: ItemName ``` @@ -366,52 +458,73 @@ Pet: ### 3.1 — Unwrapped array of models -Each model item uses its model's XML name (`XmlTag`) when the array is unwrapped. +Each model item uses its model's XML name (`XmlBook`) when the array is unwrapped. + + + ```tsp -model Pet { +model Store { @Xml.unwrapped - tags: Tag[]; + books: Book[]; } -@encodedName("application/xml", "XmlTag") -model Tag { - name: string; +@Xml.name("XmlBook") +model Book { + title: string; } ``` + + + +```tsp +model Store { + @Xml.unwrapped + books: Book[]; +} + +@encodedName("application/xml", "XmlBook") +model Book { + title: string; +} +``` + + + + ```xml - - - string - - + + + string + + ``` ```yaml -Tag: +Book: type: "object" properties: - name: + title: type: "string" xml: - name: "XmlTag" -Pet: + name: "XmlBook" +Store: type: "object" properties: - tags: + books: type: "array" items: allOf: - - $ref: "#/definitions/Tag" + - $ref: "#/definitions/Book" xml: - name: tags + name: books ``` @@ -421,51 +534,71 @@ Pet: Without `@Xml.unwrapped`, the array is wrapped in a container element named after the property. + + + ```tsp -model Pet { - tags: Tag[]; +model Store { + books: Book[]; } -@encodedName("application/xml", "XmlTag") -model Tag { - name: string; +@Xml.name("XmlBook") +model Book { + title: string; } ``` + + + +```tsp +model Store { + books: Book[]; +} + +@encodedName("application/xml", "XmlBook") +model Book { + title: string; +} +``` + + + + ```xml - - - - string - - - + + + + string + + + ``` ```yaml -Tag: +Book: type: "object" properties: - name: + title: type: "string" xml: - name: "XmlTag" -Pet: + name: "XmlBook" +Store: type: object properties: - tags: + books: type: array items: allOf: - - $ref: "#/components/schemas/Tag" + - $ref: "#/components/schemas/Book" xml: - name: XmlTag + name: XmlBook xml: wrapped: true ``` @@ -475,53 +608,75 @@ Pet: ### 3.3 — Unwrapped array of models with custom item name -Using `@encodedName` on the property overrides each item's element name, taking precedence over the model's XML name. +Using `@Xml.name` or `@encodedName` on the property overrides each item's element name, taking precedence over the model's XML name. + + + ```tsp -model Pet { - @encodedName("application/xml", "ItemsTag") +model Store { + @Xml.name("ItemBook") @Xml.unwrapped - tags: Tag[]; + books: Book[]; } -@encodedName("application/xml", "XmlTag") -model Tag { - name: string; +@Xml.name("XmlBook") +model Book { + title: string; } ``` + + + +```tsp +model Store { + @encodedName("application/xml", "ItemBook") + @Xml.unwrapped + books: Book[]; +} + +@encodedName("application/xml", "XmlBook") +model Book { + title: string; +} +``` + + + + ```xml - - - string - - + + + string + + ``` ```yaml -Tag: +Book: type: "object" properties: - name: + title: type: "string" xml: - name: "XmlTag" -Pet: + name: "XmlBook" +Store: type: "object" properties: - tags: + books: type: "array" items: allOf: - - $ref: "#/definitions/Tag" + - $ref: "#/definitions/Book" xml: - name: ItemsTag + name: ItemBook ``` @@ -529,57 +684,78 @@ Pet: ### 3.4 — Wrapped array of models with custom wrapper name -The wrapper element has a custom name via `@encodedName`; items use the model's XML name. +The wrapper element has a custom name via `@Xml.name` or `@encodedName`; items use the model's XML name. + + + + +```tsp +model Store { + @Xml.name("ItemsBooks") + books: Book[]; +} + +@Xml.name("XmlBook") +model Book { + title: string; +} +``` + + + ```tsp -model Pet { - @encodedName("application/xml", "ItemsTags") - tags: Tag[]; +model Store { + @encodedName("application/xml", "ItemsBooks") + books: Book[]; } -@encodedName("application/xml", "XmlTag") -model Tag { - name: string; +@encodedName("application/xml", "XmlBook") +model Book { + title: string; } ``` + + + ```xml - - - - string - - - + + + + string + + + ``` ```yaml -Tag: +Book: type: "object" properties: - name: + title: type: "string" xml: - name: "XmlTag" -Pet: + name: "XmlBook" +Store: type: "object" properties: - tags: + books: type: "array" xml: - name: "ItemsTags" + name: "ItemsBooks" wrapped: true items: allOf: - - $ref: "#/definitions/Tag" + - $ref: "#/definitions/Book" xml: - name: XmlTag + name: XmlBook ``` @@ -633,7 +809,24 @@ Author: ### 4.2 — Nested model with custom XML name on the model -When the referenced model has `@encodedName`, the property name still takes precedence for the XML element name. +When the referenced model has `@Xml.name` or `@encodedName`, the property name still takes precedence for the XML element name. + + + + +```tsp +model Book { + author: Author; +} + +@Xml.name("XmlAuthor") +model Author { + name: string; +} +``` + + + ```tsp model Book { @@ -646,6 +839,9 @@ model Author { } ``` + + + @@ -683,7 +879,24 @@ Author: ### 4.3 — Nested model with custom XML name on the property -Using `@encodedName` on the property overrides the element name for the nested model. +Using `@Xml.name` or `@encodedName` on the property overrides the element name for the nested model. + + + + +```tsp +model Book { + @Xml.name("xml-author") + author: Author; +} + +model Author { + name: string; +} +``` + + + ```tsp model Book { @@ -696,6 +909,9 @@ model Author { } ``` + + + @@ -1010,7 +1226,7 @@ Namespaces: `@Xml.unwrapped` on a scalar property makes it the text content of the parent element. Combined with `@Xml.attribute`, you can model elements that have both attributes and inline text. ```tsp -model BlobName { +model BookTitle { @Xml.attribute language: string; @Xml.unwrapped content: string; } @@ -1020,16 +1236,16 @@ model BlobName { ```xml - + ...content... - + ``` ```yaml -BlobName: +BookTitle: type: object properties: language: From 2e6a2b74f4c8fd78762e5e2b74b56c4addea6638 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 16:16:54 -0400 Subject: [PATCH 04/10] section 3. --- .../content/docs/docs/libraries/xml/guide.mdx | 224 ++++++++++-------- 1 file changed, 127 insertions(+), 97 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index f1d636e08dd..0261afdd508 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -37,8 +37,8 @@ model Book { ```xml 0 - string - string + The Great Gatsby + F. Scott Fitzgerald ``` @@ -101,8 +101,8 @@ model Book { ```xml 0 - string - string + The Great Gatsby + F. Scott Fitzgerald ``` @@ -163,8 +163,8 @@ model Book { ```xml 0 - string - string + Les Miserables + Victor Hugo ``` @@ -206,8 +206,8 @@ model Book { ```xml - abc - def + fiction + classic ``` @@ -248,8 +248,8 @@ model Book { ```xml - abc - def + fiction + classic ``` @@ -304,8 +304,8 @@ model Book { ```xml - abc - def + fiction + classic ``` @@ -365,8 +365,8 @@ model Book { ```xml - abc - def + fiction + classic ``` @@ -427,8 +427,8 @@ model Book { ```xml - abc - def + fiction + classic ``` @@ -454,29 +454,64 @@ Book: -## 3. Complex array types +## 3. Array of complex types -### 3.1 — Unwrapped array of models +### 3.1 — Wrapped array of models (default) -Each model item uses its model's XML name (`XmlBook`) when the array is unwrapped. - - - +By default, an array of models is wrapped in a container element named after the property. Each item uses the model name as its element name. ```tsp model Store { - @Xml.unwrapped books: Book[]; } -@Xml.name("XmlBook") model Book { title: string; } ``` + + + +```xml + + + + The Great Gatsby + + + Les Miserables + + + +``` + - + + +```yaml +Book: + type: "object" + properties: + title: + type: "string" +Store: + type: "object" + properties: + books: + type: "array" + items: + $ref: "#/components/schemas/Book" + xml: + wrapped: true +``` + + + + +### 3.2 — Unwrapped array of models + +`@Xml.unwrapped` removes the wrapper element. Each item uses the property name as its element name. ```tsp model Store { @@ -484,23 +519,22 @@ model Store { books: Book[]; } -@encodedName("application/xml", "XmlBook") model Book { title: string; } ``` - - - ```xml - - string - + + The Great Gatsby + + + Les Miserables + ``` @@ -513,36 +547,31 @@ Book: properties: title: type: "string" - xml: - name: "XmlBook" Store: type: "object" properties: books: type: "array" items: - allOf: - - $ref: "#/definitions/Book" - xml: - name: books + $ref: "#/components/schemas/Book" ``` -### 3.2 — Wrapped array of models (default) +### 3.3 — Wrapped array of models with custom wrapper name -Without `@Xml.unwrapped`, the array is wrapped in a container element named after the property. +`@Xml.name` or `@encodedName` on the property customizes the wrapper element name. ```tsp model Store { + @Xml.name("AllBooks") books: Book[]; } -@Xml.name("XmlBook") model Book { title: string; } @@ -553,10 +582,10 @@ model Book { ```tsp model Store { + @encodedName("application/xml", "AllBooks") books: Book[]; } -@encodedName("application/xml", "XmlBook") model Book { title: string; } @@ -570,11 +599,14 @@ model Book { ```xml - - - string - - + + + The Great Gatsby + + + Les Miserables + + ``` @@ -587,40 +619,35 @@ Book: properties: title: type: "string" - xml: - name: "XmlBook" Store: - type: object + type: "object" properties: books: - type: array - items: - allOf: - - $ref: "#/components/schemas/Book" - xml: - name: XmlBook + type: "array" xml: + name: "AllBooks" wrapped: true + items: + $ref: "#/components/schemas/Book" ``` -### 3.3 — Unwrapped array of models with custom item name +### 3.4 — Unwrapped array of models with custom item name -Using `@Xml.name` or `@encodedName` on the property overrides each item's element name, taking precedence over the model's XML name. +`@Xml.name` or `@encodedName` on the property overrides each item's element name when the array is unwrapped. ```tsp model Store { - @Xml.name("ItemBook") + @Xml.name("BookItem") @Xml.unwrapped books: Book[]; } -@Xml.name("XmlBook") model Book { title: string; } @@ -631,12 +658,11 @@ model Book { ```tsp model Store { - @encodedName("application/xml", "ItemBook") + @encodedName("application/xml", "BookItem") @Xml.unwrapped books: Book[]; } -@encodedName("application/xml", "XmlBook") model Book { title: string; } @@ -650,9 +676,12 @@ model Book { ```xml - - string - + + The Great Gatsby + + + Les Miserables + ``` @@ -665,8 +694,6 @@ Book: properties: title: type: "string" - xml: - name: "XmlBook" Store: type: "object" properties: @@ -674,28 +701,28 @@ Store: type: "array" items: allOf: - - $ref: "#/definitions/Book" + - $ref: "#/components/schemas/Book" xml: - name: ItemBook + name: BookItem ``` -### 3.4 — Wrapped array of models with custom wrapper name +### 3.5 — Wrapped array of models with custom wrapper and item names -The wrapper element has a custom name via `@Xml.name` or `@encodedName`; items use the model's XML name. +Both the wrapper element and each item element have custom names. ```tsp model Store { - @Xml.name("ItemsBooks") + @Xml.name("AllBooks") books: Book[]; } -@Xml.name("XmlBook") +@Xml.name("BookItem") model Book { title: string; } @@ -706,11 +733,11 @@ model Book { ```tsp model Store { - @encodedName("application/xml", "ItemsBooks") + @encodedName("application/xml", "AllBooks") books: Book[]; } -@encodedName("application/xml", "XmlBook") +@encodedName("application/xml", "BookItem") model Book { title: string; } @@ -724,11 +751,14 @@ model Book { ```xml - - - string - - + + + The Great Gatsby + + + Les Miserables + + ``` @@ -742,20 +772,20 @@ Book: title: type: "string" xml: - name: "XmlBook" + name: "BookItem" Store: type: "object" properties: books: type: "array" xml: - name: "ItemsBooks" + name: "AllBooks" wrapped: true items: allOf: - - $ref: "#/definitions/Book" + - $ref: "#/components/schemas/Book" xml: - name: XmlBook + name: BookItem ``` @@ -783,7 +813,7 @@ model Author { ```xml - string + F. Scott Fitzgerald ``` @@ -848,7 +878,7 @@ model Author { ```xml - string + F. Scott Fitzgerald ``` @@ -918,7 +948,7 @@ model Author { ```xml - string + F. Scott Fitzgerald ``` @@ -968,8 +998,8 @@ model Book { ```xml - string - string + The Great Gatsby + F. Scott Fitzgerald ``` @@ -1016,8 +1046,8 @@ model Book { ```xml 0 - string - string + The Great Gatsby + F. Scott Fitzgerald ``` @@ -1065,8 +1095,8 @@ model Book { ```xml 0 - string - string + The Great Gatsby + F. Scott Fitzgerald ``` @@ -1123,8 +1153,8 @@ model Book { ```xml 0 - string - string + Les Miserables + Victor Hugo ``` @@ -1182,8 +1212,8 @@ model Book { ```xml 0 - string - string + Les Miserables + Victor Hugo ``` From b710eeaac257c2781cbfc0e679c8c9a2d6f4dcd0 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 16:39:47 -0400 Subject: [PATCH 05/10] reorder --- .../content/docs/docs/libraries/xml/guide.mdx | 391 +++++++++--------- 1 file changed, 196 insertions(+), 195 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 0261afdd508..575b6a05420 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -188,9 +188,193 @@ Book: -## 2. Array of primitive types +## 2. Nested models -### 2.1 — Wrapped primitive array (default) +### 4.1 — Basic nested model + +A property referencing another model is serialized as a nested XML element using the property name. + +```tsp +model Book { + author: Author; +} + +model Author { + name: string; +} +``` + + + + +```xml + + + F. Scott Fitzgerald + + +``` + + + + +```yaml +Book: + type: object + properties: + author: + $ref: "#/components/schemas/Author" +Author: + type: object + properties: + name: + type: string +``` + + + + +### 4.2 — Nested model with custom XML name on the model + +When the referenced model has `@Xml.name` or `@encodedName`, the property name still takes precedence for the XML element name. + + + + +```tsp +model Book { + author: Author; +} + +@Xml.name("XmlAuthor") +model Author { + name: string; +} +``` + + + + +```tsp +model Book { + author: Author; +} + +@encodedName("application/xml", "XmlAuthor") +model Author { + name: string; +} +``` + + + + + + + +```xml + + + F. Scott Fitzgerald + + +``` + + + + +```yaml +Book: + type: object + properties: + author: + allOf: + - $ref: "#/components/schemas/Author" + xml: + name: "author" # Here we have to redefine this name otherwise in OpenAPI semantic the `XmlAuthor` name would be used +Author: + type: object + properties: + name: + type: string + xml: + name: "XmlAuthor" +``` + + + + +### 4.3 — Nested model with custom XML name on the property + +Using `@Xml.name` or `@encodedName` on the property overrides the element name for the nested model. + + + + +```tsp +model Book { + @Xml.name("xml-author") + author: Author; +} + +model Author { + name: string; +} +``` + + + + +```tsp +model Book { + @encodedName("application/xml", "xml-author") + author: Author; +} + +model Author { + name: string; +} +``` + + + + + + + +```xml + + + F. Scott Fitzgerald + + +``` + + + + +```yaml +Book: + type: object + properties: + author: + allOf: + - $ref: "#/components/schemas/Author" + xml: + name: "xml-author" +Author: + type: object + properties: + name: + type: string +``` + + + + +## 3. Array of primitive types + +### 4.1 — Wrapped primitive array (default) By default, an array property is wrapped in a container element named after the property. Each item uses the scalar type name as its element name. @@ -232,7 +416,7 @@ Book: -### 2.2 — Unwrapped primitive array +### 4.2 — Unwrapped primitive array `@Xml.unwrapped` removes the wrapper element. Each item is serialized using the property name as its XML element name. @@ -271,7 +455,7 @@ Book: -### 2.3 — Wrapped primitive array with custom wrapper name +### 4.3 — Wrapped primitive array with custom wrapper name Without `@Xml.unwrapped`, the array is wrapped in a container element. `@Xml.name` or `@encodedName` on the property customizes the wrapper element name. @@ -331,7 +515,7 @@ Book: -### 2.4 — Unwrapped primitive array with custom item name +### 4.4 — Unwrapped primitive array with custom item name `@Xml.name` or `@encodedName` on the property controls the element name of each item when the array is unwrapped. @@ -388,7 +572,7 @@ Book: -### 2.5 — Wrapped primitive array with custom wrapper and item names +### 4.5 — Wrapped primitive array with custom wrapper and item names Both the wrapper element and each item element have custom names via `@Xml.name` or `@encodedName`. @@ -454,9 +638,9 @@ Book: -## 3. Array of complex types +## 4. Array of complex types -### 3.1 — Wrapped array of models (default) +### 4.1 — Wrapped array of models (default) By default, an array of models is wrapped in a container element named after the property. Each item uses the model name as its element name. @@ -509,7 +693,7 @@ Store: -### 3.2 — Unwrapped array of models +### 4.2 — Unwrapped array of models `@Xml.unwrapped` removes the wrapper element. Each item uses the property name as its element name. @@ -559,7 +743,7 @@ Store: -### 3.3 — Wrapped array of models with custom wrapper name +### 4.3 — Wrapped array of models with custom wrapper name `@Xml.name` or `@encodedName` on the property customizes the wrapper element name. @@ -634,7 +818,7 @@ Store: -### 3.4 — Unwrapped array of models with custom item name +### 4.4 — Unwrapped array of models with custom item name `@Xml.name` or `@encodedName` on the property overrides each item's element name when the array is unwrapped. @@ -709,7 +893,7 @@ Store: -### 3.5 — Wrapped array of models with custom wrapper and item names +### 4.5 — Wrapped array of models with custom wrapper and item names Both the wrapper element and each item element have custom names. @@ -791,189 +975,6 @@ Store: -## 4. Nested models - -### 4.1 — Basic nested model - -A property referencing another model is serialized as a nested XML element using the property name. - -```tsp -model Book { - author: Author; -} - -model Author { - name: string; -} -``` - - - - -```xml - - - F. Scott Fitzgerald - - -``` - - - - -```yaml -Book: - type: object - properties: - author: - $ref: "#/components/schemas/Author" -Author: - type: object - properties: - name: - type: string -``` - - - - -### 4.2 — Nested model with custom XML name on the model - -When the referenced model has `@Xml.name` or `@encodedName`, the property name still takes precedence for the XML element name. - - - - -```tsp -model Book { - author: Author; -} - -@Xml.name("XmlAuthor") -model Author { - name: string; -} -``` - - - - -```tsp -model Book { - author: Author; -} - -@encodedName("application/xml", "XmlAuthor") -model Author { - name: string; -} -``` - - - - - - - -```xml - - - F. Scott Fitzgerald - - -``` - - - - -```yaml -Book: - type: object - properties: - author: - allOf: - - $ref: "#/components/schemas/Author" - xml: - name: "author" # Here we have to redefine this name otherwise in OpenAPI semantic the `XmlAuthor` name would be used -Author: - type: object - properties: - name: - type: string - xml: - name: "XmlAuthor" -``` - - - - -### 4.3 — Nested model with custom XML name on the property - -Using `@Xml.name` or `@encodedName` on the property overrides the element name for the nested model. - - - - -```tsp -model Book { - @Xml.name("xml-author") - author: Author; -} - -model Author { - name: string; -} -``` - - - - -```tsp -model Book { - @encodedName("application/xml", "xml-author") - author: Author; -} - -model Author { - name: string; -} -``` - - - - - - - -```xml - - - F. Scott Fitzgerald - - -``` - - - - -```yaml -Book: - type: object - properties: - author: - allOf: - - $ref: "#/components/schemas/Author" - xml: - name: "xml-author" -Author: - type: object - properties: - name: - type: string -``` - - - ## 5. Attributes From 5e51689d21b6398c928cdab9c95016630a0147c6 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 16:49:44 -0400 Subject: [PATCH 06/10] section 5 --- .../content/docs/docs/libraries/xml/guide.mdx | 75 +++++++++++++++++-- 1 file changed, 68 insertions(+), 7 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 575b6a05420..593d0bd8b18 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -975,21 +975,18 @@ Store: - ## 5. Attributes -### 5.1 — XML attributes and element name override +### 5.1 — Serializing a property as an XML attribute -`@Xml.attribute` serializes a property as an XML attribute instead of a child element. `@Xml.name` overrides the XML element name. +`@Xml.attribute` serializes a property as an XML attribute instead of a child element. ```tsp model Book { @Xml.attribute id: integer; - @Xml.name("xml-title") title: string; - author: string; } ``` @@ -999,7 +996,7 @@ model Book { ```xml - The Great Gatsby + The Great Gatsby F. Scott Fitzgerald ``` @@ -1017,8 +1014,72 @@ Book: attribute: true title: type: string + author: + type: string +``` + + + + +### 5.2 — Renaming an XML attribute + +`@Xml.name` or `@encodedName` on an `@Xml.attribute` property changes the attribute name in the XML output. + + + + +```tsp +model Book { + @Xml.attribute + @Xml.name("xml-id") + id: integer; + + title: string; + author: string; +} +``` + + + + +```tsp +model Book { + @Xml.attribute + @encodedName("application/xml", "xml-id") + id: integer; + + title: string; + author: string; +} +``` + + + + + + + +```xml + + The Great Gatsby + F. Scott Fitzgerald + +``` + + + + +```yaml +Book: + type: object + properties: + id: + type: integer xml: - name: "xml-title" + attribute: true + name: "xml-id" + title: + type: string author: type: string ``` From 14d3b41152ee60e67e547d1d925d29afc79e8009 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 18:37:51 -0400 Subject: [PATCH 07/10] fix order --- .../content/docs/docs/libraries/xml/guide.mdx | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 593d0bd8b18..393a50b1118 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -190,7 +190,7 @@ Book: ## 2. Nested models -### 4.1 — Basic nested model +### 2.1 — Basic nested model A property referencing another model is serialized as a nested XML element using the property name. @@ -234,7 +234,7 @@ Author: -### 4.2 — Nested model with custom XML name on the model +### 2.2 — Nested model with custom XML name on the model When the referenced model has `@Xml.name` or `@encodedName`, the property name still takes precedence for the XML element name. @@ -304,7 +304,7 @@ Author: -### 4.3 — Nested model with custom XML name on the property +### 2.3 — Nested model with custom XML name on the property Using `@Xml.name` or `@encodedName` on the property overrides the element name for the nested model. @@ -374,7 +374,7 @@ Author: ## 3. Array of primitive types -### 4.1 — Wrapped primitive array (default) +### 3.1 — Wrapped primitive array (default) By default, an array property is wrapped in a container element named after the property. Each item uses the scalar type name as its element name. @@ -416,7 +416,7 @@ Book: -### 4.2 — Unwrapped primitive array +### 3.2 — Unwrapped primitive array `@Xml.unwrapped` removes the wrapper element. Each item is serialized using the property name as its XML element name. @@ -455,7 +455,7 @@ Book: -### 4.3 — Wrapped primitive array with custom wrapper name +### 3.3 — Wrapped primitive array with custom wrapper name Without `@Xml.unwrapped`, the array is wrapped in a container element. `@Xml.name` or `@encodedName` on the property customizes the wrapper element name. @@ -515,7 +515,7 @@ Book: -### 4.4 — Unwrapped primitive array with custom item name +### 3.4 — Unwrapped primitive array with custom item name `@Xml.name` or `@encodedName` on the property controls the element name of each item when the array is unwrapped. @@ -572,7 +572,7 @@ Book: -### 4.5 — Wrapped primitive array with custom wrapper and item names +### 3.5 — Wrapped primitive array with custom wrapper and item names Both the wrapper element and each item element have custom names via `@Xml.name` or `@encodedName`. From 6331655938a9fd43965ab3d4dac385c5b4e4941e Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 23:29:56 -0400 Subject: [PATCH 08/10] guide --- .../content/docs/docs/libraries/xml/guide.mdx | 40 +++++++++---------- 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 393a50b1118..4de8361675a 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -196,10 +196,10 @@ A property referencing another model is serialized as a nested XML element using ```tsp model Book { - author: Author; + author: Person; } -model Author { +model Person { name: string; } ``` @@ -223,8 +223,8 @@ Book: type: object properties: author: - $ref: "#/components/schemas/Author" -Author: + $ref: "#/components/schemas/Person" +Person: type: object properties: name: @@ -243,11 +243,11 @@ When the referenced model has `@Xml.name` or `@encodedName`, the property name s ```tsp model Book { - author: Author; + author: Person; } -@Xml.name("XmlAuthor") -model Author { +@Xml.name("XmlPerson") +model Person { name: string; } ``` @@ -257,11 +257,11 @@ model Author { ```tsp model Book { - author: Author; + author: Person; } -@encodedName("application/xml", "XmlAuthor") -model Author { +@encodedName("application/xml", "XmlPerson") +model Person { name: string; } ``` @@ -289,16 +289,16 @@ Book: properties: author: allOf: - - $ref: "#/components/schemas/Author" + - $ref: "#/components/schemas/Person" xml: - name: "author" # Here we have to redefine this name otherwise in OpenAPI semantic the `XmlAuthor` name would be used -Author: + name: "author" # Here we have to redefine this name otherwise in OpenAPI semantic the `XmlPerson` name would be used +Person: type: object properties: name: type: string xml: - name: "XmlAuthor" + name: "XmlPerson" ``` @@ -314,10 +314,10 @@ Using `@Xml.name` or `@encodedName` on the property overrides the element name f ```tsp model Book { @Xml.name("xml-author") - author: Author; + author: Person; } -model Author { +model Person { name: string; } ``` @@ -328,10 +328,10 @@ model Author { ```tsp model Book { @encodedName("application/xml", "xml-author") - author: Author; + author: Person; } -model Author { +model Person { name: string; } ``` @@ -359,10 +359,10 @@ Book: properties: author: allOf: - - $ref: "#/components/schemas/Author" + - $ref: "#/components/schemas/Person" xml: name: "xml-author" -Author: +Person: type: object properties: name: From f3fe53d4ae6542ee5ab3f1e380d3f58925c57043 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 24 Mar 2026 14:19:04 -0400 Subject: [PATCH 09/10] add docs for named array model --- .../content/docs/docs/libraries/xml/guide.mdx | 156 ++++++++++++++++++ 1 file changed, 156 insertions(+) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 4de8361675a..9f66d77d359 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -1350,3 +1350,159 @@ BookTitle: + +## 9. Array models + +An _array model_ is a named model that _is_ an array rather than a model that _has_ an array property. It is declared with `model X is Type[]`. + +### 9.1 — Array model by itself + +A standalone array model produces an array schema in OpenAPI. When serialized to XML, the model name becomes the root element and each item uses its type name as the element name. + +```tsp +model Tags is string[]; +``` + + + + +```xml + + fiction + classic + +``` + + + + +```yaml +Tags: + type: "array" + items: + type: "string" +``` + + + + +### 9.2 — Array model used in a property (default) + +When a property references an array model, it behaves the same as an inline array: the property name becomes the wrapper element and each item uses its type name as the element name. + +```tsp +model BookList is Book[]; + +model Book { + title: string; +} + +model Store { + books: BookList; +} +``` + + + + +```xml + + + + The Great Gatsby + + + Les Miserables + + + +``` + + + + +```yaml +Book: + type: "object" + properties: + title: + type: "string" +BookList: + type: "array" + items: + $ref: "#/components/schemas/Book" +Store: + type: "object" + properties: + books: + type: "array" + xml: + wrapped: true + items: + allOf: + - $ref: "#/components/schemas/Book" + xml: + name: "Book" +``` + + + + +### 9.3 — Unwrapped array model property + +`@Xml.unwrapped` on the property removes the wrapper element, just as with inline arrays. + +```tsp +model BookList is Book[]; + +model Book { + title: string; +} + +model Store { + @Xml.unwrapped + books: BookList; +} +``` + + + + +```xml + + + The Great Gatsby + + + Les Miserables + + +``` + + + + +```yaml +Book: + type: "object" + properties: + title: + type: "string" +BookList: + type: "array" + items: + $ref: "#/components/schemas/Book" +Store: + type: "object" + properties: + books: + type: "array" + items: + allOf: + - $ref: "#/components/schemas/Book" + xml: + name: "books" +``` + + + From 34cafad1a180187d0859e99ad571a01ad4b6623d Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Tue, 24 Mar 2026 14:20:50 -0400 Subject: [PATCH 10/10] reorder --- .../content/docs/docs/libraries/xml/guide.mdx | 334 +++++++++--------- 1 file changed, 167 insertions(+), 167 deletions(-) diff --git a/website/src/content/docs/docs/libraries/xml/guide.mdx b/website/src/content/docs/docs/libraries/xml/guide.mdx index 9f66d77d359..762c3200874 100644 --- a/website/src/content/docs/docs/libraries/xml/guide.mdx +++ b/website/src/content/docs/docs/libraries/xml/guide.mdx @@ -975,9 +975,165 @@ Store: -## 5. Attributes +## 5. Array models -### 5.1 — Serializing a property as an XML attribute +An _array model_ is a named model that _is_ an array rather than a model that _has_ an array property. It is declared with `model X is Type[]`. + +### 5.1 — Array model by itself + +A standalone array model produces an array schema in OpenAPI. When serialized to XML, the model name becomes the root element and each item uses its type name as the element name. + +```tsp +model Tags is string[]; +``` + + + + +```xml + + fiction + classic + +``` + + + + +```yaml +Tags: + type: "array" + items: + type: "string" +``` + + + + +### 5.2 — Array model used as a property (default) + +When a property references an array model, it behaves the same as an inline array: the property name becomes the wrapper element and each item uses its type name as the element name. + +```tsp +model BookList is Book[]; + +model Book { + title: string; +} + +model Store { + books: BookList; +} +``` + + + + +```xml + + + + The Great Gatsby + + + Les Miserables + + + +``` + + + + +```yaml +Book: + type: "object" + properties: + title: + type: "string" +BookList: + type: "array" + items: + $ref: "#/components/schemas/Book" +Store: + type: "object" + properties: + books: + type: "array" + xml: + wrapped: true + items: + allOf: + - $ref: "#/components/schemas/Book" + xml: + name: "Book" +``` + + + + +### 5.3 — Unwrapped array model property + +`@Xml.unwrapped` on the property removes the wrapper element, just as with inline arrays. + +```tsp +model BookList is Book[]; + +model Book { + title: string; +} + +model Store { + @Xml.unwrapped + books: BookList; +} +``` + + + + +```xml + + + The Great Gatsby + + + Les Miserables + + +``` + + + + +```yaml +Book: + type: "object" + properties: + title: + type: "string" +BookList: + type: "array" + items: + $ref: "#/components/schemas/Book" +Store: + type: "object" + properties: + books: + type: "array" + items: + allOf: + - $ref: "#/components/schemas/Book" + xml: + name: "books" +``` + + + + +## 6. Attributes + +### 6.1 — Serializing a property as an XML attribute `@Xml.attribute` serializes a property as an XML attribute instead of a child element. @@ -1021,7 +1177,7 @@ Book: -### 5.2 — Renaming an XML attribute +### 6.2 — Renaming an XML attribute `@Xml.name` or `@encodedName` on an `@Xml.attribute` property changes the attribute name in the XML output. @@ -1087,9 +1243,9 @@ Book: -## 6. Namespace and prefix (inline form) +## 7. Namespace and prefix (inline form) -### 6.1 — Namespace on the model +### 7.1 — Namespace on the model `@Xml.ns` on a model adds a namespace prefix and declaration to the root element. @@ -1134,7 +1290,7 @@ Book: -### 6.2 — Namespace on individual properties +### 7.2 — Namespace on individual properties Properties can declare their own namespace with `@Xml.ns`, which may differ from the model's namespace. @@ -1189,9 +1345,9 @@ Book: -## 7. Namespace and prefix (normalized form) +## 8. Namespace and prefix (normalized form) -### 7.1 — Using an `@Xml.nsDeclarations` enum +### 8.1 — Using an `@Xml.nsDeclarations` enum Declare namespaces in an enum to avoid repeating URIs. Reference enum members with `@Xml.ns`. @@ -1245,7 +1401,7 @@ Namespaces: -### 7.2 — Multiple namespaces via enum +### 8.2 — Multiple namespaces via enum Multiple namespace declarations can be defined in a single enum and referenced on individual properties. @@ -1311,9 +1467,9 @@ Namespaces: -## 8. Property setting the text of the node +## 9. Property setting the text of the node -### 8.1 — Text content with attributes +### 9.1 — Text content with attributes `@Xml.unwrapped` on a scalar property makes it the text content of the parent element. Combined with `@Xml.attribute`, you can model elements that have both attributes and inline text. @@ -1350,159 +1506,3 @@ BookTitle: - -## 9. Array models - -An _array model_ is a named model that _is_ an array rather than a model that _has_ an array property. It is declared with `model X is Type[]`. - -### 9.1 — Array model by itself - -A standalone array model produces an array schema in OpenAPI. When serialized to XML, the model name becomes the root element and each item uses its type name as the element name. - -```tsp -model Tags is string[]; -``` - - - - -```xml - - fiction - classic - -``` - - - - -```yaml -Tags: - type: "array" - items: - type: "string" -``` - - - - -### 9.2 — Array model used in a property (default) - -When a property references an array model, it behaves the same as an inline array: the property name becomes the wrapper element and each item uses its type name as the element name. - -```tsp -model BookList is Book[]; - -model Book { - title: string; -} - -model Store { - books: BookList; -} -``` - - - - -```xml - - - - The Great Gatsby - - - Les Miserables - - - -``` - - - - -```yaml -Book: - type: "object" - properties: - title: - type: "string" -BookList: - type: "array" - items: - $ref: "#/components/schemas/Book" -Store: - type: "object" - properties: - books: - type: "array" - xml: - wrapped: true - items: - allOf: - - $ref: "#/components/schemas/Book" - xml: - name: "Book" -``` - - - - -### 9.3 — Unwrapped array model property - -`@Xml.unwrapped` on the property removes the wrapper element, just as with inline arrays. - -```tsp -model BookList is Book[]; - -model Book { - title: string; -} - -model Store { - @Xml.unwrapped - books: BookList; -} -``` - - - - -```xml - - - The Great Gatsby - - - Les Miserables - - -``` - - - - -```yaml -Book: - type: "object" - properties: - title: - type: "string" -BookList: - type: "array" - items: - $ref: "#/components/schemas/Book" -Store: - type: "object" - properties: - books: - type: "array" - items: - allOf: - - $ref: "#/components/schemas/Book" - xml: - name: "books" -``` - - -