Uploaded image for project: 'OASIS Open Building Information Exchange (oBIX) TC'
  1. OASIS Open Building Information Exchange (oBIX) TC
  2. OBIX-30

General: Document should indicate more clearly what is normative, what is illustrative.

    XMLWordPrintable

    Details

    • Type: Improvement
    • Status: Closed
    • Priority: Major
    • Resolution: Fixed
    • Affects Version/s: oBIX 1.1 PR01
    • Fix Version/s: OBIX 1.1 WD15
    • Component/s: OBIX 1.1 Specification
    • Labels:
      None
    • Environment:

      Toby Considine

    • Proposal:
      Hide

      Replace Extendability with Extensibility throughout document. Extendability is the capability of reaching out, as in an arm can extend because an elbow provides for extendability.

      Suggest making the use of lowerCamelCase in Names normative, and adding normative reference to CamelCasing.

      Suggest that defined terms have their first letter Upercased, as in Object or Facet, to distinguish from discussion of a general object or XML facet.

      Show
      Replace Extendability with Extensibility throughout document. Extendability is the capability of reaching out, as in an arm can extend because an elbow provides for extendability. Suggest making the use of lowerCamelCase in Names normative, and adding normative reference to CamelCasing. Suggest that defined terms have their first letter Upercased, as in Object or Facet, to distinguish from discussion of a general object or XML facet.

      Description

      For example, All examples are non-normative. Section 1 is non-normative. Etc. This also ties to the unfortunate shuffling in of REST at several sections. Perhaps if the introduction included something such as

      "This specification describes an information model and the basic operations for oBIX-based services. For simplicity, it assumes XML encoding and RESTful interactions. The normative description of the XML is the associated schema (XSD). The formal description of the REST interactions is described in the document REST Bindings for OBIX (see version xx or later version). The use of REST within this document is purely illustrative, and practitioners should look to the appropriate Binding document for normative guidance.

      Similarly, alternate encodings are specified in the specification "Common Encodings for oBIX" (see version xx or later version). Practitioners using creating any interactions in encodings other than XML should look to the document referenced above or other encodings specifications that may be developed"
      This suggestion leads to moving some REST descriptions, described elsewhere, into the REST document and out of this.

        Attachments

          Activity

            People

            • Assignee:
              craigg Craig Gemmill (Inactive)
              Reporter:
              Toby.Considine Toby Considine
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: