From d4ae1ddd57bc818b849ad0d6bb2335f5819888bc Mon Sep 17 00:00:00 2001 From: "Henry H. Andrews" Date: Sun, 9 Jun 2024 10:55:39 -0700 Subject: [PATCH] Fix XML namespace syntax The XML Object's namespace field was changed from "URL" to "absolute URI" because relative references in a namespace are deprecated by XML, and the base URI to use for resolving them in the context of an OpenAPI Description is unclear. However, XML namespaces can include fragments, and the correct term is "non-relative URI" rather than "absolute URI" which forbids fragments. This change includes additional guidance on how XML usage and the requirements of this specification do not quite align. --- versions/3.0.4.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/versions/3.0.4.md b/versions/3.0.4.md index 8dda05e8ba..7f544024c0 100644 --- a/versions/3.0.4.md +++ b/versions/3.0.4.md @@ -3183,13 +3183,19 @@ See examples for expected behavior. Field Name | Type | Description ---|:---:|--- name | `string` | Replaces the name of the element/attribute used for the described schema property. When defined within `items`, it will affect the name of the individual XML elements within the list. When defined alongside `type` being `array` (outside the `items`), it will affect the wrapping element and only if `wrapped` is `true`. If `wrapped` is `false`, it will be ignored. -namespace | `string` | The URI of the namespace definition. Value MUST be in the form of an absolute URI. +namespace | `string` | The URI of the namespace definition. Value MUST be in the form of a non-relative URI. prefix | `string` | The prefix to be used for the [name](#xmlName). attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`. wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, ``) or unwrapped (``). Default value is `false`. The definition takes effect only when defined alongside `type` being `array` (outside the `items`). This object MAY be extended with [Specification Extensions](#specificationExtensions). +The `namespace` keyword is intended to match the syntax of [XML namespaces](https://www.w3.org/TR/xml-names11/), although there are a few caveats: + +* Version 3.0.3 and earlier of this specification erroneously used the term "absolute URI" instead of "non-relative URI", so authors using namespaces that include a fragment should check tooling support carefully. +* XML allows but discourages relative URI-references, while this specification outright forbids them. +* XML 1.1 allows IRIs ([RFC3987](https://datatracker.ietf.org/doc/html/rfc3987)) as namespaces, and specifies that namespaces are compared without any encoding or decoding, which means that IRIs encoded to meet this specification's URI syntax requirement cannot be compared to IRIs as-is. + ##### XML Object Examples Each of the following examples represent the value of the `properties` keyword in a [Schema Object](#schemaObject) that is omitted for brevity.