does the XML "namespace" field allow URI fragments?

[handrews]

OAS states that the namespace field of the XML Object "MUST be in the form of an absolute URI." (3.0; 3.1).

Technically, an absolute URI cannot have a fragment. However, XML Namespaces are defined as URI-references, although relative references are deprecated. The intention of URI-references-but-not-relative-URI-references is to allow fragments in namespace URIs.

If OAS intended to be aligned with this usage (no relative references, but yes fragments), then the wording needs to be changed.

[MikeRalphson]

Why would you use an (xpath?) fragment id to identify a portion of an XML resource as a namespace?

[handrews]

@MikeRalphson I haven't used XML for anything in decades :-)

However, RDF namespaces are related to XML namespaces and typically include an empty fragment (because namespace URIs are prefixes, not base URIs, and RDF vocabulary terms are defined as plain name fragments within the resource). The RDF/XML specification shows that http://www.w3.org/1999/02/22-rdf-syntax-ns# is the standard XML namespace for RDF.

Here's an example from the spec:

<?xml version="1.0"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
            xmlns:dc="http://purl.org/dc/elements/1.1/"
            xmlns:ex="http://example.org/stuff/1.0/">

  <rdf:Description rdf:about="http://www.w3.org/TR/rdf-syntax-grammar"
             dc:title="RDF1.1 XML Syntax">
    <ex:editor>
      <rdf:Description ex:fullName="Dave Beckett">
        <ex:homePage rdf:resource="http://purl.org/net/dajobe/" />
      </rdf:Description>
    </ex:editor>
  </rdf:Description>

</rdf:RDF>

[MikeRalphson]

An optional empty fragment id I can get behind.

[handrews]

@MikeRalphson as a use case for a non-empty fragment, consider the compliance project. I'll be defining an ontology for OAS 3.0 and 3.1 concepts. I could, of course, put these in separate documents and use an empty-fragment namespace for each.

However, I want to ensure that certain concepts are defined as identical in 3.0 and 3.1 while still giving them separate URIs to avoid asking users to use a mix of 3.0 and 3.1 terms when working with 3.1. I will also want to define that some concepts, while not identical, are analogous.

This should be easier to do if both ontologies are defined in the same resource. If one is using both ontologies at once (because you are describing multiple APIs, some using 3.0 and 3.1) then declaring a namespace of https://openapis.org/ontology# and using term names like oas3.0.SchemaObject and oas3.1.SchemaObject would make sense. But if you are working with just one version, declaring a namespace prefix of https://openapis.org/ontology#oas3.0. and using term names like SchemaObject would be more suitable. (I think . ends up being legal here, but if not, then some other character - it's legal in URI fragments, but prefixed names use a more limited character set).

[MikeRalphson]

But the xml object is only for hinting at the conversion between the JSON Schema and XML object mappings within an OpenAPI document's schema objects. And the namespace property definition is only valid within this context.

It isn't clear to me that the compliance parser operates within, or on, this context.

[handrews]

@MikeRalphson the question is whether the namespace is supposed to be an actual XML namespace or not. I was just showing that there is a use case for XML namespaces with non-empty fragments, in order to make a general point about the syntax.

If namespace is not really an XML namespace, a.) it's badly named and b.) it can do whatever it wants.

[MikeRalphson]

@handrews then in that case a PR would be great if you have time!

[handrews]

@OAI/tsc review request: My take is that this was an error - the original change switched from "URL" to "absolute URI", which was not explained in the PR or issue but was likely to avoid treating the XML namespace as a URL (because that's not how they work) and to align with XML's deprecation of relative URI-references as namespaces. I doubt there was intention to remove the fragment, as that is not how XML namespaces work either.

Is this, as a bug, OK to fix in 3.0.4 and 3.1.1? Or are we stuck with it until 3.2.0?

[ralfhandl]

fix in 3.0.4 and 3.1.1

Yes, please!

[lornajane]

Discussed in TDC and since this won't make anything that is currently valid become invalid, and we agree this captures the original intent then changing to non-relative URI is good and can be done in patch.

[handrews]

PR merged for 3.0.4 and ported to 3.1.1 via PR #3921!