Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

JSON

Inherits: Resource < RefCounted < Object

Helper class for creating and parsing JSON data.

Description

The JSON enables all data types to be converted to and from a JSON string. This useful for serializing data to save to a file or send over the network.

stringify is used to convert any data type into a JSON string.

parse is used to convert any existing JSON data into a Variant that can be used within Godot. If successfully parsed, use data to retrieve the Variant, and use typeof to check if the Variant's type is what you expect. JSON Objects are converted into a Dictionary, but JSON data can be used to store Arrays, numbers, Strings and even just a boolean.

Example

var data_to_send = ["a", "b", "c"]
var json_string = JSON.stringify(data_to_send)
# Save data
# ...
# Retrieve data
var json = JSON.new()
var error = json.parse(json_string)
if error == OK:
    var data_received = json.data
    if typeof(data_received) == TYPE_ARRAY:
        print(data_received) # Prints array
    else:
        print("Unexpected data")
else:
    print("JSON Parse Error: ", json.get_error_message(), " in ", json_string, " at line ", json.get_error_line())

Alternatively, you can parse string using the static parse_string method, but it doesn't allow to handle errors.

var data = JSON.parse_string(json_string) # Returns null if parsing failed.

Note: Both parse methods do not fully comply with the JSON specification:

  • Trailing commas in arrays or objects are ignored, instead of causing a parser error.

  • New line and tab characters are accepted in string literals, and are treated like their corresponding escape sequences \n and \t.

  • Numbers are parsed using String.to_float which is generally more lax than the JSON specification.

  • Certain errors, such as invalid Unicode sequences, do not cause a parser error. Instead, the string is cleansed and an error is logged to the console.

Properties

Variant

data

null

Methods

int

get_error_line ( ) const

String

get_error_message ( ) const

String

get_parsed_text ( ) const

Error

parse ( String json_text, bool keep_text=false )

Variant

parse_string ( String json_string ) static

String

stringify ( Variant data, String indent="", bool sort_keys=true, bool full_precision=false ) static

Property Descriptions

Variant data = null

Contains the parsed JSON data in Variant form.

Method Descriptions

int get_error_line ( ) const

Returns 0 if the last call to parse was successful, or the line number where the parse failed.

String get_error_message ( ) const

Returns an empty string if the last call to parse was successful, or the error message if it failed.

String get_parsed_text ( ) const

Return the text parsed by parse as long as the function is instructed to keep it.

Error parse ( String json_text, bool keep_text=false )

Attempts to parse the json_text provided.

Returns an Error. If the parse was successful, it returns @GlobalScope.OK and the result can be retrieved using data. If unsuccessful, use get_error_line and get_error_message for identifying the source of the failure.

Non-static variant of parse_string, if you want custom error handli