search

jordoncm / kml-samples

Automatically exported from code.google.com/p/kml-samples
5 stars 0 forks source link

Extended metadata needed for ExtendedData Schema elements #291

Open GoogleCodeExporter opened 9 years ago

GoogleCodeExporter commented 9 years ago 
Which products are relevant to this feature request?

 KMLStandard, GoogleEarth

What should this feature enhancement do?

The following proposes a simple extension to KML allowing for metadata to
be added to the ExtendedData SimpleField definitions.

There is a growing use of KML in machine-to-machine (M2M) exchanges which
is making heavy usage of KML's ExtendedData element.  However, at present
there is no standard convention to represent units of measure (uom) and
other common metadata other than a field name and data type.  ExtendedData
using arbitrary XML data exists but that approach loses the ability of
Google Earth to display it and may force a designer to duplicate data both
in a displayable ExtendedData group and an arbitrary XML data group. 

Some KML documents hardcode units in the BalloonStyle in unstructured ways
for presentation but this is not good for M2M.  Some units are hardcoded
into the field names themselves which is bad practice but better than nothing.

Example:

  <ExtendedData>
      <Data name="radiusInKm">
          <value>173</value>
      <Data name="speedInMph">
          <value>37.55136</value>
      </Data>
...
  </ExtendedData>

SimpleField in KML 2.2 is defined as the following:

  <element name="SimpleField" type="kml:SimpleFieldType"/>
  <complexType name="SimpleFieldType" final="#all">
    <sequence>
      <element ref="kml:displayName" minOccurs="0"/>
      <element ref="kml:SimpleFieldExtension" minOccurs="0"
        maxOccurs="unbounded"/>
    </sequence>
    <attribute name="type" type="string"/>
    <attribute name="name" type="string"/>
  </complexType>
  <element name="SimpleFieldExtension" abstract="true"/>

The SimpleFieldExtension has no instantiation in the KML schema so any uses
of it must be in a non-kml namespace, hence no standard way to extend
SimpleFields.

A standard use of KML's SimpleFieldExtension could facilitate a best
practice of associating metadata with schema fields enabling greater
interoperability of data in KML formats.

-----------------
Recommendation #1
-----------------

A short term recommendation is adding the proposed changes (add new element
definition) into the Google Earth experimental extensions schema. This
approach won't require approval by OGC advisory board and can be added
immediately.

Minor change is required to Google Earth client to allow the new
SimpleMetadata element as a child to SimpleField.  If KML error handling is
enabled in current Google Earth client then an error dialog shows
SimpleMetadata as an unknown element even though the KML 2.2 schema allows
extensions via the SimpleFieldExtension type.

URL: http://code.google.com/apis/kml/schema/kml22gx.xsd

<schema xmlns="http://www.w3.org/2001/XMLSchema"
  xmlns:gx="http://www.google.com/kml/ext/2.2"
  xmlns:kml="http://www.opengis.net/kml/2.2"
  xmlns:atom="http://www.w3.org/2005/Atom"
  xmlns:xal="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0"
  targetNamespace="http://www.google.com/kml/ext/2.2"
  elementFormDefault="qualified"
  version="090102 BETA">
...

  <element name="SimpleMetadata" type="gx:SimpleMetadataType"
    substitutionGroup="kml:SimpleFieldExtension"/>
  <complexType name="SimpleMetadataType" final="#all">
    <sequence>
      <any namespace="##other" processContents="lax" minOccurs="0"
        maxOccurs="unbounded"/>
    </sequence>
    <attribute name="uom" type="anyURI" use="optional">
    <annotation>
      <documentation>Reference to a unit of measure definition</documentation>
    </annotation>
    </attribute>
  </complexType>

Units of measure (via uom attribute) is defined with common URIs.

See references:
- https://www.seegrid.csiro.au/twiki/bin/view/CGIModel/OgcURNScheme
- http://aurora.regenstrief.org/~ucum/ucum.html
-
https://www.seegrid.csiro.au/subversion/xmml/OGC/trunk/ExampleInstances/dictiona
ries/units.xml
- http://unitsofmeasure.org/

A more sophisticated definition can be defined similar to gml:UomIdentifier
with both URIs and UOM id's as described in latest GML spec
http://www.ogcnetwork.net/gml.

<simpleType name="UomIdentifier">
 <union memberTypes="gml:UomSymbol gml:UomURI"/>
 </simpleType>
 <simpleType name="UomSymbol"> <restriction base="string">
 <pattern value="[^: \n\r\t]+"/> </restriction>
 </simpleType>

Here is a quote from the GML spec in regards to UOMs:

    "NOTE It is recommended that the symbol be an identifier for a unit
    of measure as specified in the Unified Code of Units of
    Measure (UCUM) (http://aurora.regenstrief.org/UCUM). This provides a
    set of symbols and a grammar for constructing identifiers for units
    of measure that are unique, and may be easily entered with a
    keyboard supporting the limited character set known as 7-bit ASCII.
    ISO 2955 formerly provided a specification with this scope, but was
    withdrawn in 2001. UCUM largely follows ISO 2955 with modifications
    to remove ambiguities and other problems."

To make this work well a standard dictionary of units with URI convention
will need to be adopted and maintained so for example the units.xml
provided at
https://www.seegrid.csiro.au/subversion/xmml/OGC/trunk/ExampleInstances/dictiona
ries/units.xml
might be used for early adopters and made available at www.ogc.net,
www.google.com or similar web site.

Example:

<kml xmlns="http://www.opengis.net/kml/2.2"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:gx="http://www.google.com/kml/ext/2.2"
     xmlns:gml="http://www.opengis.net/gml"
     xmlns:om="http://www.opengis.net/om/1.0/gml32">
    <Document>
        <Schema id="SensorTypesId" name="SensorTypes">
            <SimpleField name="model" type="string"/>
            <SimpleField name="reason" type="string"/>
            <SimpleField name="sensorCoverage" type="double">
        <gx:SimpleMetadata  uom="urn:ogc:def:uom:OGC:km">
            <description>
       radius of sensor coverage in km with platform position at center
       </description>
        </gx:SimpleMetadata>
        </SimpleField>
            <SimpleField name="speed" type="double">
        <gx:SimpleMetadata  uom="urn:ogc:def:uom:OGC:m_s">
            <description>this is the true air speed of a given aircraft in meters
per second</description>
            <om:observedProperty xlink:href="urn:ogc:def:phenomenon:OGC:speed" />
        </gx:SimpleMetadata>
        </SimpleField>
            <SimpleField name="fov" type="double">
        <gx:SimpleMetadata  uom="urn:ogc:def:uom:OGC:deg">
            <description>field of view in decimal degrees</description>
        </gx:SimpleMetadata>
        </SimpleField>
            <SimpleField name="distanceToAOI" type="double">
        <gx:SimpleMetadata  uom="urn:ogc:def:uom:OGC:km">
            <description>distance to area of interest</description>
            <om:observedProperty xlink:href="urn:ogc:def:phenomenon:OGC:length" />
        </gx:SimpleMetadata>
        </SimpleField>
        </Schema>
        <Placemark>
            <name>1</name>
            <ExtendedData>
                <SchemaData schemaUrl="#SensorTypesId">
             <SimpleData name="model">E8C</SimpleData>
             <SimpleData name="reason">Asset Not in Range</SimpleData>
             <SimpleData name="sensorCoverage">200</SimpleData>
             <SimpleData name="fov">85</SimpleData>
             <SimpleData name="speed">169.9</SimpleData>
             <SimpleData name="distanceToAOI">480.2</SimpleData>
                </SchemaData>
            </ExtendedData>
            <Point>
            <coordinates>-71.238861602674,42.504733587704,13.0</coordinates>
            </Point>
        </Placemark>
    </Document>
</kml>

Failing adopting a GML-like uom attribute, the SimpleMetadata can be
further simplified to the following:

  <element name="SimpleMetadata" type="gx:SimpleMetadataType"
    substitutionGroup="kml:SimpleFieldExtension"/>
  <complexType name="SimpleMetadataType" final="#all">
    <sequence>
      <any namespace="##other" processContents="lax" minOccurs="0"
        maxOccurs="unbounded"/>
    </sequence>
  </complexType>

And gml:unitOfMeasure could be used for UOM.

            <SimpleField name="distanceToAOI" type="double">
        <gx:SimpleMetadata>
            <description>distance to area of interest</description>
            <om:observedProperty xlink:href="urn:ogc:def:phenomenon:OGC:length" />
            <gml:unitOfMeasure uom="urn:ogc:def:uom:OGC:km"/>
        </gx:SimpleMetadata>
        </SimpleField>

-----------------
Recommendation #2
-----------------

A long term solution is to extend the SimpleFieldType type (with
description and uom tags) in the KML standard and create a default
SimpleFieldExtension
instance as follows:

  <complexType name="SimpleFieldType" final="#all">
    <sequence>
      <element ref="kml:displayName" minOccurs="0"/>
      <element ref="kml:description" minOccurs="0"/>   <!-- new -->
      <element ref="kml:SimpleFieldExtension" minOccurs="0"
        maxOccurs="unbounded"/>
    </sequence>
    <attribute name="type" type="string"/>
    <attribute name="name" type="string"/>
    <attribute name="uom" type="anyURI" use="optional">   <!-- new -->
    <annotation>
      <documentation>Reference to a unit of measure definition</documentation>
    </annotation>
    </attribute>
  </complexType>

  <element name="SimpleMetadata" type="kml:SimpleMetadataType"    <!-- new -->
    substitutionGroup="kml:SimpleFieldExtension"/>
  <complexType name="SimpleMetadataType" final="#all">         <!-- new -->
    <sequence>
      <any namespace="##other" processContents="lax" minOccurs="0"
        maxOccurs="unbounded"/>
    </sequence>
  </complexType>

In example below the Placemark is identical to the one in previous example,
but only the Schema is changed to reflect native KML extensions as opposed
to external extensions (i.e. via non-kml namespace).

Example:

<kml xmlns="http://www.opengis.net/kml/2.2"
     xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
     xmlns:om="http://www.opengis.net/om/1.0/gml32">
    <Document>
        <Schema id="SensorTypesId" name="SensorTypes">
            <SimpleField name="model" type="string"/>
            <SimpleField name="reason" type="string"/>
            <SimpleField name="sensorCoverage" type="double"
uom="urn:ogc:def:uom:OGC:km">
        <description>radius of sensor coverage in km with platform position at
center</description>
        </SimpleField>
            <SimpleField name="speed" type="double"
uom="urn:ogc:def:uom:OGC:m_s">
        <description>this is the true air speed of a given aircraft in meters per
second</description>
        <SimpleMetadata>
            <om:observedProperty xlink:href="urn:ogc:def:phenomenon:OGC:speed" />
        </SimpleMetadata>
        </SimpleField>
            <SimpleField name="fov" type="double"
uom="urn:ogc:def:uom:OGC:deg">
        <description>lateral field of view in decimal degrees</description>
        </SimpleField>
            <SimpleField name="distanceToAOI" type="double"
uom="urn:ogc:def:uom:OGC:km">
        <description>distance from platform to area of interest</description>
        <SimpleMetadata>
            <om:observedProperty xlink:href="urn:ogc:def:phenomenon:OGC:length" />
        </SimpleMetadata>
        </SimpleField>
        </Schema>
        <Placemark>
        <!-- same as previous -->
        </Placemark>
    </Document>
</kml>

Are there any known workarounds that produce the similar results?
----------------------------------------------------------------

Other brute force approaches include: 1) hard-code units into the extended
data element names (not desired) or include units and other meta data as
inline comments in the KML (also not desired because non-standard and not
easily parsed by KML readers/viewers and comments can be easily stripped).

Original issue reported on code.google.com by gjmath...@gmail.com on 17 Aug 2009 at 2:51

GoogleCodeExporter commented 9 years ago

Original comment by api.roman.public@gmail.com on 20 Aug 2009 at 6:49