Need to add to Craig's listing on April 14:
OBIX-244 (should WSDL be part of the work product) and OBIX-238.
No replies that address the issues. One major problem is that the
schema says one thing and it seems the spec says something else -
for example the Contract List issues.
I'd like the schema to reflect current practice (our goal IMO for
1.1), the UML reflect the schema, and both to align with the spec.
The real issue is not "what's in the spec" but "what SHOULD be in
the spec, and how does that line up with the schemas?"
Thanks!
bill
--
On 4/8/15 6:50 PM, William Cox wrote:
As an obix neophyte, I did a thorough reread of WD39 (hence a lot
of edtorial nits).
This is taken from OBIX-238 at https://issues.oasis-open.org/browse/OBIX-238
.
IT WOULD BE MOST USEFUL FOR COMMENTS TO BE MADE IN THE JIRA ITEM
RATHER THAN BY EMAIL - comments can easily be added, or one can
create a proposed resolution and then comment on it.
These are my issues as reflected in the UML diagram in WD39 Figure
4-1 page 17 Line 323:
The UML diagram has a number of issues that need to be addressed
to avoid misleading a UML knowledgeable reader.
(1) contract is shown as anyURI, however the text says that a
Contract is a list of URIs. Is that list ordered? [this would
raise questions such as "Does a different order mean that you
have a different contract? Is there a canonical comparison? ")
Perhaps Contract should be a conformed string with
space-separated anyURI values, or a list or something else?
Is the correct use for use in an obix Obj "is" as a
space-separated list of URIs? Seems that relative and absolute are
OK; are fragments OK?
Are there any uses of "contract" where only a single URI is
required?
Should this actually be "contracts" with a plural?
Note that in the XSD PR03 (same as WD38):
<xs:simpleType name="contract">
<xs:list itemType="xs:anyURI"/>
</xs:simpleType>
So the UML is correct, but it doesn't work with space-separated
lists of URIs. And apparently neither does the schema. Note the
xs:list.
Then in the schema list is defined as
<xs:element name="list" type="List"
substitutionGroup="obj">
<xs:annotation>
<xs:documentation>conveys a list of other
Objects. The primary advantage of using a list versus a generic
obj is that lists can specify a common Contract for their
contents using the of attribute. If specified the of attribute
MUST be a list of URIs formatted as a Contract
List</xs:documentation>
</xs:annotation>
</xs:element>
Note the comment. But this differs from the xs:list used earlier.
(2)The use of obix:Nil suggests in the obix package that there
is a contract that may be treated as a Nil value. Is that the
null string? Is it a defined URI that has "Nil" as the last
component? The answers to these questions will guide the
correction of the UML diagram.
How is this treated in the schema? Is there a difference between
an empty string "" and an empty list of URIs (list of contracts)?
(3) Should a Sequence be used in the UML
rather than a conformed string?
Ties into number (1) - if a contract is xsd:anyURI then what seems
to be required is a sequence (unordered list) of contracts.
(4) Consider the accuracy of the definition of Contract in Table
1-1 line 116.
(5) Line 152 Table 1-4 talks about "long Contract Lists" but
that apparently defined term is not elsewhere in the
specification. Is it a list of Contracts? or the space-separated
list of URIs that are included in a single Contract? Correct
this.
I don't understand the history.
(6) Line 183-184 "OBIX captures these concepts into Contracts.
Contracts allow us to tag Objects with normalized semantics and
structure." should say something more like "OBIX expresses these
concepts as Contracts. OBIX Contracts allow us to tag Objects
with normalized semantics and structure." (though I'm not sure
what the last phrase means here)
So what is "normalized semantics and structure"?
(7) Section 3.6 line 276ff. I thought Contract was a list of
URIs (apparently now URI references to Contracts
does that phrase make sense? Does the URI reference something and
the reference is a contract, and any contract may have multiple
URIs?
, but the object itself is a subclass
equivalent to "anyURI" in the UML). The apparent conflict
between an object as a template and a URI referencing an object
needs to be clearly resolved in both the Quick Start and section
3.6.
(8) Line 359 is nul the same as Nil? If not where is it defined?
If a contract is a list of space-separated URIs, is this actually
represented as the null string (of zero length)? Or is it a
distinguished URI that INDICATES that it's not a valid contract
[list]? I'm confusing the terminology, I'm afraid.
(9) Line 357 says "the value of this attribute ["is"] MUST be a
Contract List...Section 7.2" Of, Is, In,out all require
Contract Lists which seems to be defined at line 1024. It's not
a 4.3.2 "list" as pointed out on line 1032. Note should be
earlier as well as on 1032.
This is confusing.
(10) Line 1024 is a single Contract a reference to a contract,
or a single element Contract List? This affects the UML model as
the class name should probably be ContractList rather than
Contract.
Ties in with 1-7
(11) Line 1035 is ContractList the same as "...a Contract List"
on line 1034? How about line 1042?
|