Re: Questions related to UML diagram and mostly Contracts - Agenda list

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

    --

    

      
      
      
      
      
      
      
William Cox 

      
Email:  

      
Web: http://www.CoxSoftwareArchitects.com 

      
+1 862 485 3696 mobile

      

      

    

    
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? 
      

      
-- 

        
        
        
        
        
        
        
William Cox 

        
Email:  

        
Web: http://www.CoxSoftwareArchitects.com 

        
+1 862 485 3696 mobile