Skip to main content

JSON Values

JSON Values

You can use the SET command to set a variable to a JSON object or a JSON array. For a JSON object, the value is a JSON object delimited by curly braces. For a JSON array, the value is a JSON array delimited by square brackets.

Within these delimiters, the literal values are JSON literals, not ObjectScript literals. An invalid JSON literal generates a <SYNTAX> error.

  • String literal: You must enclose a JSON string in double quotes. To specify certain characters as literals within a JSON string, you must specify the \ escape character, followed by the literal. If a JSON string contains a double-quote literal character this character is written as \". JSON string syntax provides escapes for double quote (\"), backslash (\\), and slash (\/). Line space characters can also be escaped: backspace (\b), formfeed (\f), newline (\n), carriage return (\r), and tab (\t). Any Unicode character can be represented by a six character sequence: a backslash, followed by lowercase letter u, followed by four hexadecimal digits. For example, \u0022 specifies a literal double quote character; \u03BC specifies the Greek lowercase letter Mu.

  • Numeric literal: JSON does not convert numbers to ObjectScript canonical form. JSON has its own conversion and validation rules: Only a single leading minus sign is permitted; a leading plus sign is not permitted, multiple leading signs are not permitted. The “E” scientific notation character is permitted, but not evaluated. Leading zeros are not permitted; trailing zeros are preserved. A decimal separator must have a digit character on both sides of it. Therefore, the JSON numerics 0, 0.0, 0.4, and 0.400 are valid. A negative sign on a zero value is preserved.

    For IEEE floating-point numbers, additional rules apply. Refer to the $DOUBLE function for details.

    JSON fractional numbers are stored in a different format than ObjectScript numbers. ObjectScript floating point fractional numbers are rounded when they reach their maximum precision, and trailing zeros are removed. JSON packed BCD fractional numbers allow for greater precision, and trailing zeros are retained. This is shown in the following example:

      SET jarray=[1.23456789123456789876000,(1.23456789123456789876000)]
      WRITE jarray.%ToJSON()
  • Special values: JSON supports the following special values: true, false, and null. These are literal values that must be specified as an unquoted literal in lowercase letters. These JSON special values cannot be specified using a variable, or specified in an ObjectScript expression.

  • ObjectScript: To include an ObjectScript literal or expression within a JSON array element or a JSON object value, you must enclose the entire string in parentheses. You cannot specify ObjectScript in a JSON object key. ObjectScript and JSON use different escape sequence conventions. To escape a double quote character in ObjectScript, you double it. In the following example, a JSON string literal and an ObjectScript string literal are specified in a JSON array:

      SET jarray=["This is a \"good\" JSON string",("This is a ""good"" ObjectScript string")]
      WRITE jarray.%ToJSON()

    The following JSON array example specifies an ObjectScript local variable and performs ObjectScript numeric conversion to canonical form:

      SET str="This is a string"
      SET jarray=[(str),(--0007.000)]
      WRITE jarray.%ToJSON()

    The following example specifies an ObjectScript function in a JSON object value:

      SET jobj={"firstname":"Fred","namelen":($LENGTH("Fred"))}
      WRITE jobj.%ToJSON()

JSON Object

A value can be a JSON object delimited by curly braces. The variable is set to an OREF, such as the following: 3@%Library.DynamicObject. You can use the ZWRITE command with a specified local variable name to display the JSON value:

  SET jobj={"inventory123":"Fred's \"special\" bowling ball"}
  ZWRITE jobj  

You can use the %Get() method to retrieve the value of a specified key using the OREF. You can resolve the OREF to the full JSON object value using the %ToJSON() method. This is shown in the following example:

  SET jobj={"inventory123":"Fred's \"special\" bowling ball"}
  WRITE "JSON object reference = ",jobj,!
  WRITE jobj.%Get("inventory123")," (data value in ObjectScript format)",!
  WRITE jobj.%Get("inventory123",,"json")," (data value in JSON format)",!
  WRITE jobj.%ToJSON()," (key and data value in JSON format)"

A valid JSON object has the following format:

  • Begins with an open curly brace, ends with a close curly brace. The empty object {} is a valid JSON object.

  • Within the curly braces, a key:value pair or a comma-separated list of key:value pairs. Both the key and the value components are JSON literals, not ObjectScript literals.

  • The key component must be a JSON quoted string literal. It cannot be an ObjectScript literal or expression enclosed in parentheses.

  • The value component can be a JSON string or a JSON numeric literal. These JSON literals follow JSON validation criteria. A value component can be an ObjectScript literal or expression enclosed in parentheses. The value component can be specified as a defined variable specifying a string, a numeric, a JSON object, or a JSON array. The value component can contain nested JSON objects or JSON arrays. A value component can also be one of the following three JSON special values: true, false, null, specified as an unquoted literal in lowercase letters; these JSON special values cannot be specified using a variable.

The following are all valid JSON objects: {"name":"Fred"}, {"name":"Fred","city":"Bedrock"}, {"bool":true}, {"1":true,"0":false,"Else":null}, {"name":{"fname":"Fred","lname":"Flintstone"},"city":"Bedrock"}, {"name":["Fred","Wilma","Barney"],"city":"Bedrock"}.

A JSON object can specify a null property name and assign it a value, as shown in the following example:

  SET jobj={}
  SET jobj.""="This is the ""null"" property value"
  WRITE jobj.%Get(""),!
  WRITE "JSON null property object value = ",jobj.%ToJSON()

Note that the returned JSON string uses the JSON escape sequence (\") for a literal double quote character.

You can use the %Set()Opens in a new tab method to add a key:value pair to a JSON object.

You can use the %Get()Opens in a new tab method to return the value of a specified key in various formats. The syntax is:

jobj.%Get(keyname,default,format) 

The default argument is the value returned if keyname does not exist.

The format argument specifies the format for the returned value. If no format is specified, the value is returned in ObjectScript format; if format="json", the value is returned in JSON format; if format="string", all string and numeric values are returned in ObjectScript format, but the JSON true and false special values are returned as JSON alphabetic strings rather than boolean integers; the JSON null special value is returned in ObjectScript format as a zero-length null string. This is shown in the following example:

  SET x={"yep":true,"nil":null}
  WRITE "IRIS: ",x.%Get("yep")," JSON: ",x.%Get("yep",,"json")," STRING: ",x.%Get("yep",,"string"),!
     /*  IRIS: 1 JSON: true STRING: true */
  WRITE "IRIS: ",x.%Get("nil")," JSON: ",x.%Get("nil",,"json")," STRING: ",x.%Get("nil",,"string")
    /*   IRIS:  JSON: null STRING:       */

For further details, see Using JSON.

JSON Array

A value can be a JSON array delimited by square brackets. The variable is set to an OREF, such as the following: 1@%Library.DynamicArray. You can use the ZWRITE command with a specified local variable name to display the JSON value:

  SET jary=["Fred","Wilma","Barney"]
  ZWRITE jary

You can use the %Get()Opens in a new tab method to retrieve the value of a specified array element (counting from 0) using the OREF: %Get(n) returns the ObjectScript value; %Get(n,,”json”) returns the JSON value. %Get(n,”no such element”,”json”) specifies a default value to return if the specified array element does not exist. You can resolve the OREF to the full JSON array value using the %ToJSON() function. This is shown in the following example:

  SET jary=["Fred","Wilma","Barney"]
  WRITE "JSON array reference = ",jary,!
  WRITE jary.%Get(1)," (array element value in ObjectScript format)",!
  WRITE jary.%Get(1,,"json")," (array element value in JSON format)",!
  WRITE jary.%ToJSON()," (array values in JSON format)"

A valid JSON array has the following format:

  • Begins with an open square bracket, ends with a close square bracket. The empty array [] is a valid JSON array.

  • Within the square brackets, an element or a comma-separated list of elements. Each array element can be a JSON string or JSON numeric literal. These JSON literals follow JSON validation criteria. An array element can be an ObjectScript literal or expression enclosed in parentheses. An array element can be specified as a defined variable specifying a string, a numeric, a JSON object, or a JSON array. An array element can contain one or more JSON objects or JSON arrays. An array element can also be one of the following three JSON special values: true, false, null, specified as an unquoted literal in lowercase letters; these JSON special values cannot be specified using a variable.

The following are all valid JSON arrays: [1], [5,7,11,13,17], ["Fred","Wilma","Barney"], [true,false], ["Bedrock",["Fred","Wilma","Barney"]], [{"name":"Fred"},{"name":"Wilma"}], [{"name":"Fred","city":"Bedrock"},{"name":"Wilma","city":"Bedrock"}], [{"names":["Fred","Wilma","Barney"]}].

You can use the %Push()Opens in a new tab method to add a new element to the end of the array. You can use the %Set()Opens in a new tab method to add a new array element or update an existing array element by position.

For further details, see Using JSON.

FeedbackOpens in a new tab