[Nmc-wg] Result Code Redux - One last issue

Jason Zurawski zurawski at internet2.edu
Thu Sep 29 06:44:10 CDT 2011 

Hi Michael;

Thank you for providing the document.  I don't agree at all with your 
proposal, and feel that the original is much better for our needs.  I 
prefer to keep the status codes the same as the namespaces (using the 
date as a version string at the end) for all the same reasons we have 
constructed the namespaces in this pattern.  You can read this 
justification in the NM document.

Its not for me to judge which is best though, I will send out a doodle 
vote poll later today so we can pick one, and move on with the document.

Regarding your observation that we went with '2.0' for NMWG - this was 
chosen in 2004 before we had a lot of experience in using namespaces and 
the complications we had in establishing new versions.  In 2007 we 
realized that appending a date was much easier, particularly when the 
schema was changing frequently.  I would prefer to use dates, and I 
would prefer they stay at the end of the string to foster extensibility 
and short/circuit identification of a general concept.

-jason

On 9/28/11 7:08 AM, thus spake Michael Bischoff:
> Alright jason, for review:
>
> Also updated the examples. (ps it's interesting that we went with 2.0 for nmwg)
>
> * kept the date as version. (didn't feel strongly about changing this
> also since it is now easy to detect the version we can opt to not
> redefine unchanged parts in future versions which probably removes any
> burden that changing it aims to solve)
> * moved the version to the left.
> * updated text
>
> to elaborate on the last email:
> "Client applications should be advised that parsing an error code may
> result in seeing this ‘unexpected’ last part, and could terminate
> parsing up to this point to avoid a complete failure."  If the version
> is at the end it also get's dropped.
>
> Michael
>
> On Wed, Sep 28, 2011 at 12:01 PM, Jason Zurawski<zurawski at internet2.edu>  wrote:
>> Hi Michael;
>>
>> If you feel strongly about this proposal, I will ask you to prepare a formal document so we can review as a group.  Please do so by Friday of next week however, as we cannot continue to debate this issue.
>>
>> Thanks;
>>
>> -jason
>>
>> ----- Original Message -----
>> From: Michael Bischoff<Michael.bischoff at controplex.nl>
>> To: zurawski at internet2.edu
>> Cc: Roman Łapacz<romradz at man.poznan.pl>, nmc-wg at ogf.org
>> Sent: Wed, 28 Sep 2011 05:18:08 -0400 (EDT)
>> Subject: Re: [Nmc-wg] Result Code Redux - One last issue
>>
>> Hello all,
>>
>> I wanted to post this earlier but didn't got around to it,
>>
>> Perhaps something to consider: having the version at the end makes it
>> more difficult to change the structure and to support multiply
>> versions in one client/service, especially if you don't force it to be
>> strictly a last single part:
>>
>>   "http://schemas.ogf.org/nmc/status/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/"<VERSION>"
>>
>> and
>>
>> 201109/beta ->  201109.beta or 201109-beta (mandate that the version
>> bit will not consist out of '/' I would also recommend standardizing
>> the separation sign for this)
>> (ps don't think we need a day in there unless you want to make
>> multiply updates in a single month - which seems unlikely.)
>>
>>  From a easy-to-parse point of view:
>> We need the version first to establish if we can interpret the status
>> regardless if the status we encounter is known. As such the version is
>> a more significant bit then what is currently left to it, as such I
>> would not put it at the end. Also client programmers might be tempted
>> to ignore the version bit given the version is at the end or least
>> significant spot, esp since we allow them to already ignore certain
>> preceding parts. Ignoring the version will lead to poorly functioning
>> clients. Moving the version to the left doesn't prevent this but does
>> require them to actively ignore it while at the same time doesn't
>> force them to do more work to ignore it.
>>
>> "http://schemas.ogf.org/nmc/status/"<VERSION>"/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/
>> (or do we tie things to a version of nmc as a whole:
>> "http://schemas.ogf.org/nmc/"<VERSION>"/status/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/
>> ?
>>
>> Also dates are good and bad - for example with dates you can't declare
>> forwards compatibility - 1.0 1.1, 1.2 - structure stayed the same all
>> messages in 1.0 are available in 1.1 1.2. So if you encounter a known
>> status and only the last part has changed it's safe to interpret. 1.0
>> ->  2.0 semantics and or structure has changed. Then again - forcing
>> clients to update might not be a bad thing at all.
>>
>> Best regards,
>>
>> Michael
>>
>> On Wed, Sep 28, 2011 at 10:20 AM, Jason Zurawski<zurawski at internet2.edu>  wrote:
>>> Hi Roman;
>>>
>>> Thanks for doing this, I will try to send an updated version by the end
>>> of the week, and include this in the formal document.  Thanks;
>>>
>>> -jason
>>>
>>> On 9/27/11 12:32 PM, thus spake Roman Łapacz:
>>>> W dniu 2011-09-23 14:22, Jason Zurawski pisze:
>>>>> Hi Roman;
>>>>>
>>>>> I think this is a good idea, would you be able to make the changes to
>>>>> the document and sent it back to the list?
>>>>
>>>> Attached (needs polishing).
>>>>
>>>> Cheers,
>>>> Roman
>>>>
>>>>>
>>>>> Thanks;
>>>>>
>>>>> -jason
>>>>>
>>>>> On 9/23/11 12:29 PM, thus spake Roman Łapacz:
>>>>>> W dniu 2011-09-23 11:32, Jason Zurawski pisze:
>>>>>>> Gang;
>>>>>>
>>>>>> Hi,
>>>>>>
>>>>>>>
>>>>>>> In typing up the final version of the status codes into the document,
>>>>>>> I hit upon a snag. Here is an example of what was proposed in the
>>>>>>> prior mail:
>>>>>>>
>>>>>>> http://schemas.ogf.org/nmc/2011/09/status/informational/protocol
>>>>>>> version/
>>>>>>>
>>>>>>> This goes against our typical method of constructing namespaces. I
>>>>>>> would suggest we do this instead:
>>>>>>>
>>>>>>> http://schemas.ogf.org/nmc/status/informational/protocol
>>>>>>> version/2011/09/
>>>>>>>
>>>>>>> Or even better using:
>>>>>>>
>>>>>>> 201109
>>>>>>>
>>>>>>> or
>>>>>>>
>>>>>>> 20110923
>>>>>>
>>>>>> Right. Good you spotted this. I prefer to have just one field for
>>>>>> version number (201109 or 20110923) with an exception for early testing
>>>>>> versions (201109/beta or 20110923/beta).
>>>>>>
>>>>>>>
>>>>>>> As the 'version' string. I am attaching an updated document going
>>>>>>> with the first suggestion, I prefer the last best of all. Other
>>>>>>> opinions?
>>>>>>
>>>>>> What do you think to replace the code hierarchy with the pattern in the
>>>>>> beginning of section 2. Example:
>>>>>>
>>>>>> --example---------------------
>>>>>>
>>>>>> "http://schemas.ogf.org/nmc/status/"<STATUS_CATEGORY>"/"<STATUS_NAME>"/"<VERSION>
>>>>>>
>>>>>>
>>>>>> <STATUS_CATEGORY>  may have the following text values:
>>>>>> - informational
>>>>>> - successful
>>>>>> - redirection
>>>>>> - clienterror
>>>>>> - servererror
>>>>>>
>>>>>> <STATUS_NAME>  depends on the status category and may have the following
>>>>>> text values:
>>>>>> - informational category
>>>>>> -- protocol version
>>>>>> -- data limitation
>>>>>> -- service_contact
>>>>>> - client error category
>>>>>> -- bad_message
>>>>>> -- bad request
>>>>>> -- authentication_failed
>>>>>> -- unauthorized
>>>>>> -- message not allowed
>>>>>> -- event_type_not_allowed
>>>>>> -- event_type_not_allowed
>>>>>> -- request_too_large
>>>>>> -- request_timeout
>>>>>> -- protocol_not_allowed
>>>>>> -- chaining_not_understood
>>>>>> - servererror category
>>>>>> -- data_fetch_error
>>>>>> -- too_busy
>>>>>> -- administrative_down
>>>>>> Two categories, successful and redirection, do not need to have
>>>>>> certain status names.
>>>>>>
>>>>>> VERSION is a string presenting information about the version of
>>>>>> protocol, e.g. 201109 or 20110925. In case of early testing version an
>>>>>> optional part after "/" may be added (e.g. 201109/beta or
>>>>>> 20110925/beta) .
>>>>>>
>>>>>> -- end---------------------
>>>>>>
>>>>>> I'm thinking about such update because version numbers don't look good
>>>>>> in the structure. They are not generic. The use of pattern solves this
>>>>>> issue. What do you think? (of course a short description below the
>>>>>> pattern in my example may be done much better; I just wanted to present
>>>>>> my idea).
>>>>>>
>>>>>> Cheers,
>>>>>> Roman
>>>>>>
>>>>>>>
>>>>>>> Thanks;
>>>>>>>
>>>>>>> -jason

More information about the Nmc-wg mailing list