XML Markup for Joint Meteorology and Oceanography Grid Segment

JMGRIB is an application of XML to describe a set of gridded data, which are packed in GRIB records.

Revision: 1.5

Introduction
GRIB meta-data
Defined GRIB parameters
Encapsulating GRIB records
Examples
References

Introduction

World Meteorological Organization (WMO) has developed a format for efficient transmission of gridded data, which is a set of floating-point values sampled over a two-dimensional grid. This format, GRIB, is described in FM 92-IX Ext. GRIB [FM92-IX]. GRIB is a compact data format. However, it is difficult to decode. Without a sophisticated decoder -- and a set of appropriate tables -- an application cannot even determine which quantity is being represented in a GRIB record, let alone access the values of the quantity at particular grid points. JMGRIB has been developed to let an application access at least the meta-information about the grid without resorting to a decoder. JMGRIB also includes a format that describes both meta-data and the data in XML form. When the number of grid points is small, this is the most convenient format as an application needs no GRIB decoder and no knowledge of the GRIB format.

JMGRIB defines a collection of elements that can be combined by a user into one of four formats. Three formats -- raw, encoded, and expanded -- are intended for gridded data with a large number of values. In this case, annotating each grid point is unfeasible. The forth, a grid-point format, is to represent a small set of data points on possibly irregular multi-dimensional grid. The latter format is the most convenient for an application program as this program can access any data value without the help of a GRIB decoder. The first three formats require the understanding of a GRIB record.

The raw, encoded, and expanded formats all have the same header. The header contains meta-data about a GRIB record. They describe and identify gridded data and the grid itself. The formats differ in representing the grid data themselves. The raw format refers to an external GRIB record. The encoded format encapsulates the whole GRIB record, which is transformed into ASCII using a BASE64 encoding. This procedure is similar to the encapsulation of binary attachments into an ASCII e-mail message. In both cases an application requires a GRIB decoder to obtain grid data. Still, the application can use the information in the JMGRIB header to decide if a particular GRIB record is of interest without decoding the record.

The expanded format carries the grid point data as floating-point numbers in ASCII representation. The numbers are separated with a single whitespace. They are listed exactly in the same order the corresponding data points occur in the Binary Data Section of the GRIB record. The precision of the values is consistent as well. Although an application is spared decoding variable-bitlength packing of the Binary Data Section, an application needs to know enough about GRIB to make sense of the stream of numbers. The application needs to refer to a JMGRIB header for information on grid dimensions, a scanning order, units of measure, and other parameters.

GRIB meta-data

This section defines XML elements that represent the meta-data of a GRIB record.

Time attributes

baseTime
	The calendar timestamp of the gridded data	datetime NMTOKEN
	A full or abbreviated ISO UTC timestamp, of the moment data have been computed or measured. The base time for an analysis model is the valid time of the analysis. The base time for a forecast model is the reference time from which all forecasts are based. GRIB PDS Octets 13-17 ddds counter: 47400 Example: 2001-04-17T1457, 20010813 The attribute is required

forecastPeriod
	Time difference between the forecast time and the BaseTime	time interval or omitted NMTOKEN
	measured in hours GRIB PDS Octet 19 ddds counter: 36830 Domain expr: `-024 .. 4320` hours

insertTime
	The calendar timestamp of insertion into a database	datetime or omitted NMTOKEN
	A full or abbreviated ISO timestamp the grid was cataloged in the database or sent to a client

<!ENTITY % Times "
	baseTime NMTOKEN #REQUIRED
	forecastPeriod NMTOKEN #IMPLIED
	insertTime NMTOKEN #IMPLIED
">

Latitude and Longitude attributes

Lat
	Latitude	number(11) NMTOKEN
	in Degrees; negative in the Southern hemisphere Domain expr: `-90.0 .. 90.0` The attribute is required

<!ENTITY % Lat "NMTOKEN #REQUIRED">

Lon
	Longitude	number(12) NMTOKEN
	in Degrees; negative in the Western hemisphere Domain expr: `-180.0 .. 180.0` The attribute is required

<!ENTITY % Lon "NMTOKEN #REQUIRED">

GribDesc element

This is the root element of the JMGRIB header. It encloses all meta-information about a GRIB record.

	XML DTD
	<!ELEMENT GribDesc (Center, Model, Parameter, Layer, Projection, Data)>

Attributes

`Times`

GRIBVer
	GRIB format version	char(1) NMTOKEN
	Edition of the GRIB format Domain expr: 1 FM92-IX, aka GRIB I[FM92-IX] 2 FM92-XII, aka GRIB II[FM92-XII]

<!ATTLIST GribDesc
	%Times;
	GRIBVer NMTOKEN '1'
>

Center element

Originating center identification

	XML DTD
	<!ELEMENT Center EMPTY>

Attributes

centerSubcenterId
	Code that represents an organization and a division that produced the grid	char(6) NMTOKEN
	The organization identifier -- either three or 6 digits -- should be the concatenated WMO center and sub-center identifiers (WMO code table 0, common code table c-1). The subcenter identifier may be dropped if not used (zero). If not available the DoD unit identification code may be used. Example: `058` -- Fleet Numerical Meteorology and Oceanography Center

description
	Description of the originating center	char(255) or omitted CDATA

<!ATTLIST Center
	centerSubcenterId NMTOKEN #REQUIRED
	description CDATA #IMPLIED
>

Model element

Identification of a process that created the gridded data.

	XML DTD
	<!ELEMENT Model EMPTY>

Attributes

id
	The identifier of a computer process that generated the grid	char(3) NMTOKEN
	This is a generating process ID number, which is allocated by the originating center. It can be found in Octet 6 of the PDS Section of a GRIB record. Example: `058` -- NOGAPS model at FNMOC

description
	Description of the model	char(255) or omitted CDATA
	Example: `NOGAPS`

<!ATTLIST Model
	id NMTOKEN #REQUIRED
	description CDATA #IMPLIED
>

Parameter element

An environmental parameter

	XML DTD
	<!ELEMENT Parameter EMPTY>

Attributes define a parameter, see GRIB Table 2.

Attributes

code
	The code that denotes a type of the environmental parameter.	char(4) ID
	The code is formed by prepending a letter 'P' to the code in the WMO code table 0291. The code numbers greater than 127 are defined by the originating center. The code number is carried in PDS Octet 9. ddds counter: 36443 Example: P011 -- stands for temperature Domain expr: `P001 .. P254`

description
	The text that describes the environmental parameter	char(256) CDATA

units
	The units of measure	char(35) NMTOKEN
	GRIB Table 2 for GRIB I and Table 4.2 in GRIB II Example: `m` , `K` , `Pa`

<!ATTLIST Parameter
	code ID #REQUIRED
	description CDATA #REQUIRED
	units NMTOKEN #REQUIRED
>

Layer element

Geophysical layer to which the gridded data pertain.

	XML DTD
	<!ELEMENT Layer EMPTY>

Attributes

code
	Geophysical layer identifying code	char(3) NMTOKEN
	This is the code typically found in PDS octet 10. It is described in GRIB Table 3.

typeCode
	The code that denotes the type of the geophysical layer.	char(1) NMTOKEN
	Domain expr: 1 Pressure (hectopascals) 2 Height (meters) 3 Sigma (0.001 to 1.000) 4 Depth (meters, towards center of earth is positive) 5 Hybrid 6 Other

lower
	The level quantity at the bottom of the layer.	decimal or omitted NMTOKEN
	The units of measure depend on the layer typecode, above. When describing a level, the upper and the lower quantities are the same -- and the lower quantity will be omitted. ddds counter: 36511

upper
	The level quantity at the top of the layer.	decimal or omitted NMTOKEN
	The units of measure depend on the layer typecode, above. When describing a level, the upper and lower quantities are the same. ddds counter: 36511

<!ATTLIST Layer
	code NMTOKEN #REQUIRED
	typeCode NMTOKEN '1'
	lower NMTOKEN #IMPLIED
	upper NMTOKEN #IMPLIED
>

Projection element

JMGRIB deals only with regular, square, dense grids. Thinned (quasi-regular) and bitmaps are not supported.

The Projection element describes the projection and the grid. This element roughly corresponds to the Grid Description Section (GDS) of a GRIB record.

	XML DTD
	<!ELEMENT Projection (Proj-Mercator \| Proj-LatLon \| Proj-LambertConf)>

Attributes

code
	Projection code per GRIB Table 6	integer or omitted NMTOKEN
	It is the content of GDS Octet 6

name
	The name of the projection	char(48) or omitted NMTOKEN
	Example: Mercator, Polar-Stereographic

maxRows
	The number of points along the y-axis	number(15) NMTOKEN

maxColumns
	The number of points along the x-axis	number(15) NMTOKEN

gridID
	Grid Identifier, PDS Octet 7 and GRIB Table B	smallint or omitted NMTOKEN

earthShape
	The code that denotes the geometrical shape that is used to model the Earth	char(1) NMTOKEN
	GRIB I table 7 uses codes 0 and 2 if bit 2 is set. GRIB II uses code Table 3.2. ddds counter: 36483 Domain expr: 0 -- Earth is assumed spherical with a radius of 6367.47 km 1 -- See GRIB II Table 3.2 2 -- Earth is assumed oblate spherical with size 6378.160 km and 6356.775 with f=1/297.0 (IAU Standard from 1965) 3 -- See GRIB II Table 3.2

vectorComponent
	The code denoting the orientation of vector components in a grid field	char(1) NMTOKEN
	GRIB I Table 7, bit 5 Domain expr: 0 -- resolved components of vector quantities relative to easterly and northerly directions 1 -- u and v components of vector quantities resolved relative to the defined grid in the direction of increasing x and y (or i and j) coordinates respectively

scanCode
	Point scan sequence code	char(1) NMTOKEN
	The code that denotes the row versus column sequence order of a grid array. See GRIB Table 8 and GDS Octet 28. `I` direction is defined as west to east along a parallel of latitude, or left to right along an x axis. `J` direction is defined as south to north along a meridian of longitude, or bottom to top along a y axis. Domain expr: `I` -- Adjacent points in I direction are consecutive (incremented first) `J` -- Adjacent points in J direction are consecutive (incremented first)

firstPoint
	The code that tells in which corner the first point lies	char(2) NMTOKEN
	The code that designates the corner point, within the grid corresponding to the first point, relative to a Cartesian coordinate system. This code is related to the +i/-i and +j/-j scanning orders, bits 1 and 2 of GDS Octet 28, GRIB Table 8. Domain expr: `LL` -- lower left `LR` -- lower right `UL` -- upper left `UR` -- upper right

<!ATTLIST Projection
	code NMTOKEN #IMPLIED
	name NMTOKEN #IMPLIED
	maxRows NMTOKEN #REQUIRED
	maxColumns NMTOKEN #REQUIRED
	gridID NMTOKEN #IMPLIED
	earthShape NMTOKEN '0'
	vectorComponent NMTOKEN '1'
	scanCode NMTOKEN #REQUIRED
	firstPoint NMTOKEN #REQUIRED
>

Latitude-Longitude Grid

Latitude-Longitude Grid is also called Equidistant-Cylindrical or Plate Carree projection grid.

	XML DTD
	<!ELEMENT Proj-LatLon EMPTY>

Attributes

latFirst
	Latitude of the first grid point	Lat

lonFirst
	Longitude of the first grid point	Lon

latLast
	Latitude of the last grid point	Lat

lonLast
	Longitude of the last grid point	Lon

latIncr
	Latitudinal direction increment	number or omitted NMTOKEN
	in degrees latitude

lonIncr
	Longitudinal direction increment	number or omitted NMTOKEN
	in degrees longitude

<!ATTLIST Proj-LatLon
	latFirst %Lat;
	lonFirst %Lon;
	latLast %Lat;
	lonLast %Lon;
	latIncr NMTOKEN #IMPLIED
	lonIncr NMTOKEN #IMPLIED
>

Mercator Grid

Mercator grid is a conformal cylindrical projection grid.

	XML DTD
	<!ELEMENT Proj-Mercator EMPTY>

Attributes

latFirst
	Latitude of the first grid point	Lat

lonFirst
	Longitude of the first grid point	Lon

latLast
	Latitude of the last grid point	Lat

lonLast
	Longitude of the last grid point	Lon

latStandard
	Latin - The latitude(s) at which the Mercator projection cylinder intersects the earth.	Lat

latIncr
	Latitudinal direction increment	number or omitted NMTOKEN
	The direction increment is in units of meters, at the circle of latitude specified by `latStandard` .

lonIncr
	Longitudinal direction increment	number or omitted NMTOKEN
	The direction increment is in units of meters, at the circle of latitude specified by `latStandard` .

<!ATTLIST Proj-Mercator
	latFirst %Lat;
	lonFirst %Lon;
	latLast %Lat;
	lonLast %Lon;
	latStandard %Lat;
	latIncr NMTOKEN #IMPLIED
	lonIncr NMTOKEN #IMPLIED
>

Lambert-Conformal Grid

Lambert-Conformal grid is a conformal conic projection grid.

	XML DTD
	<!ELEMENT Proj-LambertConf EMPTY>

Attributes

latFirst
	Latitude of the first grid point	Lat

lonFirst
	Longitude of the first grid point	Lon

lonOrientation
	The orientation of the grid	Lon
	According to the GRIB specification, this is the east longitude value of the meridian which is parallel to the y-axis (or columns of the grid) along which latitude increases as the y-coordinate increases. The orientation longitude may, or may not, appear within a particular grid.

latStandard1
	Latin1 - The first latitude from the pole at which the secant cone cuts the spherical earth.	Lat

latStandard2
	Latin2 - The second latitude from the pole at which the secant cone cuts the spherical earth.	Lat
	If Latin 1 is the same as Latin 2 then the projection is on a tangent cone.

pole
	The polarity of the projection	enum (North \| South \| Both)
	Domain expr: `North` - the North pole is on the projection plane `South` - the South pole is on the projection plane `Both` - the projection is bipolar and symmetric

latSouthernPole
	Latitude of southern pole	Lat

lonSouthernPole
	Longitude of southern pole	Lon

xIncr
	The X-direction grid length	number or omitted NMTOKEN
	The grid length is in units of meters, at the intersection latitude circle nearest to the pole in the projection plane.

yIncr
	The Y-direction grid length	number or omitted NMTOKEN
	The grid length is in units of meters, at the intersection latitude circle nearest to the pole in the projection plane.

<!ATTLIST Proj-LambertConf
	latFirst %Lat;
	lonFirst %Lon;
	lonOrientation %Lon;
	latStandard1 %Lat;
	latStandard2 %Lat;
	pole (North | South | Both) 'North'
	latSouthernPole %Lat;
	lonSouthernPole %Lon;
	xIncr NMTOKEN #IMPLIED
	yIncr NMTOKEN #IMPLIED
>

Data Element

Description of the data values: scale factors, minimum and maximum values, etc. The element corresponds to BDS Octets 0-11 and PDS Octets 27-28.

	XML DTD
	<!ELEMENT Data EMPTY>

Attributes

binScaleF
	The binary scale factor (E)	smallint or omitted NMTOKEN
	BDS Octets 5 and 6 Domain expr: `-128..127`

decScaleF
	The decimal scale factor (D)	smallint or omitted NMTOKEN
	PDS Octets 27 and 28

refValue
	Reference value: the minimum value within the grid (R)	float or omitted NMTOKEN
	BDS Octets 7-10

bitsPerV
	The number of bits into which a datum point is packed	smallint or omitted NMTOKEN
	BDS Octet 11

trailingBits
	Number of unused (padding) bits at the end of the BDS	smallint or omitted NMTOKEN
	bits 5-8 of BDS Octet 4. BDS is always filled to an even number of octets. Domain expr: `0 .. 15`

integerData
	A binary flag indicating if data values are integers	char(1) or omitted (integerData)
	bit 3 of BDS Octet 4

<!ATTLIST Data
	binScaleF NMTOKEN #IMPLIED
	decScaleF NMTOKEN #IMPLIED
	refValue NMTOKEN #IMPLIED
	bitsPerV NMTOKEN #IMPLIED
	trailingBits NMTOKEN #IMPLIED
	integerData (integerData) #IMPLIED
>

As the GRIB document specifies, the representation of a single value is such that:

Y x 10^D = R + (X x 2^E)

where

Y = original or unpacked value; units as in Table 2;
D = decimal scale factor, to achieve desired precision, a signed 16-bit integer
R = reference 32-bit floating-point value
X = internal value, bitsPerV bits long
E = binary scale factor for variable bit word length packing, a signed 16-bit integer

The reference value (R) is the minimum value of the (possibly) decimally scaled data that is being encoded.

Defined GRIB parameters

A collection of GRIB parameters

	XML DTD
	<!ELEMENT Parameters (Parameter*)>

	XML DTD
	<!ENTITY Grib-Parameters " <Parameters><Parameter code="P001" description="Pressure" units="Pa"> <Parameter code="P011" description="Temperature" units="K"> </Parameters> ">

Encapsulating GRIB records

GribRef element

GribRef -- a reference to an external GRIB record

	XML DTD
	<!ELEMENT GribRef EMPTY>

Attributes

href
	URI of a GRIB record	char(512) CDATA
	The URI may denote either a static or a dynamic resource.

<!ATTLIST GribRef
	href CDATA #REQUIRED
>

GribRecord element

GribRecord -- a GRIB record, BASE64-encoded

	XML DTD
	<!ELEMENT GribRecord (#PCDATA)>

GribValues element

GribValues contains a sequence of whitespace-separated IEEE floating-point numbers in the text format. The numbers represent gridded values, in the same order as they appear in the Binary Data Section of a GRIB record. A NaN can be used to represent "missing" values.

	XML DTD
	<!ELEMENT GribValues (#PCDATA)>

Pt element

Pt -- a single datum on a 5-dimensional grid

	XML DTD
	<!ELEMENT Pt EMPTY>

Attributes

LatLon
	Latitude and Longitude for the data point	char(35) NMTOKENS

parID
	The code that denotes the type of the environmental parameter.	char(4) IDREF
	Foreign key, refers to `Parameter.code`

v
	The value(s) of the datum	number NMTOKENS

<!ATTLIST Pt
	LatLon NMTOKENS #REQUIRED
	parID IDREF #REQUIRED
	v NMTOKENS #REQUIRED
>

Examples

A grib-raw XML document

An example of a grib-raw document. It contains an internal DTD subset, which combines elements defined in JMGRIB.dtd to make the root element.

     <!DOCTYPE EX-GR SYSTEM 'JMGRIB.dtd' [
        <!ELEMENT EX-GR (GribDesc, GribRef)>
     ]>
     <EX-GR>
       <GribDesc baseTime='1996-10-18T1200'>
         <Center centerSubcenterId='058'
                 description='US Navy  - Fleet Numerical Oceanography Center'/>
         <Model id='070'/>
         <Parameter code='P011' description='Temperature' units='K'/>
         <Layer code='105' typeCode='2' upper='2'/>
         <Projection code='0' name='Equidistant-Cylindrical'
                     gridID='242' maxRows='105' maxColumns='133'
                     vectorComponent='1' scanCode='I'
                     firstPoint='LL'>
           <Proj-LatLon latFirst='4' lonFirst='92' latLast='56'
                        lonLast='158' latIncr='0.5' lonIncr='0.5'/>
         </Projection>
         <Data binScaleF='0' decScaleF='1' refValue='2637.6807'
               bitsPerV='9' trailingBits='3' />
       </GribDesc>
       <GribRef href='A07G000.grib'/>
     </EX-GR>

A grib-encoded XML document

Refer to [JMGRIB-enc] for the complete example.

     <!DOCTYPE EX-GE SYSTEM 'JMGRIB.dtd' [
        <!ELEMENT EX-GE (GribDesc, GribRecord)>
     ]>
     <EX-GE>
       <GribDesc baseTime='1996-10-18T1200'>
         <Center centerSubcenterId='058'
                 description='US Navy  - Fleet Numerical Oceanography Center'/>
         <Model id='070'/>
         <Parameter code='P011' description='Temperature' units='K'/>
         <Layer code='105' typeCode='2' upper='2'/>
         <Projection code='0' name='Equidistant-Cylindrical'
                     gridID='242' maxRows='105' maxColumns='133'
                     vectorComponent='1' scanCode='I'
                     firstPoint='LL'>
           <Proj-LatLon latFirst='4' lonFirst='92' latLast='56'
                        lonLast='158' latIncr='0.5' lonIncr='0.5'/>
         </Projection>
         <Data binScaleF='0' decScaleF='1' refValue='2637.6807'
               bitsPerV='9' trailingBits='3' />
       </GribDesc>
       <GribRecord>
       QAwAAVJVS05XQwIBAABgChIMNgFCVEZOSFRKQTk4IEtOV0MgMTgxMjAwDQ0KR1JJQgA9sgEAABwC
       OkbygAtpAAJgChIMAAEAAAAAAAAUAAABAAAgAP8AAIUAaQAPoAFnYIAA2sACaTAB9AH0QAAAAAAA
       </GribRecord>
     </EX-GE>

A grib-expanded XML document

Refer to [JMGRIB-exp] for the complete example.

     <!DOCTYPE EX-GX SYSTEM 'JMGRIB.dtd' [
        <!ELEMENT EX-GX (GribDesc, GribValues)>
     ]>
     <EX-GX>
       <GribDesc baseTime='1996-10-18T1200'>
         <Center centerSubcenterId='058'
                 description='US Navy  - Fleet Numerical Oceanography Center'/>
         <Model id='070'/>
         <Parameter code='P011' description='Temperature' units='K'/>
         <Layer code='105' typeCode='2' upper='2'/>
         <Projection code='0' name='Equidistant-Cylindrical'
                     gridID='242' maxRows='105' maxColumns='133'
                     vectorComponent='1' scanCode='I'
                     firstPoint='LL'>
           <Proj-LatLon latFirst='4' lonFirst='92' latLast='56'
                        lonLast='158' latIncr='0.5' lonIncr='0.5'/>
         </Projection>
         <Data binScaleF='0' decScaleF='0' refValue='0'/>
       </GribDesc>
       <GribValues>
     301.4 301.7 302 302.2 302.4 302.6 302.1 301.1 299.8 297.2 ...
       </GribValues>
     </EX-GX>

A grid-point XML document

An example of a grid-point document. Two different quantities (Temperature and pressure) at two different points (36.5N 122.5W and 37.5N 122.5W) for one level (1013.5 isobar)

     <!DOCTYPE GribPoint SYSTEM 'JMGRIB.dtd' [
     <!ELEMENT GribPoint (Layer, Parameters, Pt*)>
     <!ATTLIST GribPoint %Times;>
     ]>
     <GribPoint BaseTime='2000-03-21T14-10' ForecastPeriod='0.25'>
       <Layer code='102' typecode='1' upper='1013.5'/>
       &Grib-Parameters;
       <Pt LatLon='36.5 -122.5' parID='P001' v='1000'/>
       <Pt LatLon='36.5 -122.5' parID='P011' v='300'/>
       <Pt LatLon='37.5 -122.5' parID='P001' v='1000'/>
       <Pt LatLon='37.5 -122.5' parID='P011' v='300'/>
     </GribPoint>

References

[FM92-IX] A Guide To The Code Form FM 92-IX Ext. GRIB
<http://www.wmo.ch/web/www/WDM/Guides/Guide-binary-2.html>

[FM92-XII] FM 92-XII GRIB General Regularly-distributed Information in Binary Form
<http://www.nws.noaa.gov/tdl/iwt/grib2/frameset_grib2.htm>

[JMGRIB.dtd] JMGRIB DTD
<JMGRIB.dtd>

[JMGRIB-raw] A sample grib-raw XML document
<JMGRIB-raw.xml>

[JMGRIB-enc] A sample grib-encoded XML document
<JMGRIB-enc.xml>

[JMGRIB-exp] A sample grib-expanded XML document
<JMGRIB-exp.xml>

[Sample-GRIB] A sample GRIB file used in this document's examples
<A07G000.grib>

[GRIB-to-JMGRIB-RAW] A GRIB-to-JMGRIB-RAW converter for Linux
<http://zowie.metnet.navy.mil/~spawar/JMV-TNG/Code/Linux/grib-to-jmgrib-raw>

Last updated August 8, 2002

Converted from SXML by SXML->HTML