TO_JSON

The function TO_JSON converts any any variable type to a string by converting the data to JSON.

All Airkit types can be converted to and from JSON in such a way that serializing to JSON, and deserializing that JSON will return the original value. The following table lists how each data type is encoded as JSON.

Airkit Variable TypeJSON typeExample
Nullnullnull
Booleanbooleantrue
Numbernumber3.141592653589793
Text (String)string"The quick brown fox"
Listarray[ 1, "two", 3 ]
App Objectobject{ "title": "Angels & Demons","author": "Dan Brown","isbn": "9781416524793", "genres": ["Fiction"]}
DateTimeobject{ "date": { "year": 2007, "month": 1, "day": 9 }, "time": { "hour": 9, "minute": 41, "second": 0, "millisecond": 0 }, "timeZone": "America/Los_Angeles"}
Dateobject{ "year": 2007, "month": 1, "day": 9}
Timeobject{ "hour": 9, "minute": 41, "second": 0, "millisecond": 0}
Currencyobject{ "amount": 100, "code": "USD", "precision": 2}

Declaration

TO_JSON(value) -> json_string

Parameters

value (required, type: any)
Any Airscript value.

Return Values

json_string (type: string)
The input Airscript value serialized as a JSON string.

Examples

TO_JSON called with a Number will return a String containing that number as if FORMAT_NUMBER were called on that number.

TO_JSON(PI()) -> "3.141592653589793"

When called with a String, TO_JSON will return a string containing a JSON string, note that Text itself contains double quotes.

TO_JSON("The quick brown fox") -> "\"The quick brown fox\""

Complex objects along with nested values will all be converted to JSON recursively.

TO_JSON([
  { 
    title: "Angels & Demons",
    author: "Dan Brown",
    isbn: "9781416524793",
    genres: ["Fiction"]
  },
  {
    title: "The Da Vinci Code",
    author: "Dan Brown",
    isbn: "9780307879257",
    genres: ["Fiction"]
  },
  {
    title: "Hackers: Heroes of the Computer Revolution",
    author: "Steven Levy",
    isbn: "9780141000510",
    genres: ["History"]
  },
  {
    title: "Moonwalking with Einstein: The Art and Science of Remembering Everything",
    author: "Joshua Foer",
    isbn: "9781594202292",
    genres: ["Nonfiction"]
  }  
]) -> 
[
   {
      "title":"Angels & Demons",
      "author":"Dan Brown",
      "isbn":"9781416524793",
      "genres":[
         "Fiction"
      ]
   },
   {
      "title":"The Da Vinci Code",
      "author":"Dan Brown",
      "isbn":"9780307879257",
      "genres":[
         "Fiction"
      ]
   },
   {
      "title":"Hackers: Heroes of the Computer Revolution",
      "author":"Steven Levy",
      "isbn":"9780141000510",
      "genres":[
         "History"
      ]
   },
   {
      "title":"Moonwalking with Einstein: The Art and Science of Remembering Everything",
      "author":"Joshua Foer",
      "isbn":"9781594202292",
      "genres":[
         "Nonfiction"
      ]
   }
]

The last example contained extra white space to aid legibility, however, the real output will not actually contain whitespace and the actual result will look like this.

TO_JSON([
  { 
    title: "Angels & Demons",
    author: "Dan Brown",
    isbn: "9781416524793",
    genres: ["Fiction"]
  },
  {
    title: "The Da Vinci Code",
    author: "Dan Brown",
    isbn: "9780307879257",
    genres: ["Fiction"]
  },
  {
    title: "Hackers: Heroes of the Computer Revolution",
    author: "Steven Levy",
    isbn: "9780141000510",
    genres: ["History"]
  },
  {
    title: "Moonwalking with Einstein: The Art and Science of Remembering Everything",
    author: "Joshua Foer",
    isbn: "9781594202292",
    genres: ["Nonfiction"]
  }  
]) -> [{"title":"Angels & Demons","author":"Dan Brown","isbn":"9781416524793","genres":["Fiction"]},{"title":"The Da Vinci Code","author":"Dan Brown","isbn":"9780307879257","genres":["Fiction"]},{"title":"Hackers: Heroes of the Computer Revolution","author":"Steven Levy","isbn":"9780141000510","genres":["History"]},{"title":"Moonwalking with Einstein: The Art and Science of Remembering Everything","author":"Joshua Foer","isbn":"9781594202292","genres":["Nonfiction"]}]

Discussion

The most common use case for serializing values to JSON is to send data to an external system. Special care needs to be taken when serializing values of the type DateTime, Date, Time, and Currency as there are no standard ways to represent these types in JSON. It is unlikely that the external system will represent them in the same way as Airkit does.

While Date, Time, and Currency types have no industry standard representation, DateTime types are commonly represented as either a number or a string in JSON. Airkit provides functions for working with these common formats, called timestamps. See Working with Date, Time & DateTime in Airscript for more details.