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
Comments
inline.
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.
|