MARINE XML SCHEMA DOCUMENTATION

MARINE XML SCHEMA DOCUMENTATION

INDEX

INTRODUCTION

MARINE XML SCHEMA MAP AND ELEMENT SEARCH

ENCODING A DATA SET

ENCODING AN INDIVIDUAL RECORD

ENCODING SPATIAL DATA

ENCODING TEMPORAL DATA

ENCODING THE DATA SOURCE DETAILS

ENCODING MARINE DATA

APPENDIX A DATE/TIME ISO8601 STANDARD

TABLES OF VALID VALUES

INTRODUCTION

The Marine XML (eXstensible Markup Language) structure has been developed to encapsulate marine data. It provides an efficient means to store, transfer and display marine data.

Advantages:

Data is immediately interpretable to the eye. XML is used to encase data inside tags in a hierarchal structure.
Any edits and changes to data through quality control can be tracked and recorded within the Marine XML structure.
When converting data to XML data can be validated against a Marine XML Schema or DTD (Document Type Definition).
Data can be converted to and from Marine XML using XSL stylesheets, with no programming involved, allowing the easy exchange of Marine XML data between organisations.
Data can be mapped to a graphical display straight from the Marine XML source using a XSL stylesheet.

Disadvantages:

Due to the structural nature of XML, the file size can be increased significantly when tagging data in Marine XML.

NOTE!

Expendable Bathythermograph Data (XBT) uses a slightly different schema to other data types. Instead of storing all temperature/depth pairs on 1 line in the XML file, temperature/depth pairs are encoded over multiple lines in a child element of 'ValueList' called 'Values'. See the section titled 'ValueList' later in this document for details.

MARINE XML SCHEMA MAP AND ELEMENT SEARCH

ENCODING A DATA SET

MarineDataSet

Marine XML structure has been designed to encapsulate a dataset. The parent element of an XML file is the MarineDataSet element. This element encases the entire dataset. Child elements of MarineDataSet are used to describe the quality of the data, custodian, quality control and dataset details. These elements are followed by a series of MarineDataRecord elements containing the data itself.

Attributes:

Name	Value	Use	Description
caveat	String	Optional	Used to set a restriction on the dataset. Suggested list of valid values for this attribute are defined in Table 1.
name	String	Optional	This attribute can have any value and can be used to identify the type of MarineDataSet.
description	String	Optional	This attribute can be used to assign a description of the data set.
creationDate	String	Optional	The creation date of the file. Although this attribute can be any string value the suggested date/time format is the ISO8601 standard.

Child elements:

Element	Type	Number	Description
Quality	Required	1	Describes quality of the whole dataset. Suggested list of valid values for this attribute are defined in Table 2.
Custodian	Optional	1	Used to encase custodian details.
QCDetails	Optional	1	Used to encase quality control details.
Property	Optional	0 or more	Used to outline any properties pertaining to the dataset.
MarineDataRecord	Required	1 or more	Used to encase data for the same spatial and temporal extents.

Example

Quality

The quality element is used to describe the overall quality of an object. This element has no attributes and contains free text. The value of Quality is up to the user to decide. A suggested list of values for Quality are defined in Table 2.

The Quality element is used in a variety of places within the Marine XML structure. It is a compulsory child element of MarineDataSet. It is also an optional child element of the MarineDataRecord, TemporalReference, SpatialReference and DataObject elements. Where the overall quality of a dataset may be good, you can also specify the quality of individual records, their spatial and temporal information and the data itself if required.

Example

<Quality>Suspect</Quality>

Custodian

The Custodian element can be used to specify any custodian details that need to be included with the dataset. This element is very flexible as it contains any number of Property child elements. The Property element can be used to assign a property name and value.

Child Elements:

Element	Type	Number	Description
Property	Required	1 or more	Used to identify a property and its value.

Example

<Property name="Agency">Australian Oceanographic Data Centre</Property>

<Property name="WebSite">http://www.metoc.gov.au</Property>

</Custodian>

QCDetails

The QCDetails element is an optional child element of MarineDataSet. It encases four optional child elements which can be used to describe any tests or processes performed on the data, any flags assigned to the data or edits performed on the data. The QCDetails element does not have to be utilised, however it is a very easy way to contain all of the quality control history of the dataset under the one element.

Attributes:

Name	Value	Use	Description
agency	String	Optional	The name of the agency performing the quality control.
operator	String	Optional	The name of the operator doing the quality control.
date	String	Optional	The date the file was last quality controlled. Although this attribute can be any string value, the suggested date/time format is the ISO8601 standard.
status	Complete \| Partial \| Unprocessed	Required	A statement on the status of the dataset; whether the file has been processed, partially quality controlled or the quality control is complete.

Child Elements:

Element	Type	Number	Description
Tests	Optional	0 or 1	Used to outline any quality control tests performed on the data.
Processes	Optional	0 or 1	Used to outline any quality control processes performed.
Flags	Optional	0 or 1	Used to describe any flagging systems used on the data.
Edits	Optional	0 or 1	Used to track any edits performed on the data.

Example

<Tests>

<Test................/>

</Tests>

<Process.........../>

</Processes>

<Flags>

<FlagSet............/>

</Flags>

<Edits>

<EditedValue....../>

</Edits>

</QCDetails>

Tests, Test and Result

The Tests element is used to encase a series of Test child elements. Each Test child element outlines the name of the test and what Marine XML fields the test applies to. The Test element also has any number of optional Result child elements which can be used to specify any results associated with the test.

Tests

Child Elements:

Element	Type	Number	Description
Test	Required	1 or more	Used to outline an individual test.

Test

Attributes:

Name	Type	Use	Description
name	String	Required	Name of the quality control test performed.
field	String	Required	Name of the fields the test was performed on.
details	String	Optional	Any details pertaining to the quality control test.

Child Elements:

Element	Type	Number	Description
Result	Optional	0 or more	Used to outline the results of a test for a particular MarineDataRecord.

Result

Attributes:

Name	Type	Use	Description
recordID	Non-negative integer	Required	The record index the result applies to.
details	String	Required	Any details describing the result.

Examples

Example 1:

<Tests>

</Tests>

Example 2:

<Tests>

</Test>

</Tests>

Processes and Process

The Processes element is used to encase a series of Process child elements. Each individual Process element can be used to outline details of any quality control process performed on the data.

Processes

Child Elements:

Element	Type	Number	Description
Process	Required	1 or more	Used to outline a quality control process.

Process

Attributes:

Name	Type	Use	Description
name	String	Required	Name of the process.
details	String	Required	Details of the process.

Example

</Processes>

Flags and FlagSet

The Flags element is used to encase a series of FlagSet child elements. Each FlagSet element can be used to define a set of quality control flags that have been assigned within the dataset.

Flags

Child Elements:

Element	Type	Number	Description
FlagSet	Required	1 or more	Used to define a quality control flag set.

FlagSet

This element contains free text, where the individual flag set can be defined.

Attributes:

Name	Type	Use	Description
name	String	Required	Define the name of a set of flags. This name can be referenced as the name of a parameter when attaching flags to the data.

Example

<Flags>

<FlagSet name="AODC Quality Control Flags Version 1.0">0=Original; 1=Corrected; 2=Suspect; 3=Erroneous;</FlagSet>

</Flags>

Edits and EditedValue

The Edits element is used to encapsulate a series of individual edits performed on the data as EditedValue child elements. Each EditedValue element can capture information on the index of the record edited, the date of the edit, the editor, the Marine XML object edited, the name of the parameter/object edited, the previous value and the reason for the edit.

Edits

Child Elements:

Element	Type	Number	Description
EditedValue	Required	1 or more	Used to capture individual edit details.

EditedValue

Attributes:

Name	Type	Use	Description
recordID	Non-negative integer	Required	The index of the record containing the edit.
date	String	Required	The date the edit was performed. Although this attribute can be any string value the suggested date/time format is the ISO8601 standard.
editedBy	String	Required	The person who edited the record.
object	String	Required	The name of the Marine XML object edited.
field	String	Required	The name of the parameter/object edited.
dataObjectIndex	Non-negative integer	Optional	If data edited, use attribute to specify the index of the DataObject.
parameterIndex	Non-negative integer	Optional	If data edited, use attribute to specify the index of the Parameter.
parameterSet	Non-negative integer	Optional	If data edited and data specified as a list, can specify the ParameterSet.
previousValue	String	Required	The previous value of the parameter/object.
reason	String	Required	The reason for performing the edit.

Examples

Example 1:

<Edits>

</Edits>

This type of edit would be used to track an edit on the following data object:

<Data>

</Parameter>

</Data>

Example 2:

<Edits>

</Edits>

This type of edit would be used to track an edit on the following data object in the first parameter of the fifth value set in the contents of the ValueList element.

<Data>

</ParameterSet>

</DataObject>

</Data>

Property

The Property element is a flexible element used to encase any property.

Attributes:

Name	Type	Use	Default
name	String	Required	Name of the property being described.

Example

<Property name="Contact">Elwood Blues</Property>

ENCODING AN INDIVIDUAL RECORD

MarineDataRecord

The MarineDataRecord element is used to encapsulate a group of data that has the same spatial and temporal reference. You have the option to assign a quality value to the MarineDataRecord along with any number of properties you may wish to outline. The MarineDataRecord element must contain the four children elements, SpatialReference, TemporalReference, Source and Data, in order.

Child Elements:

Element	Type	Number	Description
Quality	Optional	0 or 1	Used to capture the quality of the data contained within the individual record. Suggested list of valid values for this attribute are defined in Table 2.
Property	Optional	0 or more	Used to outline any properties pertaining to the record.
SpatialReference	Required	1	Used to define the spatial reference of the record.
TemporalReference	Required	1	Used to define the temporal reference of the record.
Source	Required	1	Used to outline the source of the data.
Data	Required	1	Used to encapsulate all of the data for an individual record.

Attributes:

Name	Type	Use	Description
ID	Non-negative integer	Required	The index of the MarineDataRecord element.
reject	true \| false	Required	This attribute can be set to true if you wish to flag the entire record as a reject.

ENCODING SPATIAL DATA

SpatialReference

The SpatialReference element is used to define the spatial extent of the record. It may contain a quality element to define the quality of the spatial reference. The spatial reference can be defined by a point, box, line or polygon.

Child Elements:

Element	Type	Number	Description
Quality	Optional	0 or 1	Used to capture the quality of the data contained within the individual record. Suggested list of valid values for this attribute are defined in Table 2.
GeoPoint	Choice of	1	Used to specify a single point in space.
GeoBox		1	Used to specify a box region.
GeoLine		1	Used to specify a line.
GeoPolygon		1	Used to specify a polygon.

GeoPoint

The GeoPoint element has one child element that specifies the coordinates of the point.

Child Element:

Element	Type	Number	Description
Coordinates	Required	1	Used to specify the spatial coordinates of the point.

GeoBox

The GeoBox element is used to specify a spatial region that takes the shape of a box. It must contain two child Coordinates elements which specify the opposite corners of the box.

Child Elements:

Element	Type	Number	Description
Coordinates	Required	2	Used to specify the spatial coordinates of the opposite corners of the box.

GeoLine

The GeoLine element is used to specify a spatial extent extending along a line. It must contain 2 or more child Coordinates elements to specify the line.

Child Elements:

Element	Type	Number	Description
Coordinates	Required	2 or more	Used to specify the coordinates of the line.

GeoPolygon

The GeoPolygon is used to specify a spatial extent in the shape of a polygon. This consists of an OuterBoundaryIs and any number InnerBoundaryIs elements, all of which are specified by a LinearRing child element.

Child Elements:

Element	Type	Number	Description
OuterBoundaryIs	Required	1	Used to define the outer boundary of the polygon.
InnerBoundaryIs	Optional	0 or more	Used to define any individual inner boundaries of the polygon.

OuterBoundaryIs

Child Elements:

Element	Type	Number	Description
LinearRing	Required	1	Used to define the outer boundary coordinates.

InnerBoundaryIs

Child Elements:

Element	Type	Number	Description
LinearRing	Required	1	Used to define the inner boundary coordinates.

LinearRing

A LinearRing element is used to define a OuterBoundaryIs or a InnerBoundaryIs. It consists of 4 or more child Coordinates elements to define the ring.

Child Elements:

Element	Type	Number	Description
Coordinates	Required	4 or more	Used to specify the coordinates of the linear ring.

Coordinates

The Coordinates element is used to define the coordinates of a single point in space. It was decided that the coordinates element would contain child elements Latitude and Longitude for describing marine spatial data. There is also an option to include a Depth or Altitude child element if required.

Child Elements:

Element	Type	Number	Description
Latitude	Required	1	Used to specify the latitude.
Longitude	Required	1	Used to specify the longitude.
Depth	Optional / Choice of	0 or 1	Used to specify the depth.
Altitude	Optional / Choice of	0 or 1	Used to specify the altitude.

Attributes:

Name	Type	Use	Description
datum	String	Required	Used to define the datum used for the latitude and longitude measurements.

Latitude

This element encases the decimal value of the latitude of the record. The precision used is up to the user. It is suggested to use a value to at least six significant figures.

Negative latitudes southern hemisphere.

Positive latitudes northern hemisphere.

Longitude

This element encases the decimal value of the longitude of the record. The precision used is up to the user. It is suggested to use a value to at least six significant figures.

Negative longitudes western hemisphere.

Positive longitudes eastern hemisphere.

Depth

This is an optional element. If depth is required as part of the spatial coordinates for the record then this element should be used. The depth element encases the decimal value of the depth. Attributes are used to assign datum and unit information. The Depth and Altitude elements cannot both be specified.

Attributes:

Name	Type	Use	Description
datum	String	Required	Used to specify the datum used to determine the depth.
units	String	Required	Used to specify the units of the depth measurement. Suggested unit of measurement is "Metres".

Altitude

This is an optional element. If altitude is required as part of the spatial coordinates for the record then this element should be used. The altitude element encases the decimal value of the altitude. Attributes are used to assign datum and unit information. The Depth and Altitude elements cannot both be specified.

Attributes:

Name	Type	Use	Description
datum	String	Required	Used to specify the datum used to determine the depth.
units	String	Required	Used to specify the units of the depth measurement. Suggested unit of measurement is "Metres".

ENCODING TEMPORAL DATA

TemporalReference

The TemporalReference element is used to specify the temporal extent of a record. It may contain a Quality element to specify the quality of the temporal information. It then may contain either an Instant element, to specify an instant in time, or a Period element, to specify a period in time.

Child Elements:

Element	Type	Number	Description
Quality	Optional	0 or 1	Used to specify the quality of the temporal data.
Instant	Choice of	1	Used to specify a specific instant in time.
Period	Choice of	1	Used to specify a period in time.

Instant

The Instant element encapsulates a single Date element used to specify the date/time of the record. All of the attributes of the Date child elements are required when Date is a child of an Instant element.

Child Elements:

Element	Type	Number	Description
Date	Required	1	Used to specify the date and time.

Date

The Date element uses attributes to specify the date and time. Each of the attributes are optional. This has been done to allow flexibility when defining cyclic, non-continuous periods. Examples of this are illustrated with the Period element.

Attributes:

Name	Type	Description
year	Non-negative integer	Specify year value. Should be non-negative integer.
month	Non-negative integer	Specify month value. Between 1 and 12.
day	Non-negative integer	Specify day value. Between 1 and 31.
hour	Non-negative integer	Specify hour value. Between 0 and 23.
minute	Non-negative integer	Specify minute value. Between 0 and 59.
second	Non-negative integer	Specify second value. Between 0 and 59.
timeZone	String	Specify time zone. Values and format for the time zone entry should be concurrent with Table 3.

Please note, that when specifying Date as a child of an Instant element all of the attributes are required, otherwise they are optional.

Period

The Period element can be used in a variety of ways. You may specify a continuous period with specific instants in time for both the start and end of the period. You may also specify periodical periods which have start and end dates, and various sub-periods in-between. Examples follow to illustrate the various uses of this element.

Child Elements:

Element	Type	Number	Description
Start	Required	1	Used to specify the start of the period.
Period	Optional	0 or more	Used to specify any internal periods.
End	Required	1	Used to specify the end of the period.

Attributes:

Name	Type	Use	Description
type	Continuous \| Periodical	Optional	Used to specify whether the period is "continuous" or "periodical". This attribute should only be used in the outermost Period element.

Start

The Start element can be used to specify an Instant or a Date element. The Instant element would be used if the start of the period is a specific instant in time. The Date element would be used if for example, you only wanted to specify the start of the period as a year.

Child Elements:

Element	Type	Number	Description
Instant	Choice of	1	Used to specify an instant in time.
Date	Choice of	1	Used to specify a date. Could be year, year and month, etc.

End

The End element can be used to specify an Instant or a Date element. The Instant element would be used if the end of the period is a specific instant in time. The Date element would be used if you only wanted to specify the end of the period as a year, for example.

Child Elements:

Element	Type	Number	Description
Instant	Choice of	1	Used to specify an instant in time.
Date	Choice of	1	Used to specify a date. Could be year, year and month, etc.

Examples

Example 1: A continuous period.

This example defines a continuous period from 1/1/1995 00:00:00 to 31/12/2001 23:59:59.

<Start>

</Instant>

</Start>

<End>

</Instant>

</End>

</Period>

Example 2: A periodical period.

This example defines the period, all March, April and May data between 1995 and 2001.

<Start>

</Start>

<Start>

</Start>

<End>

<End>

</Period>

<End>

</End>

</Period>

ENCODING THE DATA SOURCE DETAILS

Source

The Source element is used to specify details relating to the source of the data. Attributes allow details such as source file name, agency and project identification numbers to be assigned. It contains a child element, Platform, which can be used to assign the details of the platform the observations were taken from.

Child Elements:

Element	Type	Number	Description
Platform	Optional	0 or 1	Used to specify platform details.

Attributes:

Name	Type	Use	Description
isObservedData	true \| false	Required	Set to true if observations were observed.
sourceFileName	String	Required	The original file name and location.
agency	String	Required	The agency collecting the data.
projectID	String	Required	The project ID.

Platform

Attributes:

Name	Type	Use	Description
type	String	Required	Suggested values of the type of platform could be "Marine", "Land", "Aerial".
name	String	Required	The name associated with the platform.
identifier	String	Required	The identifier of the platform.

Examples

</Source>

ENCODING MARINE DATA

Data

The Data element encases any number of DataObject child elements which contain the data, along with information on the parameter measured and the sensor used.

Child Elements:

Element	Type	Number	Description
DataObject	Required	1 or more	Used to encapsulate one observation or a series of observations, along with parameter and sensor details.

Attributes:

Name	Type	Use	Description
numberOfDataObjects	Non-negative integer	Required	The number of DataObject elements encased within the Data element.

DataObject

Each DataObject element can be used to encapsulate data for one parameter or a series of parameters. This allows flexibility in the way in which data is represented within the XML structure. It is most idyllic to create one DataObject per parameter. This can be impractical where a large number of related observations are observed for each record. In this case using individual DataObject elements can make the file size become excessive. Examples of the various ways the DataObject element can be used to represent data follow.

Child Elements:

Element	Type	Number	Description
Quality	Optional	0 or 1	Specify the quality of the observations within the DataObject.
Parameter	Choice of	1 or more	Specify individual parameters, their sensor (optional) and value.
ParameterSet	Choice of	1 or more	Specify a set of parameters, the sensor (optional) and individual values or value list.

Attributes:

Name	Type	Use	Description
index	Non-negative integer	Required	The index of the DataObject within the Data element.
name	String	Optional	A name associated with the DataObject.
type	Primary \| Ancillary	Required	Used to set the data type as the primary observed data or as ancillary data.
numberOfParameters	Non-negative integer	Optional	The number of parameters encased within the DataObject.
numberOfParameterSets	Non-negative integer	Optional	The number of parameter sets encased within the DataObject.
reject	true \| false	Required	Set whether the data within this DataObject should be rejected.

Parameter

This element is used to identify the parameter, units of measurement, sensor and data value.

Child Elements:

Element	Type	Number	Description
Sensor	Optional	0 or 1	Used to encapsulate the sensor used to measure the parameter.
Value		0 or 1	Used to encapsulate the value of the parameter.

Please note that if Parameter is a direct child of a DataObject element then the child element of Parameter, Value is compulsory. However if Parameter is a direct child of a ParameterSet element then the child element of Parameter, Value is optional, as the values may be specified as a ValueList element.

Attributes:

Name	Type	Use	Description
index	Non-negative integer	Required	The index of the Parameter element under the DataObject element.
name	String	Required	The name of the parameter. It is advised that the name used comes from a set of valid parameter names in Table 4.
units	String	Required	The units the parameter was measured in. It is advised that the units used comes from the standard accepted units in Table 5.

Sensor

This element is used to encapsulate the details of the sensor used to measure the parameter.

Attributes:

Name	Type	Use	Description
name	String	Required	The name of the sensor.
model	String	Optional	The model of the sensor.
description	String	Optional	A description of the sensor.

Value

This element is a child of the Parameter element only and contains free text of the value. Use of this element is illustrated in Example 1 and 2 below.

ParameterSet

This element is used to encapsulate a series of related parameters usually measured by the same sensor. In this case the data can be represented as a comma separated list or specified as individual values. The most common use of this element would be to encapsulate profile data.

Attributes:

Name	Type	Use	Description
index	Non-negative integer	Required	The index of the ParameterSet element under the DataObject element.
numberOfParameters	Non-negative integer	Required	The number of parameters encapsulated by the ParameterSet element.

Child Elements:

Element	Type	Number	Description
Sensor	Optional	0 or 1	Used to encapsulate the sensor used to measure the parameter.
Parameter	Required	1 or more	Used to define the parameters measured. In this case do not use the child elements of Parameter to specify the sensor or the value.
ValueList	Optional	1	This is a list of observed values for each of the parameters.

ValueList

- Non-XBT data

This element is a child of the ParameterSet element only. The list of values should be made up of a series of sets of values for each parameter (in the order of the parameter indexes), separated by a comma. Each set of values should be separated by a space. This is best illustrated by an Example 3 below.

Attributes:

Name	Type	Use	Description
numberOfValueSets	Non-negative integer	Required	The number of values sets contained within the value list.

- XBT data

For XBT data only instead of storing all values on 1 line, values are encoded at each depth over multiple lines. A child element of 'ValueList' called 'Values' is used to encode the parameters at each depth. See Example 4 below.

Attributes:

Name	Type	Use	Description
index	Non-negative integer	Required	The index number for the depth

Examples:

Example 1: Using Parameter to specify simple point data.

The following code specifies a Sea Surface Temperature of value 25.3 degrees Celsius.

</Parameter>

</DataObject>

</Data>

Example 2: Using Parameter to specify simple point data and a flag value.

The following code specifies a Sea Surface Temperature of value 25.3 degrees Celsius with flag 3.

</Parameter>

</Parameter>

</DataObject>

</Data>

Example 3: (Non-XBT data) Using ParameterSet to specify a sound velocity-depth profile. The sound velocity profile is encoded in 1 line in the element ValueList.

The following code specifies 4 depths and sound speeds as shown in the table

Depth	Sound Velocity
0	1541.3
5	1541.4
10	1541.6
15	1541.4

</ParameterSet>

</DataObject>

Example 4: (XBT data only). Temperature profile is encoded over multiple lines (485) using the child element 'Values'.

<............................................................>

</ValueList>

</ParameterSet>

</DataObject>

APPENDIX A Date/Time ISO8601 Standard

TABLES OF VALID VALUES

Table 1 caveat

Unclassified

Classified

Restricted

Secret

Top Secret

Table 2 Quality

Good

Suspect

Bad

Unknown

Table 3 timeZone

Table 4 Parameter Names

Table 5 Standard Units