The Extended GeoJSON file format

Introduction

The GeoJSON specification is a well-known specification for describing and placing features on a map. Besides a location on the map, it also allows you to attach additional properties that describe the feature. For example, the number of people that life in a certain area, or when a building was built.

The problem with the GeoJSON specification

The problem with the GeoJSON specification is that it does not tell you how you would like to display a map feature (for example color, icon, size, etc.), nor how you would like to display its properties (text or number, how many decimals, what's the title, description, etc.). As we couldn't find a good specification for these aspects (correct me if I'm wrong), we started writing our own 'specification', and that's what is documented here.

The Extended GeoJSON format

Note that I don't talk about an Extended GeoJSON specification, as I'm not in the position nor the inclination to go that far, but the way we format things in csWeb en csMap, that's something I can describe.

A regular GeoJSON file looks like this:

{ 
  "type": "FeatureCollection",
  "features": [
  { 
    "type": "Feature",
    "geometry": {"type": "Point", "coordinates": [102.0, 0.5]},
    "properties": {"prop0": "value0"}
  },
  { "type": "Feature",
    "geometry": {
      "type": "LineString",
      "coordinates": [ [102.0, 0.0], [103.0, 1.0], [104.0, 0.0], [105.0, 1.0] ]
    },
    "properties": {
      "prop0": "value0",
      "prop1": 0.0
    }
  },
  { "type": "Feature",
    "geometry": {
       "type": "Polygon",
       "coordinates": [ [ [100.0, 0.0], [101.0, 0.0], [101.0, 1.0], [100.0, 1.0], [100.0, 0.0] ] ]
     },
     "properties": {
       "prop0": "value0",
       "prop1": {"this": "that"}
       }
     }
   ]
 }

Our format extends the JSON structure with a few additional properties: FeatureTypes, FeatureStyle and PropertyStyle. Our format also supports the use of temporal data. It is described in a seperate article Working-with-temporal-data.

FeatureTypes

FeatureTypes is a dictionary of one or more FeatureType objects, identifyable by their name. And the purpose of a FeatureType is to describe how a feature should be displayed on the map. Often, we have a GeoJSON file that only contains features of one particular type, e.g. hospitals. In that case, we only have one FeatureType, named "Default".

A partial example is given below.

"featureTypes": {
  "Default": {
    "name": "Hospital"
    "style": {
      "fillColor"  : "#ffff99",
      "strokeColor": "#000000",
      "drawingMode": "Point",
      "strokeWidth": 1,
      "iconWidth"  : 32,
      "iconHeight" : 32,
      "iconUri"    : "images/gemeente.png",
      "nameLabel"  : "Name"
    },
    "propertyTypeData": [{
      "label": "Name",
      "type": "text",
      "title": "Hospital name",
      "isSearchable": true,
      "visibleInCallout": false
    }, {
...

Let's examine the "Default" FeatureType a bit further. It has a:

• name (string): this is used when displaying the feature type in the application, for example in a legend.
• style (FeatureType): is used when displaying the feature on the map. See the next section.
• propertyTypeData (PropertyType[]): for each GeoJSON property that you wish to use, you can describe it with a property type (see the section below for a detailed description).

FeatureType

A FeatureType represents a feature on the map, and it defines the following properties:

• fillColor: A hexadecimal string in RGB notation, e.g. #f00 (or #ff0000) for red, or #00f (#0000ff) for blue. In case you use the ARGB notation, the first two bytes specify the opacity.
• strokeColor: the color of the border (of an icon or region). See fillColor for allowable values.
• strokeWidth: the width of the border line.
• iconWidth: the width of the icon in pixels.
• iconHeight: the height of the icon in pixels.
• iconUri: the (relative) URI of the icon.
• nameLabel: the name of the property that should be used as the name.
• drawingMode: typically point/image or polygon/multipolygon. Although we could have extracted this from the GeoJSON geometry type, we include it here so everything we need to know for rendering is available in one object.

NOTE: copy the geometry type property to the FeatureType, so we are always in sync.

PropertyType

• label: "Name",
• type: "text",
• title
• isSearchable
• visibleInCallout

A PropertyType represents a property, and it defines the following properties:

Note that the order that you add them here, is the order that they are shown as well, for example in the right hand panel when you select it).