[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [obix] oBIX Artifact Naming and Titling...Titles for Encodings
|
I like the inclusion of Common in encodings. It better describes the current document and, as you say, it gives us greater flexibility in the future. Markus: Could you please change the Title of the Encodings document to: Encodings for OBIX: Common Encodings Version 1.0 I can imagine conformance statements such as “Implementations claiming conformance must specify which of the “Encodings for oBIX” specification that they conform
to.” tc "When one door closes, another opens; but we often look so long and so regretfully upon the closed door that we do not see the one which has opened for us."
-- Alexander Graham Bell
From: Paul Knight [mailto:paul.knight@oasis-open.org]
Hi Toby and all, Thanks for asking. It's certainly best to think about these things before publication! As of now, I note that three templates for OBIX documents have been requested and provided in February 2013. The titles were: - Bindings for OBIX: REST Bindings Version 1.0 - Bindings for OBIX: SOAP Bindings Version 1.0 - Encodings for OBIX Version 1.0 The first two titles are quite flexible, with respect to supporting the case your mentioned, "We anticipate that at a future time, a new encodings document could be made, or
a new binding, without creating a [oBIX] 1.2." that is, the Version can be incremented in the title without regard to the associated OBIX/oBIX versioning. I would suggest that the text of the Abstract and Introduction sections of each document should
clearly identify the OBIX/oBIX versions supported. The "Encodings" title is a bit more problematic, since the proximity of "OBIX" and "Version" can cause some confusion. The XACML TC dealt with this by using the title "REST Profile of XACML v3.0 Version 1.0". However, this approach ties
the specification to a particular version of the core specification. A simple solution might be to slightly revise the title to be: OBIX Encodings Version 1.0. This allows the same flexibility as the first two titles. If you anticipate breaking out various encodings over time into separate specifications, it might be better to start with something like: Encodings for OBIX: Common Encodings Version 1.0, which might over time be broken out as: Encodings for OBIX: XML Encodings Version 1.0 Encodings for OBIX: JSON Encodings Version 1.0, etc. Any of these titles also allow for the introduction of specific Version numbers in the titles in association with OBIX/oBIX, as well. In that case, you should use the lower-case "v" immediately followed by the number, as in the XACML example. (e.g., Bindings for OBIX v1.2: REST Bindings Version 1.0). I would not advise a construction like "v1.1 and above" in a title. It's much better to use the text to communicate that level of detail. I should also note that the use of commas in a title is strongly discouraged, and is definitely not allowed as a separator before "Version 1.0". (as in your suggestions) Now, if you are still reading, I have some items to bring to your attention before we get to publication: - I note that a working draft of OBIX Version 1.1 is under construction. I would urge you to request a current template for this document, as a glance at its format (in wd08) shows that it needs updating, despite manual updating efforts
noted in the revision notes for wd07. In particular, MS-Word paragraph styles have changed in the templates over time, and it's clear that the document is using some older styles. Not too surprising, since it was initiated in 2003, apparently. - I also note that the templates requested in February specified the use of "OBIX" in the title, while various references (e.g., the Normative References in wd08 which I inspected) use "oBIX" in referring to those documents, at the same
time as the title of wd08 uses "OBIX". You've got to choose one and stick with it! I followed the earlier pattern of "OBIX" for the v2.0 template I produced earlier today, although "oBIX" was requested there. - for the document file names and URIs, the currently-planned names are: These file names do not need to follow the capitalization pattern of the titles (OBIX or oBIX). Since the handling of file names is case-sensitive, it's quite important to keep the naming regular. I would highly recommend using all lower-case
file names. For those times when they are manually typed, it simplifies things considerably, and I think it has a neater appearance. However, we can support whatever the TC agrees for file names. Please make a specific choice for these file names, as well
as for the titles. Enough for now... please feel free to ask for clarification, support, etc. Best regards, Paul On Thu, Apr 18, 2013 at 1:07 PM, Considine, Toby <Toby.Considine@unc.edu> wrote: Advice needed, requested after considerable discussion in oBIX TC. (This might be a Paul Knight question) oBIX 1.0 is an omnibus specification. In 1.1 we are breaking out two bindings, (SOAP and REST), and Encodings (XML, JSON, COAP, et al.) We anticipate that a Conforming 1.1 Server
MUST specify which Bindings, Encodings it supports. We anticipate that at a future time, a new encodings document could be made, or a new binding, without creating a 1.2. Conversely, we can imagine oBIX 1.2 coming out and referencing the Binding/Encoding documents
we are working on today. As a matter of work process, the current WDs of each specification are essentially stripped out of the old 1.0. Each spec is currently being modified as needed. We anticipate releasing
a package of 4 specifications (oBIX 1.1, SOAP Binding for oBIX, REST Binding for oBIX, Encodings for oBIX) in the same public review. There was a spirited discussion today about avoiding confusion. Should they all be 1.1 of the Spec, because they all existed formerly as part of 1.0? Should they have longer titles,
i.e., ·
“SOAP Bindings for oBIX 1.1 and above, v1.0” ·
“SOAP Bindings for oBIX 1.1, v1.0” Of course, the answer could also be ·
“SOAP Bindings for oBIX 1.1 and above, v1.1” ·
“SOAP Bindings for oBIX 1.1, v1.1” With each document noting that the original material was all included in 1.0. We are looking for advice on how to avoid as much confusion as possible while still allowing for flexibility going forward. Thanks tc "You can cut all the flowers but you cannot keep spring from coming."
-Pablo Neruda
-- |
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]