Section 2, Lines 114-115: "document" used to refer to multiple types of documents, needs clarification

    • Type: Bug
    • Resolution: Fixed
    • Priority: Major
    • OBIX 1.1 WD15
    • Affects Version/s: None
    • Component/s: OBIX 1.1 Specification
    • None
    • Environment:

      Ludo Bertsch, Horizon Technologies Inc. (250) 592-1488
      Representing CABA (Continental Automated Buildings Association)

    • Hide

      Propose to add the following text to 1.1.1 as a new paragraph:

      Data objects are represented in XML by XML documents. It is important to distinguish the usage of the term document in this context from references to this specification document. When "this document" is used, it references this specification document. When "oBIX document" or "XML document" is used, it references an oBIX object, encoded in XML, as per the convention for this (specification) document.

      Also, inspect the entire spec to ensure clarity - several instances of "this document" changed to "this specification", and instances of "the document" changed to "the oBIX document".

      Show
      Propose to add the following text to 1.1.1 as a new paragraph: Data objects are represented in XML by XML documents. It is important to distinguish the usage of the term document in this context from references to this specification document. When "this document" is used, it references this specification document. When "oBIX document" or "XML document" is used, it references an oBIX object, encoded in XML, as per the convention for this (specification) document. Also, inspect the entire spec to ensure clarity - several instances of "this document" changed to "this specification", and instances of "the document" changed to "the oBIX document".

      Up to this point, "document" has referred to the oBIX specification documents (oBIX V1.1, Encodings, REST, SOAP), yet "document" in line 115 seems to reference a different type of document.

      It is suggested that clarification be made to differentiate from the oBIX specification documents. Similar clarification should be considered throughout the specification document.

            Assignee:
            Craig Gemmill (Inactive)
            Reporter:
            Toby Considine (Inactive)
            Votes:
            0 Vote for this issue
            Watchers:
            1 Start watching this issue

              Created:
              Updated:
              Resolved: