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: [obix] Resolved issues post meeting - Ludo's email


I disagree.  The min, max, and units values are not present in the Contract definition.  They do not exist.  I am happy with adding language to the specification to describe that these values are implied.  Is this clarified any by the following sections?

 

bool

The bool type represents a boolean condition of either true or false. Its val attribute maps to xs:boolean defaulting to false. The literal value of a bool MUST be “true” or “false” (the literals “1” and “0” are not allowed). The Contract definition is:

<bool href="" is="obix:obj" val="false" null="false"/>

This defines an Object that can be referenced via the URI obix:bool, which extends the obix:obj type.  Its default value is false, and its null attribute is false by default.  The optional attribute range is not present in the Contract definition, which means that there is no standard range of values attached to an obix:bool by default.

Here is an example of an obix:bool which defines its range:

<bool val="true" range="#myRange">

  <list href="" is="obix:Range">

    <obj name="false" displayName="Inactive"/>

    <obj name="true" displayName="Active"/>

  </list>

</bool>

The range attribute specifies a local fragment reference to its myRange child, where the intended display names for the false and true states are listed.

 

int

The int type represents an integer number. Its val attribute maps to xs:long as a 64-bit integer with a default of 0. The Contract definition is:

<int href="" is="obix:obj" val="0" null="false"/>

This defines an Object that can be referenced via the URI obix:int, which extends the obix:obj type.  Its default value is 0, and its null attribute is false by default.  The optional attributes min, max, and unit are not present in the Contract definition, which means that no minimum, maximum, or units are attached to an obix:int by default.

An example:

<int val="52" min="0 max="100"/>

This example shows an obix:int with a value of 52.  The int may take on values between a minimum of 0 and a maximum of 100.  No units are attached to this value.

 

 

 

 

From: Bertsch, Ludo [mailto:bertsch@caba.org]
Sent: Tuesday, October 28, 2014 10:55 AM
To: Gemmill, Craig; William Cox; Obix TC List
Cc: ludob@horizontec.com; Toby Considine
Subject: RE: [obix] Resolved issues post meeting - Ludo's email

 

What I am trying to suggest in the updated Contract Definition Line 518 with min, max, and unit is to make sure it aligns with the Schema and Figure 4-1, which does list those terms.  I used "true" to indicate they exist, but realize other words might be more appropriate - like minvalue, maxvalue.  Whatever words are used, I think the terms min, max and unit should appear in the Contract Definition.

 

Another proposed Contract Definition for Line 518:

<int href="" is="obix:obj" val="0" null="false" min=minvalue max=maxvalue unit=uomvalue/>

 

 

The Schema for Int is:

<xs:complexType name="Int">
    <xs:complexContent>
        <xs:extension base="Obj">
            <xs:attribute name="min" type="xs:int"/>
            <xs:attribute name="max" type="xs:int"/>
            <xs:attribute ref="unit"/>
            <xs:attribute name="val" type="xs:int" default="0"/>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>

 

 

Figure 4-1 for Int:

+ max: int[0..1]

+ min: int[0..1]

+ unit: anyURI[0..1]

+ val: int = 0

 

 

 

Cheers,

Ludo

 

 

 


From: Gemmill, Craig [craig.gemmill@tridium.com]
Sent: Tuesday, October 28, 2014 6:39 AM
To: Bertsch, Ludo; William Cox; Obix TC List
Cc: ludob@horizontec.com; Toby Considine
Subject: RE: [obix] Resolved issues post meeting - Ludo's email

Re: references – I’m not sure what has happened with the references, these two are clearly wrong, and the next one I checked, ‘Implementation’, seems to also be wrong.  I wonder if something has gone wrong during the various reincarnations we’ve done to escape the styling and formatting problems that seem to pop up at random.

 

Actually I ended up removing Implementation.  I think it’s actually fairly clear what it is, and the explanation sort of serves to confuse the issue, because the term is used in the description of Contracts to mean an implementation of a specific Contract (as opposed to an implementation of the specification as a client or server).  I’ve gone through the rest and corrected the ones I thought were wrong.

Re: further explanations – I think what href and null mean in the definition of bool are explained within the description of the respective attributes in Sections 4.2.X, do we need to repeat ourselves here?  It seems that was the opinion of those collected last meeting, so I will try to include some useful additions in Sections 4.3.X.

 

Re: the examples in Ludo’s previous email (sent 8:02am PDT), these are not the correct usage of the attributes range, min, max, or units.  But I think we covered that in the TC call last week.  A key point that seems to have been missed is that the types bool, real, int, etc... are derived from the val type, which is in turn derived from the obj type.  So, the bool type inherits the default value from its supertype, e.g., the bool type contains a status attribute which defaults to “ok”.  There shouldn’t be a need to add the inherited attributes in, nor should we add in attributes that need not be present (like displayName – the default is not “”, but {not present}).

 

I plan to post a WD37 today.

 

Craig

 

 

 

 

 

 

 

 

From: Bertsch, Ludo [mailto:bertsch@caba.org]
Sent: Saturday, October 25, 2014 1:14 PM
To: William Cox; Gemmill, Craig; Obix TC List
Cc: ludob@horizontec.com; Toby Considine
Subject: RE: [obix] Resolved issues post meeting - Ludo's email

 

In our last conference call, the question was asked in regards to Line 512: what does is="obix:obj" mean in this case?  To me, this is an indication that some further explanation is needed.

 

Similarly:

What does href="" mean?

What does null="false" mean?

 

While I have suggested the explanation come after the Line 512, it could also be done by modifying the text before Line 512.  I think a good explanation needs to make a direct connection to the wording in Contract definition in Line 512, and should not skip key words such as obix:bool, obix:obj and null (and range which is coming).  If required to limit changes to the spec document, this level of explanation could be done to only the first couple Core Types, bool and int (line 518), plus Object (line 333).  With that, only a few new lines are needed.  I think the Core Types and Object need good explanations as they are an important foundation - and without a solid foundation, other explanations would be lacking.  

 

 

While going through the document, I noticed that in Section 1.7.1, Table 1-1: Contracts are in Section 3.6 not 3.5.  Objects are in Section 4.1 not 3.1.  These are only a couple random spots - the referencing of other sections should be checked.

 

 

Cheers,

Ludo

 


From: obix@lists.oasis-open.org [obix@lists.oasis-open.org] on behalf of Bertsch, Ludo [bertsch@caba.org]
Sent: Friday, October 24, 2014 8:02 AM
To: William Cox; Gemmill, Craig; Obix TC List
Cc: ludob@horizontec.com; Toby Considine
Subject: RE: [obix] Resolved issues post meeting - Ludo's email

Immediately after the Contract Definition for Bool (Line 512) I suggest an explanation be given of what that Contract definition means similar to what I have in my previous email.  Throughout the entire document, there is not really a good explanation of Contract definition in practice.  It makes sense to explain the Contract definition for "Bool", as it is one of the first Contract Definitions in the document (the only previous definition is "Object", which may also be suitable). That is, Line 512 (with updated Contract definition) and the new Line could be something like:

 

<bool href="" is="obix:obj" val="false" null="false" range="true"/>

The above Contract Definition defines the expected behavior and facets of the Value Object "bool" when used in OBIX, and says that: the Schema is found at "obix:Bool", properties of "Object" could be used and are found at the Schema at "obix:Obj", the default value if not specifically set is "false", the value cannot be null and a range of values are expected (e.g. pointers to strings such as "off"/"on").

 

 

Similarly, for "int" (Line 518) we could put something like (with updated Contract definition):

 

<int href="" is="obix:obj" val="0" null="false" min="true" max="true" units="true"/>

The above Contract Definition defines the expected behavior and facets of the Value Object "int" when used in OBIX, and says that the Schema is found at "obix:Int", properties of "Object" could be used and are found at the Schema at "obix:Obj", the default value if not specifically set is "0", the value cannot be null, an inclusive minimum value could be used, an inclusive maximum value could used, and unit of measure could be used.  

  

 

 

Cheers,

Ludo

 

 

 


From: obix@lists.oasis-open.org [obix@lists.oasis-open.org] on behalf of William Cox [wtcox@CoxSoftwareArchitects.com]
Sent: Thursday, October 23, 2014 10:06 AM
To: Bertsch, Ludo; Gemmill, Craig; William Cox; Obix TC List
Cc: ludob@horizontec.com; Toby Considine
Subject: [obix] Resolved issues post meeting - Ludo's email

Craig, Chris, and others -

Post-meeting note with decisions on Ludo's issues.

Thanks!

bill
--

William Cox 

Email: wtcox@CoxSoftwareArchitects.com 

Web: http://www.CoxSoftwareArchitects.com 

+1 862 485 3696 mobile

 

On 10/23/14 10:55 AM, Bertsch, Ludo wrote:

Here is my answer to your question, Bill, "what specific items are not in synch?"


For now I am focusing on one small part.  If we find an issue there, we should then check other areas.  Right now I am focused on "int" and the difference between the Schema (.xsd) and the text (pdf) - let's use WD36.


Consider you are a programmer, ready to program for OBIX.  If you want to know about what "int" means let's see what it says in the Schema:

<xs:complexType name="Int">
    <xs:complexContent>
        <xs:extension base="Obj">
            <xs:attribute name="min" type="xs:int"/>
            <xs:attribute name="max" type="xs:int"/>
            <xs:attribute ref="unit"/>
            <xs:attribute name="val" type="xs:int" default="0"/>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>

So from the Schema we can see that "Int" can have a minimum and maximum value, a unit of measure, and value with type "Int", with a default value of "0".


Let's look at "bool" in the Schema:

<xs:complexType name="Bool">
    <xs:complexContent>
        <xs:extension base="Obj">
            <xs:attribute ref="range"/>
            <xs:attribute name="val" type="xs:boolean" default="false"/>
        </xs:extension>
    </xs:complexContent>
</xs:complexType>

So, here from the Schema we can see that "Bool" has a finite value set (e.g. 0 and 1), with a value type "boolean" and with a default value of "false".  The Schema also says, that in contrast to "Int", for "Bool" we do not have a minimum or maximum value, nor a unit of measure.


However, when I go the pdf spec for "int", the Contract definition says the following (line 515, section 4.3.1.2):
<int href="" is="obix:obj" val="0" null="false"/>

Compare to 512.

bool doesn't mention range but it's an attribute. Schema doc 282 is ofr - On / Off works.
int doesn't mention min, max, unit
real is missing min, max, precision, unit

Line 512
include range in 512. 
Look in 11.2 - talk about range - example there is on/off for boolean. names are true and false, display name is on/off.

Line 518:
Similar change for Real

Line 530 and 532:
Similar change - unit, min, max - see schema line 145. Say in 530 something like "...min=minchars ... max=maxchars"
Example on 532 something like "min=0 max=12", could show conforming/non-conforming string.


All the pdf text says here is that "int" has the value type "int" and the default value is "0".  It points to obj, but does not indicate that a minimum, maximum or unit of measure of the object could be used.


The pdf spec for "bool" Contract definition says the following (line 512, section 4.3.1.1):
<bool href="" is="obix:obj" val="false" null="false"/>

All the pdf text says here is that "bool" has the value type "bool" and the default value is "false".  This also points to obj like "int" did, but in this case, minimum, maximum or unit of measure would not be appropriate.

So how is one supposed to know without a lot of checking different sections, that "bool" does not have minimum, maximum and unit of measure?  Just as important, how does one know that "int" could have minimum, maximum and unit of measure?


For a programmer, one would expect a reasonable connection between the spec text and the Schema, and they would have similar meanings - at least to the degree that is reasonable to do so.   I think for these examples, the Schema is much more precise, yet only takes one line to explain.

So I suggest text section for "int" (section 4.3.1.2) preferably in the Contract Definition, but otherwise in the text, should include that minimum, maximum and unit of measure could be used.   This way, the definition of "int" is more precise, and aligns with the Schema.


Other sections may have similar issues.



Cheers,
Ludo


From: obix@lists.oasis-open.org [obix@lists.oasis-open.org] on behalf of Gemmill, Craig [craig.gemmill@tridium.com]
Sent: Thursday, October 23, 2014 5:03 AM
To: William Cox; Obix TC List
Cc: ludob@horizontec.com; Toby Considine
Subject: RE: [obix] OBIX Deadline today - unresolved issues

Comments inline.

 

From: William Cox [mailto:wtcox@CoxSoftwareArchitects.com]
Sent: Wednesday, October 22, 2014 8:09 PM
To: Obix TC List
Cc: ludob@horizontec.com; Gemmill, Craig; Toby Considine
Subject: Re: [obix] OBIX Deadline today - unresolved issues

 

 


My emails on 21 October discussed issues remaining with the schema and the spec, and came out of a detailed phone call with Toby.

BTW Toby had a hardware failure of some kind Tuesday, and I've not heard from him since.

These issues are still open, and affect both the specification (1.1) and the schema. I've seen nothing on the list regarding this; perhaps I should be more inflammatory to get comments. ;-)

The issues are

  • The Integral types and inconsistentcy between spec and schema (21 Oct, 5:20pm ET) with diagrams

The Schema is the final word once we’ve released it; however, the spec is the correct value for what we want.  It should be a 64-bit long.  So I think the schema should be changed to represent that.

  • Obj is the complexType, but the spec says "Object" everywhere.

Obj is just the abbreviated notation of “Object”, because it is less jarring to the reader to see the known word Object, instead of the non-word Obj, in the prose.  The XML representation is ‘obj’, which is just an abbreviation to save space, since it’s used frequently.  If you want to change the schema to say ‘Object’ instead of ‘Obj’, that’s fine, but the XML representation should stay ‘obj’, and the spec should stay “Object” for readability.  If a sentence is needed somewhere up in Section 3 or 4 to say that “Object” == <obj>, that’s fine.

  • Minor issue on cardinality of "is" attrribute to "Obj"

is = 0 .. N,   not 0 .. 1

  • Updated UML to reflect the xs:any (separate email just sent)

 

  • Annotate the xs:any use in the specification.

You mean in Section 4 or something?


Ludo --

Which specific items are not in synch?

I think that the spec should say something about each substantive thing expressed in the schema .

Thanks!

bill
--

William Cox 

Email: wtcox@CoxSoftwareArchitects.com 

Web: http://www.CoxSoftwareArchitects.com 

+1 862 485 3696 mobile

 

 

On 10/22/14 9:27 AM, Ludo Bertsch wrote:

As a final check, I did some quick comparisons of the Schema and the text, and found they did not agree; and thus prompted my comments last week.  It looks like Bill and you folks are in the midst of solving the issues.  Since the Schema has the ultimate priority, we need to make sure that the Schema is right.

Question: does every term in the Schema need to have an explanation in the text?  For example, "int" has "unit" in the Schema, but the text does not mention that?  What does "unit" mean for "int"? 


Cheers,
Ludo


On 10/21/2014 6:29 PM, Gemmill, Craig wrote:

Toby-

 

I didn’t see any questions from you, although there seems to be some from either Ludo or Bill.

 

I don’t think any of these require changes to the spec.  I will address what questions I see here, please let me know if I’m missing something:

·         The obix:int type defined in 4.3.1.2 maps to an xs:long.  The schema and the figure both need to reflect this.

·         The root abstraction is “Object”.  This is abbreviated in encoding as “obj”.  I’m not sure how the text on 324-325 is incorrect, because it uses the term Object consistently.  An Object can implement zero or more Contracts (not just zero or one).  Assuming the request was to make line 344 (and not 324) singular, I disagree.  An Object must be allowed to implement any number of Contracts.  What about an alarmable sensor point, that must implement obix:Point obix:Alarm obix:StatefulAlarm?

·         A contract is NOT just an alias for anyURI, I don’t think.  Maybe only in the XSD, although I’m not sure I agree with even that restricted statement.  I’m not a schema guru, so I could be wrong, it just seems like an oversimplification to me.

 

So, these are the only questions I’ve seen, and I don’t see any changes necessary yet to WD36.  If you think we need something new, let me know, or if there is a new XSD we can include that.

 

Craig

 

 

From: Toby Considine [mailto:tobyconsidine@gmail.com] On Behalf Of Toby Considine
Sent: Tuesday, October 21, 2014 1:15 PM
To: Gemmill, Craig
Subject: RE: [obix] OBIX Deadline today

 

Did you see my ?s on Schema?

 

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: Tuesday, October 21, 2014 1:02 PM
To: Toby Considine
Subject: RE: [obix] OBIX Deadline today

 

Is there anything to do?  I have not seen any comments from anyone that would require any further effort.  Let me know if you need me to provide something else before the vote.  I’m in meetings all day today, tomorrow, and Thursday (although I plan to try and step out for the TC meeting).

 

 

From: obix@lists.oasis-open.org [mailto:obix@lists.oasis-open.org] On Behalf Of Toby Considine
Sent: Tuesday, October 21, 2014 10:15 AM
To: obix@lists.oasis-open.org
Subject: [obix] OBIX Deadline today

 

Remember that we need complete packages for all OBIX specifications today.

 

A complete package is a Zip archive including:

 

1)      Editable form

2)      Normative form (PDF w/ Line Numbers)

3)      Any Artifacts (XSD, WSDL as appropriate or needed)

 

We vote on the entire archive.

 

We also need to prepare a document showing differences between this version and the one used for the last Public Review. Drop me a line if you need assistance preparing this.

 

We also need an issue resolution report (from Jira) for all issues. If you have any Jira issues make sure that they are up-to-date. If you must prioritize, I’d rather get the packages today, and Jira updated tomorrow. I can then prepare resolution reports from Jira.

 

We hope to vote the complete set out for public review this week, then turn to the white paper.

 

tc

 


"Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it."

- Brian W. Kernighan


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

 

 

-- 
Ludo Bertsch, P.Eng.
Horizon Technologies
www.horizontec.com
ludob@horizontec.com
(250) 592-1488
 
This email may contain confidential information and is directed at the
recipient only and is not to be disclosed to anyone else without
permission.  If you have received this email in error, please
inform us and delete this email and attachments. Please let us
know if you no longer wish to receive emails from us.               

 

 



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