From 0d3c536cd8a5c570fa44f4283ac431a795de656d Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 18 May 2025 09:13:50 -0700 Subject: [PATCH] Allow xml field in any schema as a MAY This allows implementations to support the `xml` Schema Object field / JSON Schema extension keyword in any Schema Object, with a recommendation that the behavior be forward-compatible with OAS 3.2. --- src/oas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/oas.md b/src/oas.md index 243fd1c084..7cc1970791 100644 --- a/src/oas.md +++ b/src/oas.md @@ -2749,7 +2749,7 @@ JSON Schema implementations MAY choose to treat keywords defined by the OpenAPI | Field Name | Type | Description | | ---- | :----: | ---- | | discriminator | [Discriminator Object](#discriminator-object) | Adds support for polymorphism. The discriminator is used to determine which of a set of schemas a payload is expected to satisfy. See [Composition and Inheritance](#composition-and-inheritance-polymorphism) for more details. | -| xml | [XML Object](#xml-object) | This MAY be used only on property schemas. It has no effect on root schemas. Adds additional metadata to describe the XML representation of this property. | +| xml | [XML Object](#xml-object) | Implementations MUST support this field on property schemas, and MAY support it in other kinds of schemas, in which case such support SHOULD follow the guidance in version 3.2 of this specification for forward compatibility. Adds additional metadata to describe the XML representation of this property. | | externalDocs | [External Documentation Object](#external-documentation-object) | Additional external documentation for this schema. | | example | Any | A free-form field to include an example of an instance for this schema. To represent examples that cannot be naturally represented in JSON or YAML, a string value can be used to contain the example with escaping where necessary.

**Deprecated:** The `example` field has been deprecated in favor of the JSON Schema `examples` keyword. Use of `example` is discouraged, and later versions of this specification may remove it. |