Last modified: 2013-04-08 11:02:25 UTC
It would be useful to define an XML namespace for any XML-Formatted output of the web API. This would allow us to embed elements from that output in other XML documents easily. My own use case is embedding <rc> tags in XMPP stanzas. I would suggest to use the URI http://www.mediawiki.org/xml/api-0.1 for the namespace. In practice, this would mean that the top level <api> tag returned by the API would become: <api xmlns="http://www.mediawiki.org/xml/api-0.1"> This should have no impact whatsoever on backward compatibility, except perhaps for clients processing the XML using naive regular expressions. I believe it would be ok to break those, since they rely on things that are never guaranteed in XML.
I agree on the breakage - It's not as if we're breaking conformity to valid xml etc. IIRC (NB, I've not done much with this), we don't need to have anything served at that URL do we, it's just like an identifier?
Would anything need to be present at that URL? It currently 404s. If it needs like a full schema of possible outputs, that's a problem.
no, namespaces are pure URIs. nothing needs to be there. Namespaces also don't require any schema or dtd. it's useful to have some kind of documentation at that location though.
http://www.mediawiki.org/wiki/api would be the easiest to have documentation there ;)
>This should have no impact whatsoever on backward compatibility If you're using a namespace aware xml parser to parse the api, this could break it if your code expects the api output to have no namespace, and now it suddenly does.
at #5: how would the code expect that? In what way would one usually rely on the fact that no namespace is used? And if so, why use a namespace aware parser? I understand the point in theory, but can't imagine when it would actually happen.
It is still rather far fetched, I just thought I should mention it because it seemed more likely breakage case than the regex one.
Bringing some life back here. The fix is fairly simple, and there are possibly some breakages. I'm almost inclined to just say "tough" to those not doing it properly Thoughts?
Although I would defer to those more familiar with all things XMLish, I'm inclined to agree with Reedy here. Anything that breaks because of a change like this was really already broken. (Of course, having said that, I bet my own API clients are going to choke on it... :)
Daniel poked me about this at the hackathon, gonna start doing this in a minute.
Fixed in r88007. I used http://www.mediawiki.org/xml/api/ as a namespace and created that URL on the cluster as well.
Not completely breakage-proof, it seems: see the comment about XPATH at http://www.mediawiki.org/wiki/Special:Code/MediaWiki/88007#c23862 reported by a user of the jdom library.
Just a note, this really is a breaking change for some parsers. Specifically, for the one I'm using: LINQ to XML in .Net. It is namespace-aware and when a namespace is present, it has to be always used. For example to get the root node, previously you would do: var elem = document.Element("api"); With the namespace, the previous code wouldn't work and would have to be changed to: XNamespace ns = "http://www.mediawiki.org/xml/api/"; var elem = document.Element(ns + "api"); I'm not arguing against the change (I think it's a good idea), but I wanted to let you know that it's going to be a breaking change, at least for some people.
Since this apparently is a breaking change, can we revert it and make the addition of a namespace optional, perhaps with the boolean includexmlnamespace?
(In reply to comment #14) > Since this apparently is a breaking change, can we revert it and make the > addition of a namespace optional, perhaps with the boolean includexmlnamespace? Sounds good. Mind doing this yourself? I'm busy packing now and will be traveling for the next few days.
r99135
(In reply to comment #16) > r99135 Deployed.
This would make me sad if this is a permanent option, since this is option bloat. LINQ to XML in .Net is presenting a really broken API if it's requiring the caller provide the namespace URI to parse the resulting XML. Not the end of the world if we have to leave it in there, but wow that's sad.
(In reply to comment #18) > This would make me sad if this is a permanent option, since this is option > bloat. LINQ to XML in .Net is presenting a really broken API if it's requiring > the caller provide the namespace URI to parse the resulting XML. Not the end > of the world if we have to leave it in there, but wow that's sad. If you think this is sad, you ain't seen nothin' yet ;)
For the record: Many XML parsers, including (as noted) JDOM and MSXML (on top of which the .NET XML library, among many other libraries, is built) are namespace-aware. This isn't "not doing it properly", it's arguably doing it properly, since two XML nodes that only differ in which namespace they belong to should be treated as different node types.
