Subject: Re: [apps-discuss] New Version Notification for draft-nottingham-http-problem-02.txt

From: Conal Tuohy <[email-masked]>
Date: Mon, 17 Dec 2012 14:27:37 +1000

Can I suggest that the XML format known as the media type 
"application/api-problem+xml" should use an XML namespace?

Using namespaces to disambiguate XML vocabularies is considered best 
practice. It allows for an XML document to be correctly interpreted even 
outside the HTTP context in which it might appear (i.e. without knowing 
the specific internet media type). See 
http://www.w3.org/TR/webarch/#xml-namespaces for details, and also see 
http://www.w3.org/TR/webarch/#namespace-document for the reasons why 
namespace URIs should resolve to useful documentation (such as an RFC 
document).

It seems to me that the relationship between the names of JSON objects 
and corresponding XML elements also needs clarification.

For instance, the XML schema allows those objects to be in "##any" 
namespace, but how would those namespaces relate to JSON expressions of 
the same error report? If a JSON problem report were to be transformed 
into XML, what XML namespaces would actually be used for any extension 
members? Conversely, if an XML-formatted problem report were converted 
to JSON, how would any XML namespaces be rendered in the JSON?

Conal

-- 
Conal Tuohy
eResearch Business Analyst
Victorian eResearch Strategic Initiative
+61-466324297

-- 
Conal Tuohy
HuNI <http://huni.net.au/> Technical Coordinator 
<http://apidictor.huni.net.au/trac/wiki/ConalSpace>
Victorian eResearch Strategic Initiative 
<http://versi.edu.au/about-us/versi-team#Con>
Skype: conal.tuohy
Twitter: @conal_tuohy <https://twitter.com/conal_tuohy>
Mobile: +61-466324297 <tel:+61-466324297>

---

From: Mark Nottingham <[email-masked]>
Date: Mon, 17 Dec 2012 16:34:26 +1100

Hi Conal,

On 17/12/2012, at 3:27 PM, Conal Tuohy <[email-masked]> wrote:

> 
> Can I suggest that the XML format known as the media type "application/api-problem+xml" should use an XML namespace?

You can certainly suggest it :)

> Using namespaces to disambiguate XML vocabularies is considered best practice. It allows for an XML document to be correctly interpreted even outside the HTTP context in which it might appear (i.e. without knowing the specific internet media type). See http://www.w3.org/TR/webarch/#xml-namespaces for details, and also see http://www.w3.org/TR/webarch/#namespace-document for the reasons why namespace URIs should resolve to useful documentation (such as an RFC document).

Yes, I'm familiar with the WebArch document. In practice, XML Namespaces can cause a lot of developer confusion, and I'd put forth that they should only be used where distributed extensibility is necessary, and there are no other ways to achieve it. 

Here, because the definition of the problem type (and thereby, its extensions) is controlled by the person that mints it (using a describedBy link), there isn't a need for distributed extensibility, as far as I can see. Furthermore, using XML namespaces would force the use of a similar mechanism with JSON, which would make me (and many others, I think) unhappy.

> It seems to me that the relationship between the names of JSON objects and corresponding XML elements also needs clarification. 
> 
> For instance, the XML schema allows those objects to be in "##any" namespace, but how would those namespaces relate to JSON expressions of the same error report? If a JSON problem report were to be transformed into XML, what XML namespaces would actually be used for any extension members? Conversely, if an XML-formatted problem report were converted to JSON, how would any XML namespaces be rendered in the JSON?

I'm CC:ing Erik because he helped me add the XML format (which I was somewhat reluctant to do). 

No namespaces would be used, as I understand it. Erik, does the schema need revision?

Cheers,

P.S. Conal, if you're in Melbourne, It'd be great to chat over a coffee sometime; I'd love to hear more about your use cases.

--
Mark Nottingham   http://www.mnot.net/

---

From: Erik Wilde <[email-masked]>
Date: Mon, 17 Dec 2012 15:22:23 -0800

hello conal.

> You can certainly suggest it :)

and that's what i came up with as my first proposed design ;-) but then 
we moved away from that, and so far it's the first cut at defining an 
XML format, and things are open for discussion. so thanks for your comments!

> Yes, I'm familiar with the WebArch document. In practice, XML Namespaces can cause a lot of developer confusion, and I'd put forth that they should only be used where distributed extensibility is n…

i tend to believe that developers are not quite as bad as grappling with 
them as sometimes is assumed, but they certainly still are something 
that many people not very familiar with XML are confused about. i like 
them because they make XML documents truly self-describing, and the 
extensibility is a nice side-effect.

> Here, because the definition of the problem type (and thereby, its extensions) is controlled by the person that mints it (using a describedBy link), there isn't a need for distributed extensibility…

and that was the main poin in mark's argument for me. in XML, you get 
namespaces for free, and while some people dislike them, they are just 
part of the established tech landscape. if you want to represent things 
across XML and JSON, then mapping XML-enabled XML to JSON just becomes 
fairly painful, because of JSON's simplicity. since the intention is to 
keep XML and JSON aligned, and use JSON as the canonical format, adding 
namespaces to the XML variant makes things surprisingly complicated.

> No namespaces would be used, as I understand it. Erik, does the schema need revision?

good catch, that was probably something from earlier namespace-aware 
exercises. 
https://github.com/dret/I-D-1/blob/master/http-problem/http-problem-03.xsd 
is the updated "##targetNamespace" version, allowing only non-namespace 
XML (and thus easy mapping to and from JSON, as long as the JSON labels 
do not validate XML's naming rules, of course...). is still has issues 
because of XSD's UPA constraint, but for now i'll leave that as an 
exercise for further refinement...

@mark, should we add a constraint to the JSON definition that for the 
only XML NCNames SHOULD be used (it currently says "names SHOULD conform 
to token [RFC2616]"), or something along these lines?

cheers,

dret.

-- 
erik wilde | mailto:[email-masked]  -  tel:+1-510-2061079 |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |

---

From: Mark Nottingham <[email-masked]>
Date: Tue, 18 Dec 2012 11:39:45 +1100

On 18/12/2012, at 10:22 AM, Erik Wilde <[email-masked]> wrote:
> 
> @mark, should we add a constraint to the JSON definition that for the only XML NCNames SHOULD be used (it currently says "names SHOULD conform to token [RFC2616]"), or something along these lines?

I chose token to make it compatible with other serialisations as well (e.g., in a HTTP Header); XML isn't the only (other) game in town.

Cheers,

---

From: Erik Wilde <[email-masked]>
Date: Mon, 17 Dec 2012 16:44:37 -0800

> I chose token to make it compatible with other serialisations as well (e.g., in a HTTP Header); XML isn't the only (other) game in town.

sure. but for those serializations we know of, maybe being friendly to 
them is a good idea. token is more permissible than NCName and thus 
allows things that don't work too well in XML-land. maybe choose the 
intersection of all of the ones we know of?

cheers,

dret.

---

From: Mark Nottingham <[email-masked]>
Date: Wed, 19 Dec 2012 11:33:53 +1100

On 18/12/2012, at 11:44 AM, Erik Wilde <[email-masked]> wrote:

> sure. but for those serializations we know of, maybe being friendly to them is a good idea. token is more permissible than NCName and thus allows things that don't work too well in XML-land. maybe choose the intersection of all of the ones we know of?

Makes sense, although I don't want to do it by reference to NCName...

---

From: Mark Nottingham <[email-masked]>
Date: Fri, 21 Dec 2012 11:51:42 +1100

This is what I have now:

>       <t>If such additional members are defined, their names SHOULD start with
>       a letter (ALPHA, as per <xref target="RFC5234"/> and SHOULD consist of
>       characters from ALPHA, DIGIT and "_", so that it can be serialised in
>       formats other than JSON, and SHOULD be three characters or longer.</t>