[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: RE: [obix] Resolved issues post meeting - Ludo's email
How about adding just one optional attribute for each of reltime and time? (reltime is very similar to abstime, and date is similar close to time). Leaving the examples of abstime
and date without any optional attributes also shows that the objects don't need optional attributes.
From: obix@lists.oasis-open.org [obix@lists.oasis-open.org] on behalf of Gemmill, Craig [craig.gemmill@tridium.com]
Sent: Tuesday, October 28, 2014 2:03 PM To: Bertsch, Ludo; William Cox; Obix TC List Cc: ludob@horizontec.com; Toby Considine Subject: RE: [obix] Resolved issues post meeting - Ludo's email Thanks.
I’ve done this for bool, int, real, str, and enum. Beyond that, I think the pattern of the contract definition defining only the attributes that exist in the default object is well established, and I think the implementer could figure it out. Do you agree? If so, I can post WD37 now. If not, I may need a little more time for the other types.
From: Bertsch, Ludo [mailto:bertsch@caba.org]
Sounds good.
By the way, your latest examples for "bool" and "int" are much better.
The previous example in WD36 for "bool", <bool val="true"/>, did not do much to further a person's understanding.
Your latest example for "bool" nicely highlights the concept of "range" which is listed in the Schema and Figure 4-1, but whose use is not immediately apparent. This latest example shows how to connect the "false" and "true" values to real life values. This is helpful in furthering a person's understanding.
I encourage you to do the same for the others, paying particular attention to characteristics that might not be immediately apparent, such as using the optional attributes listed in Figure 4-1. Since your "Int" example did not use "unit", it may be helpful to include "unit" in the example of Real. Similarly, the use of "min" and "max" for Str would be helpful, since it is not immediately apparent what is meant by that.
Using these optional attributes in the examples and using good examples, also helps to solidify the understanding of Figure 4-1, Schema and Contract Definitions.
Cheers, Ludo
From: Gemmill, Craig [craig.gemmill@tridium.com]
From: Bertsch, Ludo [mailto:bertsch@caba.org]
While max, min and unit might not exist for Int, they appear in the Schema and Figure 4-1 with no further explanation. I think this needs to be explained.
The only description for Figure 4-1 is (lines 315-316): "OBIX specifies a small, fixed set of object types. The OBIX object model is summarized in Figure 4-1. It consists of a common base Object (obix:obj) type, and includes 16 derived types."
Figure 4-1 then shows Int having: + max: int[0..1] + min: int[0..1] + unit: anyURI[0..1] + val: int = 0
Therefore, one could understandably assume that the max, min and unit attributes "exist".
Perhaps the Lines 315-316 should say: "OBIX specifies a small, fixed set of object types. The OBIX object model is summarized in Figure 4-1 and derived from the Schema. It consists of a common base Object (obix:obj) type, includes 16 derived types, and lists the optional attributes for each type."
I like this addition. It captures the optional nature of the attributes in a more concrete way than just the [0..1] in the figure does. Although I understand that the figure is a correct representation of the schema. I’ve incorporated this – actually, your followon language.
Similarly, it may also be helpful at the appropriate introductory place to clarify that the Schema lists the optional attributes. I’ve added a sentence about this in 4.1.
It may also be helpful at the appropriate introductory place to clarify what to expect in the Contract Definitions (e.g. defaults, Schema references, contracts implemented) and what not to expect (e.g. optional attributes) before Contract Definition is used (in Line 333) or as it is used for the first time. Added language in 4.2 after line 333, in the explanation of the Contract Definition of obix:obj.
In summary, the differences and similarities between the Schema, Figure 4-1, and Contract Definitions should be clear.
I think that your additional text below is helpful when the text I suggested above is incorporated. Great, I will fill out the rest of the types then.
Cheers, Ludo
From:
obix@lists.oasis-open.org [obix@lists.oasis-open.org] on behalf of Gemmill, Craig [craig.gemmill@tridium.com] 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?
boolThe 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.
intThe 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]
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">
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] 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]
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] 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] Craig, Chris, and others - 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:
Compare to 512.
From:
obix@lists.oasis-open.org [obix@lists.oasis-open.org] on behalf of Gemmill, Craig [craig.gemmill@tridium.com] Comments inline.
From: William Cox [mailto:wtcox@CoxSoftwareArchitects.com]
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 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.
is = 0 .. N, not 0 .. 1
You mean in Section 4 or something?
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:
|
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]