Re: [apps-discuss] WGLC on draft-ietf-appsawg-http-problem-00.txt

[Erik Wilde <[e-mail]>]

hello julian.

thanks for the detailed feedback!

On 2014-12-08, 15:35 , Mark Nottingham wrote:
>> On 8 Dec 2014, at 6:41 pm, Julian Reschke <[e-mail]> wrote:
>> In the spec:
>>>     The data model for problem details is a JSON [RFC7159] object; when
>>>     formatted as a JSON document, it uses the "application/problem+json"
>>>     media type.  Appendix A defines how to express them in an equivalent
>>>     XML format, which uses the "application/problem+xml" media type.
>> Why is this an appendix?
> When all things are equal, I'd prefer people to use JSON for APIs, not XML. If we move it to be a peer of the JSON format, we'd need to have some text advising when to use each, and that could get sticky. Putting it in an appendix seemed like a reasonable compromise. If we don't put it in an appendix, I'd almost want to put it in a separate document...

to me, it seems like the error serialization should simply match the 
serialization of the rest of the API, so there wouldn't be a need to 
recommend anything beyond this.

as a side note, for home documents, we have the setup that mark is 
referring to: two separate documents for JSON and XML:

http://tools.ietf.org/html/draft-nottingham-json-home-03
http://tools.ietf.org/html/draft-wilde-home-xml-03

personally, i think it's easier to have one document explain the overall 
model, and then have two serializations of it in the same documents, but 
i am fine either way.

>>>     The OPTIONAL RELAX NG schema [ISO-19757-2] for the XML format is:
>> What does "OPTIONAL" mean here? The schema doesn't seem optional at all; lacking it, you wouldn't even know what XML namespace to use.
> That's Erik's work, but I tend to agree.

i have a hard time remembering why it says "OPTIONAL" here. i think the 
reason was that we did not want to recommend a specific schema language 
and were simply using RELAX NG as one possible choice. but i think 
you're right that the term "OPTIONAL" does not make a lot of sense.

>>>     default namespace ns = "urn:ietf:rfc:XXXX"
>> This needs to state that it will be updated based on the assigned RFC number.
> Ack.

done. ("Note to RFC Editor: Please replace "XXXX" with assigned RFC 
number before publication.")

>>>     Extension arrays and objects can be serialized into the XML format by
>>>     considering an element containing a child or children to represent an
>>>     object, except for elements that contain only child element(s) named
>>>     'i', which are considered arrays.  For example, an alternate version
>>>     of the example above would appear in XML as:
>> This is written like guidance, but it's normative, right?

good point. what about this wording instead:

Extension arrays and objects are serialized into the XML format by 
considering an element containing a child or children to represent an 
object, except for elements that contain only child element(s) named 
'i', which are considered arrays. For example, the XML version of the 
JSON example above would appear as:

>>>     <?xml version="1.0" encoding="UTF-8"?>
>>>     <problem xmlns="urn:ietf:rfc:XXXX">
>>>       <type>http://example.com/probs/out-of-credit</type>
>>>       <title>You do not have enough credit.</title>
>>>       <detail>Your current balance is 30, but that costs 50.</detail>
>>>       <instance>
>>>         http://example.net/account/12345/msgs/abc
>>>       </instance>
>> It would be good to point out that due to the type definitions in the schema, the whitespace inside <instance> is ignorable.
> I'll leave this to Erik...

actually, i think in this case it might be less confusing to simply not 
have this extraneous whitespace in the example, so my suggestion is to 
change example to simply say:

<instance>http://example.net/account/12345/msgs/abc</instance>

thanks again for the review! cheers,

dret.

-- 
erik wilde | mailto:[e-mail]  -  tel:[phone] |
            | UC Berkeley  -  School of Information (ISchool) |
            | http://dret.net/netdret http://twitter.com/dret |