OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

obix message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: RE: Examples versus Contract Definitions


I would say the most important consideration is to "make it clear".


Through the previous exchanges on this topic, I thought that the difference between Contract Definitions and Examples were being clarified, until the mention was made about Section 1.6.  I believe to say that Contract Definitions are "really just an Example . . . ." only adds to confusion, especially without further discussion.  

My view is that Contract Definitions in Section 1.6 is dealing with the possibility that the Schema and text do not agree, and to indicate that the Schema takes priority.  It is saying that the Contract Definitions are "non-normative" and that the Schema supersedes.  I don't believe the intent is to say that Contract Definitions are Examples, at least how I am envisioning Examples.  In my view, the meanings behind Contract Definitions and Examples are different and still need to be clarified throughout the document.  I think the statement in Lines 344-345  "the formal Schema supersedes the examples defined here" only adds confusion.  I suggest it should say: "the formal Schema supersedes the examples and contract definitions defined here".

Let's look at Section 4.3.1.2 int. 
<int href="" is="obix:obj" val="0" null="false"/>
Line 755 (WD34) shows a Contract Definition, which defines how "int" is to behave.  To me, it is not an Example, it is a definition.  I believe an Example is code that one would reasonably expect to see in a product.  One would not expect to see Line 755 in an actual product.

The next lines then include an Example which contrasts to the Contract Definition. 
<int val="52"/>
One would expect to see Line 757 in an actual product, so it is an Example and not a Contract Definition.


By not differentiating between Examples and Contract Definitions in the specification, the use of Contract Definitions (which is a challenge to grasp in the first place) becomes even more confusing.  Lines 755 and 757 have different meanings behind them and I believe still need to be indicated differently.  While in this case it is clear because the Contract Definition and Example directly follow each other, there are cases where an Example or a Contract Definition appear on their own with no mention of either, and it can lead to confusion.   

Take a look at Section 4.2.7.7 range.  There is no mention throughout Section 4.2.7.7 whether Line 674 is an Example or a Contract Definition. It is not clear whether Line 674 is showing an example of what would expect in a product, or whether it is defining what "range" means, especially when the same format has been used as Examples and Contract Definitions.


One simple way to deal with this is might be to remove the grayed boxes from the Contract Definitions if there are limited formats available.  

Also, one should ensure that each Contract Definition is introduced accordingly.

It may also be helpful to define the term Examples.


In my view, to say that the grayed areas are Examples (Lines 340 to 342) and then use it for both Examples and Contract Definitions does not help with clarity and adds to confusion.


Ludo



From: Considine, Toby [Toby.Considine@unc.edu]
Sent: Monday, October 13, 2014 10:08 AM
To: Gemmill, Craig; Toby Considine; Bertsch, Ludo; obix@lists.oasis-open.org
Subject: RE: Examples versus Contract Definitions

Then keep it simple…

 

 


“The single biggest problem in communication is the illusion that it has taken place.”

– George Bernard Shaw.


Toby Considine
TC9, Inc

OASIS TC Chair: oBIX & WS-Calendar

OASIS TC Editor: EMIX, Energy Interoperation

SGIP Smart Grid Architecture Committee

  

Email: Toby.Considine@gmail.com
Phone: (919)619-2104

http://www.tcnine.com
blog: http://www.NewDaedalus.com

 

From: obix@lists.oasis-open.org [mailto:obix@lists.oasis-open.org] On Behalf Of Gemmill, Craig
Sent: Monday, October 13, 2014 12:48 PM
To: Toby Considine; 'Bertsch, Ludo'; obix@lists.oasis-open.org
Subject: [obix] RE: Examples versus Contract Definitions

 

By “all examples”, you mean “all text in the ‘Example’ style”?  So, then I think I should go through and for all the cases where I’m saying “The Contract Definition is:”, I’ll need to put a note that it is normative?  Do you think the phrase “The Contract definition is” is not sufficient to identify ‘normative-ness’?

 

It seems like we could address this in a single fell swoop by modifying Section 1.6 to say that

 

OK, after reading Section 1.6, it seems that even the Contract Definitions are intended to be non-normative (surprise!), as they are really just an Example instance of an object from the Schema definition.  My earlier statements had assumed the contract definitions were normative, which is apparently incorrect.  So, I’m seeing less of a problem with having both of these be in the same style, as they are both non-normative.  It does sort of elevate the need for the white paper about “Obix by Example”.

 

I could put some note around the contract definitions to mark them as normative, but I think that would be unnecessarily confusing.

 

 

 

From: Toby Considine [mailto:tobyconsidine@gmail.com] On Behalf Of Toby Considine
Sent: Monday, October 13, 2014 12:32 PM
To: Gemmill, Craig; 'Bertsch, Ludo'; obix@lists.oasis-open.org
Subject: RE: Examples versus Contract Definitions

 

Well, you can check out the “code” style – but I think that is likely to be too subtle.

 

My take:

 

All examples are non-normative unless otherwise marked.

 

And mark the ones you want to be normative.

 

tc

 


"There are seldom good technological solutions to behavioral problems "

-- Ed Crowley


Toby Considine
TC9, Inc

OASIS TC Chair: oBIX & WS-Calendar

OASIS TC Editor: EMIX, Energy Interoperation

SGIP Smart Grid Architecture Committee

  

Email: Toby.Considine@gmail.com
Phone: (919)619-2104

http://www.tcnine.com
blog: http://www.NewDaedalus.com

 

From: Gemmill, Craig [mailto:craig.gemmill@tridium.com]
Sent: Monday, October 13, 2014 12:05 PM
To: Bertsch, Ludo; Toby.Considine@gmail.com; obix@lists.oasis-open.org
Subject: RE: Examples versus Contract Definitions

 

Toby, what do you think?

 

I see his point, that there are some cases which are truly an example of usage of the rule, and not normative (such as the Brady Bunch references).  But others are intended to be fully normative like the contract definitions.  What is the typical committee behavior in this case?  Both of these are using the defined style named “XML”.  You can see it clearly in 4.3.1.X, where we give the (normative) contract definition, followed a line later by a (presumably non-normative) example usage.

 

There is a style called “Code” in the document template that looks similar.  I could change one usage or the other to use the “Code” style.  I’m happy to add a new style, with a different background color or something, but I want to stick within the OASIS guidelines.

 

Or would this just be better as a PR comment that we can address then?

 

Thanks

Craig

 

 

From: obix@lists.oasis-open.org [mailto:obix@lists.oasis-open.org] On Behalf Of Bertsch, Ludo
Sent: Thursday, October 09, 2014 6:10 PM
To: Toby.Considine@gmail.com; obix@lists.oasis-open.org
Subject: [obix] Examples versus Contract Definitions

 

Re: WD34 clean document.

 

Section 1.6, Lines 340-341 indicate that grayed boxes such as on Line 342 are to be used to show "Examples".

 

Following that, the next three grayed boxes are in fact Examples: Lines 407-411, Lines 435-450, and Lines 476-491.

 

However, the grayed box in Section 4.2, Line 580 is not an Example but is a Contract Definition.

 

Following that, some of the grayed boxes are Examples, and some are Contract Definitions.

 

Using the same type of grayed box for both Examples and Contract Definitions can lead to a lack of clarity and is especially confusing when grayed boxes were noted to be used for Examples, but was not noted for Contract Definitions.

 

It is suggested that a different type of box be used for Examples versus Contract Definitions to clarify the difference between the two, and to aid new readers to understand the difference.  This will help to identify Examples (versus Contract Definitions) when not specially mentioned, but implied, such as in Section 4.2.7.6, Line 666.  This will also help with the understanding of the Lobby Contract Definition that we have discussed in Section 5.1, Lines 886-893.

 

Cheers,

Ludo

 

 

 

 



[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]