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"/>
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
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).
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
--
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.