Using fromJSON() to create a class instance

Many classes, including all layers, symbols, geometries, Camera, Viewpoint, Color, and FeatureSet, contain a method called fromJSON().

This function allows you to create an instance of the given class from JSON generated by a product in the ArcGIS platform. JSON in this format is typically created from a toJSON() method or a query via the REST API. See the ArcGIS REST API documentation for information and examples of how geometries, symbols, webmaps, etc. are queried and represented in JSON.

The following sample shows how to create a SimpleMarkerSymbol with JSON that was previously retreived from a query using the REST API.

require(["esri/symbols/SimpleMarkerSymbol"], function(SimpleMarkerSymbol){
  // SimpleMarkerSymbol as a JSON response generated from ArcGIS REST API query
  var smsJson = {
    "type": "esriSMS",
    "style": "esriSMSSquare",
    "color": [76,115,0,255],
    "size": 8,
    "angle": 0,
    "xoffset": 0,
    "yoffset": 0,
    "outline":
    {
      "color": [152,230,0,255],
      "width": 1
    }
  };

  // Create a SimpleMarkerSymbol from the JSON representation
  var sms = SimpleMarkerSymbol.fromJSON(smsJson);
});

The JSON object passed as the input parameter to fromJSON() may look similar to the object passed as a constructor parameter in the same class. However, these two objects are different in various ways and should not be interchanged. This is because the values and default units of measurement differ between the REST and JavaScript API's (e.g. symbol size is measured in points with the REST API whereas the JavaScript API uses pixels).

The parameter passed in class constructors is a simple JSON object designed for your convenience. Generally, this should always be used to create a new instance of a class, unless dealing with JSON previously generated elsewhere from a toJSON() method or a query to the REST API. Also, it should be noted to always work with fromJSON(), not the constructor, when creating a class instance from a JSON object in cases where the JSON was previously generated using the ArcGIS REST API or another ArcGIS product (e.g. ArcGIS for Server, ArcGIS Online, Portal for ArcGIS, etc.).

Using jsonUtils

Three jsonUtils objects are provided for your convenience when you need to use fromJSON() to instantiate an object, but you don't know its type.

These are available for scenarios when you obtain a JSON object representing either a geometry, renderer, or symbol from the REST API, but you don't know the type of the object. For example, when you get a layer's renderer via REST, but you don't know that it's a UniqueValueRenderer; rather than figuring it out its type on your own and requiring a separate module, you can require the esri/renderers/support/jsonUtils object and get the renderer without knowing its type.

require([ "esri/renderers/support/jsonUtils",
          "esri/layers/FeatureLayer"
], function( rendererJsonUtils, FeatureLayer ){

  // renderer object obtained via REST request
  var rendererJson = {
     "authoringInfo":null,
     "type":"uniqueValue",
     "field1":"CLASS",
     "field2":null,
     "field3":null,
     "expression":null,
     "fieldDelimiter":null,
     "defaultSymbol":{
        "color":[
           235,
           235,
           235,
           255
        ],
        "type":"esriSLS",
        "width":3,
        "style":"esriSLSShortDot"
     },
     "defaultLabel":"Other major roads",
     "uniqueValueInfos":[
        {
           "value":"I",
           "symbol":{
              "color":[
                 255,
                 170,
                 0,
                 255
              ],
              "type":"esriSLS",
              "width":10,
              "style":"esriSLSSolid"
           },
           "label":"Interstate"
        },
        {
           "value":"U",
           "symbol":{
              "color":[
                 223,
                 115,
                 255,
                 255
              ],
              "type":"esriSLS",
              "width":7,
              "style":"esriSLSSolid"
           },
           "label":"US Highway"
        }
     ]
  };

  // Create a renderer object from its JSON representation
  var flRenderer = rendererJsonUtils.fromJSON(rendererJson);

  // Set the renderer on a layer
  var layer = new FeatureLayer({
    renderer: flRenderer
  });

});