๐Ÿ”ท Core

bx-yaml

Use this skill when serializing or deserializing YAML in BoxLang with the bx-yaml module: yamlSerialize(), yamlDeserialize(), yamlDeserializeFile(), serializing BoxLang classes to YAML, and custom toYAML() methods.

$ npx skills add ortus-boxlang/skills/boxlang-modules/bx-yaml
$ coldbox ai skills install ortus-boxlang/skills/boxlang-modules/bx-yaml
๐Ÿ”— https://skills.boxlang.io/skills/raw/ortus-boxlang/skills/boxlang-modules~bx-yaml

bx-yaml: YAML Serialization

BoxLang is the AI-native software productivity platform for building, modernizing and running applications, with developers and AI agents working together.

Installation

install-bx-module bx-yaml
# CommandBox
box install boxlang-yaml

BIFs

BIFDescription
yamlSerialize( content, [filepath], [charset] )Serialize a BoxLang value to a YAML string (or file)
yamlDeserialize( content )Parse a YAML string into a BoxLang value
yamlDeserializeFile( filepath, [charset] )Parse a YAML file into a BoxLang value

Basic Usage

// Serialize a struct to YAML
yaml = yamlSerialize( { name: "Luis", age: 21, city: "Orlando" } )

// Serialize nested structures
yaml = yamlSerialize({
    name    : "Luis",
    age     : 21,
    address : { street: "1234 Main St", city: "Orlando", state: "FL" },
    tags    : [ "admin", "developer" ]
})

// Serialize to a file
yamlSerialize( appConfig, "/app/config/settings.yml" )

// Deserialize YAML string back to BoxLang value
data = yamlDeserialize( yaml )
println( data.name )      // Luis
println( data.address.city ) // Orlando

// Deserialize from a file
config = yamlDeserializeFile( "/app/config/settings.yml" )

Config File Pattern

// Read environment config
env = server.system.environment.APP_ENV ?: "development"
config = yamlDeserializeFile( "/app/config/#env#.yml" )

// Access nested config values
dbHost = config.database.host
dbPort = config.database.port

Serializing BoxLang Classes

By default, a class with serializable = true (or no annotation) is serialized using its properties:

class serializable=true {
    property name="username" type="string"
    property name="email"    type="string"
    property name="password" type="string" yamlExclude=true  // excluded from YAML
}

user = new User().setUsername( "alice" ).setEmail( "[email protected]" )
yaml = yamlSerialize( user )
// username and email are included; password is excluded

Custom toYAML() Method

class {
    function init( name, age, city ) {
        variables.name = name
        variables.age  = age
        variables.city = city
    }

    // Only expose name and city (not age)
    function toYAML() {
        return { name: variables.name, city: variables.city }
    }
}

person = new Person( "Luis", 21, "Orlando" )
yaml = yamlSerialize( person )
// Calls toYAML() โ€” only name and city appear in output

Property-Level Exclusion Options

  • yamlExclude=true on a property โ€” exclude this property from YAML serialization
  • serializable=false on the class โ€” prevents the whole class from being serialized
  • yamlExclude list on the class โ€” list of property names to exclude

Common Pitfalls

  • โœ… Use yamlDeserializeFile() for reading config files rather than fileRead() + yamlDeserialize()
  • โŒ YAML is whitespace-sensitive โ€” don't manually construct YAML strings; always use yamlSerialize()
  • โœ… Use the yamlExclude annotation to prevent sensitive fields (passwords, tokens) from being serialized