License Agreement: © 2004, Petrotechnical Open Standards Consortium, Inc. All rights reserved. All access, receipt, and/or use of this document is subject to the POSC Product Licensing Agreement posted on the POSC Web site at http://www.posc.org/about/license.shtml.

The following set of recommendations was developed at POSC in coordination with other groups, including CSIRO and the OpenGIS. It has been submitted to POSC for approval, and to OpenGIS for approval. (2002)

1.Using a Unit of Measure

1.1.Recommendation 1:

When an abbreviation for units of measure is to be used in an element or attribute name, the abbreviation should be uom or UOM.

Comment: The other obvious choice is “unit.” Since “unit” can have other meanings, it was felt that “uom” was a better choice than “unit.” The important point is to select one, and use it exclusively.

Comment: This recommendation is for abbreviations only. It is still permissible to use the full name, “UnitOfMeasure,” where appropriate.

1.2.Recommendation 2:

The type for the attribute, uom, may also be IDREF or string, with the understanding that it may be a keyref to a value that is contained within the file.

Comment: The use of xsd:double for the value is used since it is the most general format available in the W3C datatypes. It is not intended to imply any semantics on the data value, or to imply any special computer representation of the value.

Comment: It is intended that the attribute, uom, be a reference to another instance within the same file. Thus, alternative formulations of the quantityType would allow the uom to be of type xsd:IDREF, or of type xsd:string, where string is declared to be a keyref to a locally defined key. The particular implementation of the QuantityType is left to the using application. Note that xsd:IDREF is being deprecated, and its use is discouraged.

Comment: The use of xsd:anyURI for a local reference implies that a “#” is included. Applications should be able to handle a reference with or without the “#” symbol. Below is an example of a QuantityType with uom of type xsd:anyURI and one of xsd:string:

Comment: The Recommendation uses the term, “QuantityType.” This is not mandatory. The name of the complexType is local, and is under control of the schema developer. Also widely used is MeasureType or MeasurementType. However, the structure of the complexType should be maintained.

Comment: The Recommendation is that the uom attribute be optional. This is not mandatory. The schema developer may make it required.

Comment: The string value of the uom attribute does not contain any semantic meaning. It is strictly defined as a key reference to another instance within the document. The use of “ft” in the above example does not necessarily imply that the unit of measure is a foot. However, in practice, it would probably be useful to have a meaningful value.

1.3.Recommendation 3:

Comment: This datatype differs from the QuantityType only in that there is no value. Its usage is to set a unit of measure within a context, rather than to assign a unit of measure to a value.

2.Defining a Unit of Measure

The uom attribute defined above is intended to be a key reference to an instance within the same document. The instance within the document is a definition of the unit of measure. The definition may either be contained at that point in the document, or be a reference to a definition in another document. This latter case is referred to as a “skip reference.”

Every uom value in a document should reference an instance with an id attribute within the document.

Comment: Recommendation 4 is a preferred practice. There are two exceptions to the practice. The first is that the uom attribute directly reference an instance in another document. This alternative puts a burden on the reader, and may degrade interoperability.

Comment: The second exception is that the reference be implied, rather than explicit. In particular, using the example above, the “ft” used as a reference is intended to imply that there is meaning to “ft” that is known to the reading application. This puts a burden on the reader to understand all uom references, since they are implicitly defined. While this practice is acceptable in a tightly controlled environment, it is not interoperable in a general environment, and its use is highly discouraged. This comment leads to the following variation on Recommendation 4:

2.2.Recommendation 4a:

Within a tightly controlled environment, it is acceptable for the uom value to be a symbol that represents a unit of measure. When this is the case, there must be a specification that lists all the acceptable symbols and their meanings.

Comment: When using Recommendation 4a – reference by symbol – compliant applications must understand all the symbols in the listed set. It should also be understood that extensions to new units of measure require a change to the specification, rather than a simple extension, since the new unit of measure will break all existing applications.

2.3.Recommendation 5:

A skip reference datatype be defined as follows:

<xsd:complexType name="skipRefType">
  <xsd:attribute name="id" type="xsd:ID" use="required"/>
  <xsd:attribute name="href" type="xsd:anyURI" use="required"/>
</xsd:complexType>

with exceptions as noted below in the comments.

Comment: The skipRefType has the property that it contains a referencable key, and references a resource, generally in another document.

Comment: The value of the id attribute is a key may be referenced by a uom attribute. The semantic meaning of the xsd:ID datatype in this definition is that it be unique within the document, and serve as a key for a uom keyref. Note that this may also be accomplished using the schema elements uniq, key, and keyref. This process is encouraged within application documents as an alternative to the above.

Comment: The href attribute is illustrative. No general agreement has been set for the attribute name. However, such agreement should a goal of using groups.

Comment: The datatype xsd:anyURI is necessary. The purpose of the skip reference is to reference an outside resource.

Comment: An example of use of the skip reference follows. This reference takes the local “ft”, and skips it to a document which contains the definition of a “foot”:

<skipRef id=”ft” href=”http://www.some.com/unitDef.xml#foot”/>

2.4.Recommendation 6:

A complexType be used that defines the meaning of a unit of measure. The meaning is contained in one of two ways – either it is a base unit, or it contains a conversion to a referenced base unit. Beyond these two requirements, this recommendation does not define the information carried in such a definition or the structure of the information. Recommendations 7 and 8 further define these two requirements.

Comment: The element containing the definition must have an id attribute of type xsd:ID, where the xsd:ID may be replace by xsd:string with uniq, key, and keyref definitions as appropriate. This allows the definition to referenced by a uom or href attribute.

Comment: Recommendations 6, 7, and 8 will require that a unit of measure definition have either a BaseUnit subelement or a ConversionToBaseUnit subelement.

2.5.Recommendation 7:

A definition of a base unit should have a subelement, BaseUnit. The content of BaseUnit, if any, is not defined by this recommendation.

Comment: A minimal definition of a base unit would look like, for example,

<UOMDefinition id=”m”>
  <BaseUnit/>
</UOMDefinition>

Additional information may be contained that would, for example, give a name for the unit (such as metre), the definition of it, how it is annotated, a citation, etc.

2.6.Recommendation 8:

A definition of a unit of measure that is not a base unit would have a subelement, ConversionToBaseUnit, that is of type, conversionType, as follows:

<xsd:complexType name="conversionType">
  <xsd:sequence>
    <xsd:choice>
      <xsd:element name="Factor" type="xsd:double"/>
      <xsd:element name=”Fraction”>
       <xsd:complexType>
        <xsd:sequence>
         <xsd:element name="Numerator" type="xsd:double"/>
         <xsd:element name="Denominator" type="xsd:double"/>
        </xsd:sequence>
       </xsd:complexType>
      </xsd:element>
      <xsd:element name=”Formula”>
       <xsd:complexType>
        <xsd:sequence>
         <xsd:element name="A" type="xsd:double" minOccurs="0"/>
         <xsd:element name="B" type="xsd:double"/>
         <xsd:element name="C" type="xsd:double"/>
         <xsd:element name="D" type="xsd:double" minOccurs="0"/>
        </xsd:sequence>
       </xsd:complexType>
      </xsd:element>
    </xsd:choice>
  </xsd:sequence>
  <xsd:attribute name="baseUnit" type="xsd:anyURI" use="required"/>
</xsd:complexType>

Comment: This definition maps directly to the schema that is output using the MDA rules in ISO 19118. However, it has been modified slightly from the direct output.

Comment: As given in other papers, the A, B, C, D capture the parameters in the equation:

Y = (A + B* X) / (C + D* X)

Where X is the value of the measure in the input units, and Y is the value in the base unit.

Comment: The ConversionType may be restricted by groups, and still be in compliance with Recommendation 8.

3.References

3.1.Outside References

[ANSIX12] X12 Reference Model for XML Design, 2002-10, produced by the ANSI X12 committee, obtainable at http://www.x12.org/x12org/.

[BestPractices] Best Practices Homepage, developed and maintained by XML-dev and Mitre, obtainable at http://www.xfront.com/BestPracticesHomepage.html.

[ComProServ] PIDX XML Standards Master, Version 1.0, RP 3901, produced by PIDX, obtainable at http://committees.api.org/business/pidx/standards.htm.

[EBCCNAM] ebXML RT - Naming Convention for Core Component, 2001-05-10, produced by the ebXML group, obtainable at http://www.ebxml.org/specs/index.htm#technical_reports.

[ebTechArch] ebXML Technical Architecture Specification V1.0.4, 2001-02-16, produced by the ebXML group, obtainable at http://www.ebxml.org/specs/ebTA.pdf.

[FedDevGuide] Draft Federal XML Developer's Guide, 2002-04 (work in progress), produced by the Federal CIO Council, obtainable at http://xml.gov/documents/in_progress/developersguide.pdf.

[FedTagStds] Federal Tag Standards for Extensible Markup Language, 2001-06, produced by LMI, not obtainable from the internet.

[HKGuide] XML Schema Design and Management Guide, (4 parts), Draft versions dated in summer, 2003. Produced by Hong Kong Information Services Technology Division. Available at http://www.itsd.gov.hk/itsd/english/infra/eif.htm.

[IETFKeywords] Key Words for Use in RFCs to Indicate Requirement Level, 1997-03, obtainable at http://www.ietf.org/rfc/rfc2119.txt.

[ISO8601] International Standard Date and Time, 2001-11-10, produced by ISO. A web page that explains the formats is http://www.cl.cam.ac.uk/~mgk25/iso-time.html.

[ISO11179] ISO 11179 Part 5 - Naming and Identification, 1995-12, produced by ISO, obtainable at http://fdr.faa.gov/iso/ISO11179page.htm. There is a later version, that is available from the ISO website,

[UKGuide] e-Government Schema Guidelines for XML, 2002-12, produced by United Kingdom e-Envoy, obtainable at http://www.e-envoy.gov.uk/Resources/Guidelines/fs/en.

[Unicode] Unicode Charts, available at http://www.unicode.org/charts/.

[W3CSchemaDatatypes] W3C Schema Datatypes, 2001-05-02, produced by W3C, obtainable at http://www.w3.org/TR/xmlschema-2.

[W3CNamespaces] Namespaces in XML, 1999-01-14, produced by W3C, obtainable at http://www.w3.org/TR/REC-xml-names/.

[W3CSchemaPrimer] W3C Schema Primer, 2001-05-02, produced by W3C, obtainable at http://www.w3.org/TR/xmlschema-0.

[W3CSchemaStructures] W3C Schema Structures, 2001-05-02, produced by W3C, obtainable at http://www.w3.org/TR/xmlschema-1.

[Xlink] W3C XLink Specification, 2001-06, produced by W3C, obtainable at http://www.w3.org/TR/xlink/.

[Xpath] W3C XPath Specification, 1999, produced by W3C, obtainable at http://www.w3.org/TR/xpath/.

[XSL] W3C XSL and XSLT Specifications, produced by W3C, obtainable at http://www.w3.org/Style/XSL/.

3.2.POSC References

POSC references are available in the following formats:

[html] html format readable by browsers

[doc] MS Word 97/2000/XP

[sxw] OpenOffice writer, v1.0