From 5ec079037c13e50023a340154a0d7dc2760e5e04 Mon Sep 17 00:00:00 2001 From: Timothee Guerin Date: Mon, 16 Mar 2026 14:43:53 -0400 Subject: [PATCH 1/8] 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 2/8] 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 3/8] 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 4/8] 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 5/8] 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 6/8] 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 7/8] 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 8/8] 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: