VRyHungry1/addons/yaml/CHANGELOG.md

Godot YAML Changelog

Version 2.2.0

• Updated GDSchema to version 2.0.0, with JSON schema draft 2020-12 validation spec
• Enable CTRL+mouse wheel to zoom in the YAML editor (Issue #17)
• Renamed HistoryState class to YAMLEditorHistoryState, fixing Issue #19
• Various small fixes

Version 2.1.3

• Changed the behavior of the x-yaml-tag Schema validation rule to ignore tagless nodes

Version 2.1.2

• Added support for Android (arm64, x86_64) platforms thanks to @Nemo1166
• Rewrote String variant strigification rules, resolving Issue #15
• Fixed application hanging when closed due to an issue with the YAML class registry

Version 2.1.1

Empty strings are stringified with quotes.

Version 2.1.0

When passing the custom tag to YAML.schema_register(class, serialize_method, deserialize_static, custom_tag) use the custom tag when emitting, resolving Issue #13.

Version 2.0.0

The second major version of Godot YAML brings powerful schema validation capabilities through the integration of GDSchema, enabling JSON Schema Draft-7 validation for your YAML data. This release also includes improved multi-document handling, custom tag support, and several important bug fixes. See the migration guide for breaking changes.

Major Features

Schema Validation (New!)

Version 2.0.0 introduces comprehensive schema validation powered by GDSchema, bringing the full power of JSON Schema Draft-7 to your YAML workflows. This flagship feature enables you to:

• Validate YAML data against industry-standard JSON Schema specifications
• Define schemas in YAML with native YAML syntax for better readability
• Auto-apply defaults when properties are missing using the default keyword
• Validate YAML tags with the custom x-yaml-tag keyword for type safety
• Reference schemas using $ref for modular, reusable validation rules
• Register schemas globally with $id for cross-file validation
• Get detailed error reports with JSON Pointer paths and constraint information

New classes:

• Schema - Validates data against JSON Schema Draft-7 specifications
• SchemaValidationResult - Contains detailed validation results and errors

New YAML methods:

• YAML.load_schema_from_string() - Parse YAML schema definitions
• YAML.load_schema_from_file() - Load schema files with auto-registration
• YAML.parse_and_validate() - Parse and validate YAML in one step

Schema features include:

• Full JSON Schema Draft-7 support (type checking, numeric constraints, string patterns, array/object validation)
• Logical composition (allOf, anyOf, oneOf, not)
• Conditional validation (if/then/else)
• Schema definitions and references ($defs, $ref)
• Custom format validators
• Thread-safe lazy compilation with caching
• YAML-specific extensions:
  • default - Provides default values for missing properties
  • x-yaml-tag - Validates YAML type tags (e.g., !Resource, !CustomType)

Example:

# Define a schema in YAML
var schema_yaml = """
$id: "http://example.com/user.yaml"
type: object
properties:
  username:
    type: string
    minLength: 3
  email:
    type: string
    format: email
  role:
    type: string
    default: user
    x-yaml-tag: UserRole
required:
- username
- email
"""

# Build the schema (auto-registered with $id)
var schema = YAML.load_schema_from_string(schema_yaml)

# Validate data
var data_yaml = """
username: Alice
email: alice@exampe.com
"""

var result = YAML.parse_and_validate(data_yaml, schema)

if result.is_valid():
    print(result.get_data().role)  # "user" (default applied)
else:
    print(result.get_summary())  # Detailed error report

Other Changes

• Breaking: Removed the YAMLResult.get_data(index) parameter. Use YAMLResult.get_document(index) instead for multi-document access.
• Added YAMLResult.get_documents() and YAMLResult.has_multiple_documents() methods for easier multi-document YAML handling
• Added support for custom tags when registering classes with YAML.register_class() - now you can specify custom YAML tags like !Item or !ruby:object/Item
• Added YAMLCodeEdit class to enable embedding the YAML editor directly into your projects
• Added missing example for handling multi-document YAML files
• Upgraded RapidYAML to version 0.10.0

Bug Fixes

• Fixed YAMLResult.get_data() only returning the first element of a document that only contains an array
• Fixed invalid numeric value parsing that could cause crashes or incorrect values
• Fixed empty strings being parsed and emitted as null values instead of empty strings
• Fixed YAML files not opening correctly in Godot 4.3 editor

Migration Guide From Version 1.* to 2.0.0

Replace YAMLResult.get_data(index) calls with YAMLResult.get_document(index):

Old version:

var result = YAML.parse(multi_doc_yaml)
var first_doc = result.get_data(0)
var second_doc = result.get_data(1)

New version:

var result = YAML.parse(multi_doc_yaml)
var first_doc = result.get_document(0)
var second_doc = result.get_document(1)

# Or get all documents at once
var all_docs = result.get_documents()

Version 1.1.0

• YAML files can now be loaded with the !Resource tag, allowing modular composition
• Fixes:
  • Force YAML indentation to always use spaces instead of tabs
  • The file system should now update properly when saving a new YAML file
  • Fixed tab indentation not working correctly in the YAML editor
  • Fixed Packed Array types not detecting array templates
  • Prevent duplicates in YAML editor file list

Version 1.0.0

The first major version of Godot YAML includes many improvements, and some breaking changes. See the migration guide for details.

Changes

• Streamlined API in many places
• Added class documentation for the in-editor help
• Added custom YAML editor inside the Godot engine editor
• Added YAMLSecurity class for safer resource loading during parsing
• YAMLStyle API changes:
  • Adopted Godot terminology for container form (Array and Dictionary instead of Sequence and Map)
  • Merged scalar and quote styles into unified string style
  • Separated number format into integer and float formats respectively
  • Removed binary encoding (now always uses base64 encoding)
  • Implemented serializing/deserializing style definitions
• Implemented stringifying non-local-to-scene resource references
• Performance optimizations
• Improved error reporting across the board with line/column tracking when parsing
• Fixes:
  • Style definitions should now be parsed correctly
  • Stringifying with styles should now work consistently
  • Fixed custom tags not being used when stringifying with styles
  • Fixed integer to string conversion with 64 bit values

Migration Guide From Version 0.12.1 to 1.0.0

This migration guide should help you update your code to work with the latest version of the YAML plugin. The core functionality and architecture remain similar, but the style system has been refined for better consistency and usability.

Custom Class Serialization and Deserialization

Custom class serialization has been changed to allow serializing to/from just dictionaries to any of the supported Godot variants:

Old version:

class_name CustomClass extends Resource

@export var name: String

func _init(p_name: String = "") -> void:
    name = p_name

func to_dict() -> Dictionary:
    return {
      "name": name
    }

static func from_dict(data: Dictionary) -> CustomClass:
    return CustomClass.new(data["name"])

New version:

class_name CustomClass extends Resource

@export var name: String

func _init(p_name: String = "") -> void:
    name = p_name

func serialize() -> Variant:
    return {
      "name": name
    }

static func deserialize(data: Variant) -> Variant:
    if typeof(data) != TYPE_DICTIONARY:
        return YAMLResult.error("CustomClass expects Dictionary")

    return CustomClass.new(data["name"])

Container Form Changes

Previously the container forms used the YAML standard naming of Sequences and Maps, but to make the extension more Godot friendly the containers now follow Godot's naming conventions of Arrays and Dictionaries:

# Specify how containers are formatted
style.set_container_form(YAMLStyle.FORM_ARRAY)      # Previously FORM_SEQ
style.set_container_form(YAMLStyle.FORM_DICTIONARY) # Previously FORM_MAP

Scalar Style and Quote Style Merged

Old version:

var style = YAML.create_style()
# Separate methods for different aspects of string formatting
style.set_scalar_style(YAMLStyle.SCALAR_LITERAL) # For block style (|)
style.set_quote_style(YAMLStyle.QUOTE_DOUBLE)    # For quoting style

New version:

var style = YAML.create_style()
# Single method combining both formatting aspects
style.set_string_style(YAMLStyle.STRING_LITERAL) # For block style (|)
style.set_string_style(YAMLStyle.STRING_QUOTE_DOUBLE) # For quoting style

The constants have been unified:

• YAMLStyle.SCALAR_PLAIN, YAMLStyle.SCALAR_LITERAL, YAMLStyle.SCALAR_FOLDED are now accessible through the STRING_* constants
• YAMLStyle.QUOTE_NONE, YAMLStyle.QUOTE_SINGLE, YAMLStyle.QUOTE_DOUBLE have been replaced with STRING_PLAIN, STRING_QUOTE_SINGLE, STRING_QUOTE_DOUBLE

Number Format Changes

Old version:

style.set_number_format(YAMLStyle.NUM_HEX)

New version:

style.set_integer_format(YAMLStyle.INT_HEX)
style.set_float_format(YAMLStyle.FLOAT_SCIENTIFIC)

Integer and float formatting have been split into two methods with dedicated enum values:

• YAMLStyle.NUM_DECIMAL, YAMLStyle.NUM_HEX, etc. are now YAMLStyle.INT_DECIMAL, YAMLStyle.INT_HEX, etc.
• YAMLStyle.NUM_SCIENTIFIC is now YAMLStyle.FLOAT_SCIENTIFIC

Removed YAMLLoader and YAMLWriter Classes

If using the old loaders, they have been integrated to the main YAML class:

Old version:

# Load YAML from a file
var data = YAMLLoader.load_file("res://data.yaml")
if YAMLLoader.last_error != null:
    print("Error loading file: ", YAMLLoader.last_error)
else:
    print("Loaded data: ", data)

# Save data to a YAML file
var data = {"key": "value", "list": [1, 2, 3]}
var success = YAMLWriter.save_file(data, "user://output.yaml")
if !success:
    print("Error saving file: ", YAMLWriter.last_error)

New version:

# Load YAML from a file
var load_result = YAML.load_file("res://example.yaml")
if load_result.has_error():
    push_error(load_result.get_error())
    return null
var data = load_result.get_data()
print("Loaded data: ", data)

# Save data to a YAML file
var save_result = YAML.save_file(data, "user://output.yaml")
if save_result.has_error():
    push_error(save_result.get_error())
    return null
var yaml_text = save_result.get_data()
print("Saved YAML:\n", yaml_text)

# The above can also be written as
var null_on_fail = YAML.try_load_file("res://example.yaml")
var success = YAML.try_save_file(data, "user://output.yaml")

Older Versions

• 0.12.1 - Build support for Linux (x86 64-bit)
• 0.12.0 - Performance optimizations, bug fixes, and comprehensive tests for all variant types
• 0.11.0 - Added support for parsing multiple documents, and error handling for custom class deserialization
• 0.10.1 - Fixed issue with custom Resources not being serializable
• 0.10.0 - Added custom class serialization support, upgraded to Godot 4.3
• 0.9.0 - Initial public release