Skip to content

Latest commit

 

History

History
70 lines (44 loc) · 4.04 KB

readme.md

File metadata and controls

70 lines (44 loc) · 4.04 KB

COGJ Spec

COGJ defines a header included before an unbounded list of GeoJSON FeatureCollections. Therefore this spec only defines the header and file structure -- not the FeatureCollection or sub structures of it. For information on those please reference the official IETF doc.

COGJ Header

Separating Feature Collections

Each FeatureCollection in the collection section should be prefixed with the record separator symbol (UTF8 0x001E) and terminated with the line feed symbol (UTF8 0x000A). The following describes the structure and meaning of properties in the COGJ header. The header must start at byte 0 of the COGJ file and cannot exceed beyond byte 9999 (0 indexed). The header must be valid JSON and must adhere to the JSON schema defined here.

COGJ Headers are a GeoJSON FeatureCollection with extended properties.

Mandatory Fields

The following properties are mandatory in the header:

Name Optional Type Meaning
size no integer the size in bytes of the entire file
features no integer the number of total features contained in the entire file
bbox no array the bounding box of the entire dataset as an array of 4 coordinates specified in decimal degrees and WGS84 ordered as left, bottom, right, top
collections no an array of collection objects each object describes a FeatureCollection contained in this file
name yes string a short name for this dataset
description yes string a textual desciption of this dataset
version yes string the version of this dataset, ideally compliant with sematic versioning
published yes string the publication timestamp in ISO8601 format
extended_metadata yes object an object that points to an range of bytes which allows this header to extend beyond 10k byte size

The features array contains the GeoJSON features with following properties:

Name Optional Type Meaning
start no integer the first byte of the collection in the file
size no integer the size of the collection in bytes
bbox no array the bounding box of the collecttion as an array of 4 coordinates specified in decimal degrees and WGS84 ordered as left, bottom, right, top
features no integer the number of features in this collection
name yes string a short name for this dataset
description yes string a textual desciption of this dataset

The extended_metadata object contains the following properties:

Name Optional Type Meaning
start no integer the first byte of the extended_metadata in the file
size no integer the size of the extended_metadata in bytes

The geometry object must be null.

Additional Properties

Both the top level header and the collection objects allow additionalProperties in the JSON schema definition. This means that any arbitrary properties may be inserted to enrich the file or collection metadata.

COGJ Extended header

When dealing with very large datasets which have been divided into large numbers of collections it may be possible for the header to overflow the 10k limit. In such cases the extended_metadata object allows the publisher to specify an additional byte range containing the full metadata header.

The content of the byte range specified by the extended_metadata object should be valid JSON and adhere to the same header schema.

Header Padding

As the header JSON will rarely be exactly 10,000 bytes, the remainder of the length should be padded using spaces (UTF8 0x0020) so that the size is exact.

Separating Feature Collections

Each FeatureCollection in the collection section should be prefixed with the record separator symbol (UTF8 0x001E) and terminated with the line feed symbol (UTF8 0x000A).