Merge pull request #3905 from handrews/xmlns-304

Fix XML namespace syntax

versions/3.0.4.md

@@ -3183,13 +3183,19 @@ See examples for expected behavior.
 Field Name | Type | Description
 ---|:---:|---
 <a name="xmlName"></a>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.
-<a name="xmlNamespace"></a>namespace | `string` | The URI of the namespace definition. Value MUST be in the form of an absolute URI.
+<a name="xmlNamespace"></a>namespace | `string` | The URI of the namespace definition. Value MUST be in the form of a non-relative URI.
 <a name="xmlPrefix"></a>prefix | `string` | The prefix to be used for the [name](#xmlName).
 <a name="xmlAttribute"></a>attribute | `boolean` | Declares whether the property definition translates to an attribute instead of an element. Default value is `false`.
 <a name="xmlWrapped"></a>wrapped | `boolean` | MAY be used only for an array definition. Signifies whether the array is wrapped (for example, `<books><book/><book/></books>`) or unwrapped (`<book/><book/>`). 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.