:github_url: hide .. DO NOT EDIT THIS FILE!!! .. Generated automatically from Godot engine sources. .. Generator: https://github.com/godotengine/godot/tree/master/doc/tools/make_rst.py. .. XML source: https://github.com/godotengine/godot/tree/master/doc/classes/JSON.xml. .. _class_JSON: JSON ==== **Inherits:** :ref:`Resource` **<** :ref:`RefCounted` **<** :ref:`Object` Helper class for creating and parsing JSON data. .. rst-class:: classref-introduction-group Description ----------- The **JSON** class enables all data types to be converted to and from a JSON string. This is useful for serializing data, e.g. to save to a file or send over the network. \ :ref:`stringify` is used to convert any data type into a JSON string. \ :ref:`parse` is used to convert any existing JSON data into a :ref:`Variant` that can be used within Godot. If successfully parsed, use :ref:`data` to retrieve the :ref:`Variant`, and use :ref:`@GlobalScope.typeof` to check if the Variant's type is what you expect. JSON Objects are converted into a :ref:`Dictionary`, but JSON data can be used to store :ref:`Array`\ s, numbers, :ref:`String`\ s and even just a boolean. :: 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 strings using the static :ref:`parse_string` method, but it doesn't 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 :ref:`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 cleaned up and an error is logged to the console. .. rst-class:: classref-reftable-group Properties ---------- .. table:: :widths: auto +-------------------------------+---------------------------------------+----------+ | :ref:`Variant` | :ref:`data` | ``null`` | +-------------------------------+---------------------------------------+----------+ .. rst-class:: classref-reftable-group Methods ------- .. table:: :widths: auto +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`from_native`\ (\ variant\: :ref:`Variant`, allow_classes\: :ref:`bool` = false, allow_scripts\: :ref:`bool` = false\ ) |static| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`int` | :ref:`get_error_line`\ (\ ) |const| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_error_message`\ (\ ) |const| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`get_parsed_text`\ (\ ) |const| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Error` | :ref:`parse`\ (\ json_text\: :ref:`String`, keep_text\: :ref:`bool` = false\ ) | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`parse_string`\ (\ json_string\: :ref:`String`\ ) |static| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`String` | :ref:`stringify`\ (\ data\: :ref:`Variant`, indent\: :ref:`String` = "", sort_keys\: :ref:`bool` = true, full_precision\: :ref:`bool` = false\ ) |static| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | :ref:`Variant` | :ref:`to_native`\ (\ json\: :ref:`Variant`, allow_classes\: :ref:`bool` = false, allow_scripts\: :ref:`bool` = false\ ) |static| | +---------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Property Descriptions --------------------- .. _class_JSON_property_data: .. rst-class:: classref-property :ref:`Variant` **data** = ``null`` :ref:`🔗` .. rst-class:: classref-property-setget - |void| **set_data**\ (\ value\: :ref:`Variant`\ ) - :ref:`Variant` **get_data**\ (\ ) Contains the parsed JSON data in :ref:`Variant` form. .. rst-class:: classref-section-separator ---- .. rst-class:: classref-descriptions-group Method Descriptions ------------------- .. _class_JSON_method_from_native: .. rst-class:: classref-method :ref:`Variant` **from_native**\ (\ variant\: :ref:`Variant`, allow_classes\: :ref:`bool` = false, allow_scripts\: :ref:`bool` = false\ ) |static| :ref:`🔗` Converts a native engine type to a JSON-compliant dictionary. By default, classes and scripts are ignored for security reasons, unless ``allow_classes`` or ``allow_scripts`` are specified. .. rst-class:: classref-item-separator ---- .. _class_JSON_method_get_error_line: .. rst-class:: classref-method :ref:`int` **get_error_line**\ (\ ) |const| :ref:`🔗` Returns ``0`` if the last call to :ref:`parse` was successful, or the line number where the parse failed. .. rst-class:: classref-item-separator ---- .. _class_JSON_method_get_error_message: .. rst-class:: classref-method :ref:`String` **get_error_message**\ (\ ) |const| :ref:`🔗` Returns an empty string if the last call to :ref:`parse` was successful, or the error message if it failed. .. rst-class:: classref-item-separator ---- .. _class_JSON_method_get_parsed_text: .. rst-class:: classref-method :ref:`String` **get_parsed_text**\ (\ ) |const| :ref:`🔗` Return the text parsed by :ref:`parse` (requires passing ``keep_text`` to :ref:`parse`). .. rst-class:: classref-item-separator ---- .. _class_JSON_method_parse: .. rst-class:: classref-method :ref:`Error` **parse**\ (\ json_text\: :ref:`String`, keep_text\: :ref:`bool` = false\ ) :ref:`🔗` Attempts to parse the ``json_text`` provided. Returns an :ref:`Error`. If the parse was successful, it returns :ref:`@GlobalScope.OK` and the result can be retrieved using :ref:`data`. If unsuccessful, use :ref:`get_error_line` and :ref:`get_error_message` to identify the source of the failure. Non-static variant of :ref:`parse_string`, if you want custom error handling. The optional ``keep_text`` argument instructs the parser to keep a copy of the original text. This text can be obtained later by using the :ref:`get_parsed_text` function and is used when saving the resource (instead of generating new text from :ref:`data`). .. rst-class:: classref-item-separator ---- .. _class_JSON_method_parse_string: .. rst-class:: classref-method :ref:`Variant` **parse_string**\ (\ json_string\: :ref:`String`\ ) |static| :ref:`🔗` Attempts to parse the ``json_string`` provided and returns the parsed data. Returns ``null`` if parse failed. .. rst-class:: classref-item-separator ---- .. _class_JSON_method_stringify: .. rst-class:: classref-method :ref:`String` **stringify**\ (\ data\: :ref:`Variant`, indent\: :ref:`String` = "", sort_keys\: :ref:`bool` = true, full_precision\: :ref:`bool` = false\ ) |static| :ref:`🔗` Converts a :ref:`Variant` var to JSON text and returns the result. Useful for serializing data to store or send over the network. \ **Note:** The JSON specification does not define integer or float types, but only a *number* type. Therefore, converting a Variant to JSON text will convert all numerical values to :ref:`float` types. \ **Note:** If ``full_precision`` is ``true``, when stringifying floats, the unreliable digits are stringified in addition to the reliable digits to guarantee exact decoding. The ``indent`` parameter controls if and how something is indented; its contents will be used where there should be an indent in the output. Even spaces like ``" "`` will work. ``\t`` and ``\n`` can also be used for a tab indent, or to make a newline for each indent respectively. \ **Example output:**\ :: ## JSON.stringify(my_dictionary) {"name":"my_dictionary","version":"1.0.0","entities":[{"name":"entity_0","value":"value_0"},{"name":"entity_1","value":"value_1"}]} ## JSON.stringify(my_dictionary, "\t") { "name": "my_dictionary", "version": "1.0.0", "entities": [ { "name": "entity_0", "value": "value_0" }, { "name": "entity_1", "value": "value_1" } ] } ## JSON.stringify(my_dictionary, "...") { ..."name": "my_dictionary", ..."version": "1.0.0", ..."entities": [ ......{ ........."name": "entity_0", ........."value": "value_0" ......}, ......{ ........."name": "entity_1", ........."value": "value_1" ......} ...] } .. rst-class:: classref-item-separator ---- .. _class_JSON_method_to_native: .. rst-class:: classref-method :ref:`Variant` **to_native**\ (\ json\: :ref:`Variant`, allow_classes\: :ref:`bool` = false, allow_scripts\: :ref:`bool` = false\ ) |static| :ref:`🔗` Converts a JSON-compliant dictionary that was created with :ref:`from_native` back to native engine types. By default, classes and scripts are ignored for security reasons, unless ``allow_classes`` or ``allow_scripts`` are specified. .. |virtual| replace:: :abbr:`virtual (This method should typically be overridden by the user to have any effect.)` .. |const| replace:: :abbr:`const (This method has no side effects. It doesn't modify any of the instance's member variables.)` .. |vararg| replace:: :abbr:`vararg (This method accepts any number of arguments after the ones described here.)` .. |constructor| replace:: :abbr:`constructor (This method is used to construct a type.)` .. |static| replace:: :abbr:`static (This method doesn't need an instance to be called, so it can be called directly using the class name.)` .. |operator| replace:: :abbr:`operator (This method describes a valid operator to use with this type as left-hand operand.)` .. |bitfield| replace:: :abbr:`BitField (This value is an integer composed as a bitmask of the following flags.)` .. |void| replace:: :abbr:`void (No return value.)`