Questions related to UML diagram and mostly Contracts

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:  

      
Web: http://www.CoxSoftwareArchitects.com 

      
+1 862 485 3696 mobile