Questions related to UML diagram and mostly Contracts

[William Cox <wtcox@CoxSoftwareArchitects.com>]

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?

--

William Cox 

Email: wtcox@CoxSoftwareArchitects.com 

Web: http://www.CoxSoftwareArchitects.com 

+1 862 485 3696 mobile