OBIX v1.0 Comments

[cisi@ix.netcom.com]

4.16.8 status

Comment: If we define two alarm objects, alarm and ack, each with two states,

there are four alarm states:

1. no_alarm and no_ack.

2. alarm and no_ack. normally occurs between the alarm_timestamp and the

    ack_timestamp.

3. alarm and ack.

4. no_alarm and ack.

Usually an alarm system will reset ack when the alarm transitions to no_alarm.

So, alarm state    4 will not be allowed to exist.

Adding a temporal dimension, adds a fifth state.

5. no_alarm and no_ack for a previous alarm



Actually, renaming the parent alarm object annunciator would help me. Then

<obj name="annunciator"> 

    <bool name="alarm" />

    <bool name="ack" />

</obj>

Then there are five states of annunciator.

1. clear

2. unackedAlarm

3. ackalarm

4. noname since system disallows.

5. unacked    


15 Alarming



Suggest alarmTimestamp be mentioned in 2. Alarm Generation.



Re "these alarms merely represent event": This confuses me.

Suggest this be clarified to show that an event is not a subset of alarm

but a separate and distinct object.



15.1.2 

As suggested above for 4.16.8, there are five states of annunciator.

1. clear

2. unackedAlarm

3. ackalarm

4. noname since system disallows.

5. unacked



normalTimestamp and alarmTimestamp are children of alarm

ackTimestamp is a child of ack

All three timestamps are grandchildren of annunciator.



15.2.2 StatefulAlarm

Per 15. "an alarm indicates a condition which requires notification of either a user

or another application" I am having trouble coming up with an example of an alarm

which does not transition back to normal.
The specification is very well done. Obviously, many person-hours and a lot of
thought went into this project.

My comments are my thinking out loud (on the keyboard), a normal process for
me when I am trying to learn something. I hope my ramblings will be useful
to someone. I would be glad to clarify anything either in print or on the phone.

My comments fall into one of two categories, plain comments and rewordings.
The rewordings are the result of my attempt to reach an understanding of the
content. I have included my rewordings in the hopes that they may help others.
The word Rewording: appears as a label at the start of each rewording.
The word Comment: appears as a label at the start of each comment
where necessary to separate a rewording from a comment.

2   Quick Start
Rewording: ... -the staid thermostat. Lets assume we have a simple thermostat.
In oBIX XLM, the thermostat object is represented by
	<obj href="http://myhome/thermostat";>
	</obj>
If the thermostat includes a temperature sensor which reports the current space
temperature, a temperature setpoint that stores the desired temperature, and
a control output that indicates when the thermostat is calling for a furnace to
be on, these three objects are represented by the following elements:
	<real name="spaceTemp" val="67.2"/>
	<real name="setpoint" val="72.0"/>
	<bool name="furnaceOn" val="true"/>
The useful information for these objects includes not only the object
identification, the name or the href, but also a value.
Therefore, these elements are value elements and include the val attribute.
To be meaningful, a value element must include a statement about the type of data,
real for the two floating point temperature values and bool for the boolean value
of the furnace state. 
Since these three objects are child (sub) objects of the thermostat object,
the parent/child relationship is represented by including the child elements
within the parent element as follows: 
	<obj href="http://myhome/thermostat";>
		<real name="spaceTemp" val="67.2"/>
		<real name="setpoint" val="72.0"/>
		<bool name="furnaceOn" val="true"/>
	</obj>
	
Since in this example the thermostat is the most basic object,
it is the root object.
If the thermostat were controlling the temperature in my home and
if the space also included a humidistat, the root object would be my home.
In oBIX XLM, the my_home object is represented by
	<obj href="http://myhome";>
	</obj>
Now, the thermostat becomes a child element along with brother humidistat
which are represented by: 
	<obj href="http://myhome";>
		<obj href="http://myhome/thermostat";>
			<real name="spaceTemp" val="67.2"/>
			<real name="setpoint" val="72.0"/>
			<bool name="furnaceOn" val="true"/>
		</obj>
		<obj href="http://myhome/humidistat";>
			<real name="spaceHumidity" val="51.2"/>
			<real name="setpoint" val="55.0"/>
			<bool name="dehumidifierOn" val="false"/>
		</obj>
	</obj>

Adding a units attribute to a temperature value element increases the meaning of
the information, for example:	
<real name="spaceTemp" val="67.2" units="obix:units/fahrenheit"/>
helps explain what 67.2	means.
Adding a status attribute to a temperature value element helps, for example:
<real name="spaceTemp" val="-412.0" units="obix:units/fahrenheit" status="fault"/>		
helps explain that the unusual temperature represents an alarm condition.
The units attribute and the status attribute belong to a class of attributes
called facets. 

Comment: At this point, I am confused by the example of contracts.
To some extent -412degF is an obvious fault. But the status attribute does avoid
any ambiguity. However, I have not imagined a circumstance wherein anyone would
not recognize a spaceTemp as a point. In other words, a different contract example
would be better in the Quick Start.

3.1 Object Model

Rewording: All information ......

Value elements represent objects for which a value enhances the meaning of the
object. For example, the space temperature or the furnace state.

Their are 7 value objects, which represent a piece of variable information:
	bool: ....
	.
	.
	reltime: ....
and 6 special objects which represent relatively fixed values
	uri: ....	
	list: stores a list of objects
	op: stores an operation or sequence to be performed
	feed: stores a stream of events
	ref: stores a reference to another object
	err: stores an error indicator

4    Object Model

The organization of this section confuses me. 
The illustration includes the attribute "val". I would prefer to have this block
labeled "value objects"

I would prefer an organization which would clearly indicate what is an object
and what is an attribute of an object, such as:

Rewording: Suggested reorganization
4	Object Model

4.1	Objects

4.1.1 obj
.
.
.
4.1.14 feed

4.2 Attributes of objects

4.2.1 Null

4.2.2 Facets
end of rewording

4.16 Facets
Comment:
The examples for displayName, display, and writable appear to be examples of
attributes and they include a name attribute to link the facet to a specific object.
The examples for min, max, precision, range, status, and unit appear to be examples
of attributes. But, they do not include a name attribute to link the facet to a
specific object. For example, 4.16.9 unit:
<real unit="obix:units/fahrenheit" val="67.2"/>
Elements representing value objects use the type declaration instead of obj.
But, don't we need some way to identify what is 67.2degF? In our simple thermostat,
it could be either the current space temp or the setpoint.

4.16.8 status
Comment: If we define two alarm objects, alarm and ack, each with two states,
there are four alarm states:
1. no_alarm and no_ack.
2. alarm and no_ack. normally occurs between the alarm_timestamp and the
	ack_timestamp.
3. alarm and ack.
4. no_alarm and ack.
Usually an alarm system will reset ack when the alarm transitions to no_alarm.
So, alarm state	4 will not be allowed to exist.
Adding a temporal dimension, adds a fifth state.
5. no_alarm and no_ack for a previous alarm

Actually, renaming the parent alarm object annunciator would help me. Then
<obj name="annunciator"> 
	<bool name="alarm" />
	<bool name="ack" />
</obj>
Then there are five states of annunciator.
1. clear
2. unackedAlarm
3. ackalarm
4. noname since system disallows.
5. unacked		
	
5 Naming.

What is camel case?

5.1 Why discourage the use of name within the root object. Is there any reason,
other than social engineering, for this discouragement? 

5.2 I am struggling with "there may not be a root URI". I would have thought
there is always a root for any object.

5.3 Some examples. I am not familiar with the meaning of + or R as used here.

5.4 I do not understand the need for the second paragraph: "In the example above
the object with an href of "onOff" is both the target of the fragment URI, but
also has the absolute URI "http://server/whatever/onOff"; ". 
Isn't this obvious since the object with an href of "onOff" is the child of
the object with with an href of http://server/whatever/ ?
Please include an example of "an object that was the target of a fragment URI
within the document, but could not be directly addressed using an absolute URI".

6 Contracts

Contracts are special but not because other objects reference it as do other
objects's and other attributes.

Does "as a "template object"" add any meaning to the sentence?

6.3 is Attribute
Rewording:
The is attribute is used to specify a contract required for an object.

If the object is a list object or a feed object, then a contract is specified using
the of attribute.

An object can override (by name) an object specified in one of its contracts.

Comment: (an example would help)
What is a respective primitive contract? Please avoid reference to implied
contracts.

6.4 Contract Inheritance

Re sentence:
"Usually the implicit contract is documented using natural language prose.
It isn't mathematical, but rather subject to human interpretation."
And later "These fuzzy concepts...".
Comment: 
But the task of the designer is to make the language as explicit and unfuzzy
as possible in order to limit the chances of misinterpretation.
I am worried that these words will bias the understanding of implicit.
My dictionary includes "suggested or to be understood though not plainly
expressed" as a definition of implicit. In a control/monitoring environment,
the existance of any contracts that are "suggested or to be understood though not
plainly expressed" are a recipe for problems.

Re sentence:
"An object shouldn't put obix:Alarm in its contract list unless it really
represents an alarm event."
Comment: Is this type of statement necessary? If so, should the following
be included: Do not label a point as a temperature unless it really represents
a temperature.

Re sentence:
"A contract's named children objects are automatically applied to
implementations."  ..." If the implementation omits the child, then it is
assumed to default to the contract's value(s)."
Comment: Add sentence: If the implementation declares
the child (by name), then it will use the child's value(s) unless the
implementation overrides some or all of the child's attributes.

6.5 Override Rules.

Suggest you change second sentence to:
Rewording: Implicit means that the implementation
object can omit specification of any child attributes unless the implementation
object wishes to override some attributes. In other words, the implementation
object understands that the child's attributes will be used unless the
implementation object specifies an override value.

6.6.1 Comment: Suggest the use of a simple real example such as a thermostat.

6.7 Re sentence:
"A contract list X is compatible with contract list Y, if and only if
X narrows the value space defined by Y."
Later: "X can add new URIs to Y's list , but never any take away
Comment: (never take any away?)
If the override rules are that children or attributes omitted from a contract
specification use the default values, there is no way to take away. True?

7.2 Re sentence:
"The object model figure in Chapter 4 illustrates the valid XML elements and their
respective attributes."
Comment: Except for val which is not an element but an attribute
of a value object (or an umbrella term for a group of objects). 

9.1 Re example: Comment: Previous use of list have included the
<list....>   </list> pair (ref sections 3.2, 4.10, 6.8) or
the abbreviated <list...... /> (ref section 4.10).

10.1.2 Re sentence: "in fact the unit facet should be not included in the request".
Comment: I would think this is a place for explicit information.
Specifying the units in the request would allow the server to confirm that the
units are correct.
To not plainly express the units requires the server to assume the units
are correct. Such assumptions get us into trouble. If "complete extent" include
the units, the response will catch an error but after the error has been made.
Specifying the units in the write would allow the server to catch an error
before it took action.

11.5 Units.

The term "ratio" in this context confuses me. My dictionary defines ratio as a
relationship between two values. "a ratio of seven fundamental dimensions"? 
My dictionary defines function (in math) as a quantity whose value depends on
some number of other values. "A function of seven fundamental dimensions" makes
more sense to me.

I do not understand the second example:
acceleration is m/s2, which would be encoded as
<int name="m" val="1" />
<int name="sec" val="-2" />
Where is the squaring of se and the division m/s2 implemented?

I believe the -2 exponent of seconds in the joule normalized value should be -3
as shown in a later example.

12 Watches. Why worry about the exposure of well-known IP addresses? Suggest
"well-known" be replaced by "sensitive".

12.1 Suspect the "The Watch URI is available directly from the Lobby object"
should be  The WatchService URI...

12.2 Since the children of Watch are listed in an order of lease, add, etc,
suggest lease be in 12.2.1, add be in 12.2.2, etc.

12.2.1 Add
If an attempt is made to add a URI to a watch which was previously added,
suggest some kind of notice be included in the result; would be a useful
diagnostic tool.

In the Note: "not able" should be "not be able".

12.2.3 Suggest you add "since the last poll" to "This operation returns a list
of subscribed objects which have changed." 
Suggest "change" be defined as a change in state of a bool object and a change
greater than a delta value for a real object. The delta value should be
independently adjustable for each polled real object.

12.2.4 last sentence: ...have changed state or value since the pollRefresh
invocation. Add "or value".

12.2.5 Suggest change last sentence in second paragraph to
In all cases, the server will respond to the write request and include
in the response he new lease time in effect.

12.4 Feeds
Third sentence: Clients subscribe to feeds....
Suggest a delta be available for the lat and long.
The hysteresis on my GPS is there. So, as the satellites move I would expect
a change in the lat and long even if the object stays in a fixed position.

13. Points. Suggest the name attribute be included in each example.

14. History.
In the obix:History contract element <abstime name="start" null="true"/>,
does this mean the value is null or nill?
Question also applies to HistoryQueryOut.
In the example of a history, does the repitition of "query" in the href
attribute of op name="query" map to the HistoryFilter specified in
the obix:History contract. I would have thought that a particular
HistoryFilter would be assigned to the outsideAirTemp point.

14.3.4 Rollup Calc example:
looks like the start time specified in the QueryOut is 2005-03-17.....
while the start time in the result is 2005-03-16....

15 Alarming

Suggest alarmTimestamp be mentioned in 2. Alarm Generation.

Re "these alarms merely represent event": This confuses me.
Suggest this be clarified to show that an event is not a subset of alarm
but a separate and distinct object.

15.1.2 
As suggested above for 4.16.8, there are five states of annunciator.
1. clear
2. unackedAlarm
3. ackalarm
4. noname since system disallows.
5. unacked

normalTimestamp and alarmTimestamp are children of alarm
ackTimestamp is a child of ack
All three timestamps are grandchildren of annunciator.

15.2.2 StatefulAlarm
Per 15. "an alarm indicates a condition which requires notification of either a user
or another application" I am having trouble coming up with an example of an alarm
which does not transition back to normal.