Esri-JSON (Esri JavaScript Object Notation) Reader/Writer

FME supports the Esri Feature Sets, as defined at http://resources.esri.com/help/9.3/BusinessAnalyst/Online_apis/apis/REST/types.html#FeatureSet

Esri-JSON is a standard for encoding spatial data in JSON structured text.

Overview

Esri-JSON encodes both geometry and feature information into objects. An Esri Feature Set is a collection of feature with the same geometry type and coordinate system. In a JSON document, a feature set is represented by JSON object. The JSON object has three keys:

  • geometryType,
  • spatialReference, and
  • features. 

The value of the geometryType key is a string which indicates the type of geometry contained by the features in the data set.  Valid geometry types are points, polylines, polygons, envelopes and multi-points.

The value of the spatialReference key is a JSON object containing coordinate system data for the features in the data set. In ESRIJSON, coordinate systems are represented by their well known ID, typically an EPSG number. The spatialReference key and value are duplicated in the geometry object of each feature in the dataset. A spatial reference object representing the EPSG:4326 coordinate system is shown below.

{ “wkid“ : 4326 }

The value of the features key is an array of JSON objects, representing the individual features in the data set.  Each feature object has two keys, geometry and attributes. The value of the attributes key is a JSON object whose keys and values represent feature attribute names and values. The value of the geometry key is an Esri-JSON geometry object. The various types of geometry objects are listed below.

Point

All point geometries are simple two dimensional geometry.

Polyline

A polyline is an array of linear segments. Each linear segment is an array of points.  A point is represented as two element array. The first element is always the x-coordinate and the second is always the y-coordinate, regardless of the coordinate system being used. 

Polygon

Polygon geometries have similar structure to polylines.  A polygon consists of an array of rings, each of which is an array of points. As with polylines, the first element in a point is always the x-coordinate, and the second is always the y-coordinate. 

Envelope

Envelope geometries are simply bounding box features, represented by two points.

MultiPoint

Multipoint geometries are represented by an array of two dimensional points. As with other geometries, the first element in each point is the x-coordinate, and the second is the y-coordinate. 

Reader Overview

The Esri-JSON reader can read many different types of JSON text.

It may be used to read an Esri Feature Set object, as described in the Overview section above. It may also be used to read individual geometry objects, or an array of geometry objects. Finally, if the root JSON object or array in a dataset is not a known Esri-JSON object, the reader will examine each value in the object or array and attempt to use these values to create features.

Coordinate Systems

The ESRIJSON reader currently supports coordinate systems that have an EPSG number. 

In a spatialReference JSON object, the reader will use the value of the wkid key as the EPSG coordinate system number. For example, if a dataset contains the following spatial reference, the coordinate system would be EPSG:4326.

{ “spatialReference”:{“wkid”:4326} }

Writer Overview

The Esri-JSON writer writes out a file for each feature type.  Each file contains a single JSON object, whose RecordSet property contains an Esri-JSON FeatureSet object.

Coordinate Systems

Each feature type may have a unique coordinate system. The Esri-JSON writer will output the Esri well-known ID for the coordinate system, as the value of the spatialReference key in the top-level object. 

In general, the well-known ID is an EPSG coordinate system number. If a well-known ID cannot be determined for a particular coordinate system, the coordinate system name will be output instead.

Geometry

FME feature geometry is written out in an Esri-JSON geometry object as the value of the geometry key in an ESRIJSON feature object. Because Esri-JSON only supports linear geometry, arcs will be stroked to lines, and ellipses will be stroked to polygons.

Features containing unsupported geometry will have a null value written to the geometry key.