Crate hedl_yaml 

HEDL YAML Conversion

Provides bidirectional conversion between HEDL documents and YAML format, with comprehensive support for HEDL’s rich type system and data structures.

Important Limitations

When converting HEDL to YAML and back, certain HEDL-specific metadata is not preserved:

• ALIAS declarations: Type aliases are lost (YAML has no equivalent concept)
• NEST definitions: Entity hierarchy declarations are lost (only structure remains)
• STRUCT schemas: Explicit field constraints and type declarations are lost
• Type constraints: Validation rules (min/max/format) are not preserved
• Document metadata: Version, author, license, etc. are not preserved

YAML is an excellent format for data exchange and configuration, but it lacks the type system and schema capabilities of HEDL’s native format. See the README for detailed examples and recommended workarounds.

What IS Preserved

The following are preserved during YAML conversion:

• Scalar values (strings, numbers, booleans, null)
• References (local and qualified)
• Expressions
• Tensors (multi-dimensional arrays)
• Objects and nested structures
• Matrix lists (inferred schemas)
• Hierarchical relationships (structural only)

Examples

Converting HEDL to YAML

use hedl_core::{Document, Item, Value};
use hedl_yaml::{to_yaml, ToYamlConfig};
use std::collections::BTreeMap;

let mut doc = Document {
    version: (1, 0),
    schema_versions: BTreeMap::new(),
    aliases: BTreeMap::new(),
    structs: BTreeMap::new(),
    nests: BTreeMap::new(),
    root: BTreeMap::new(),
};
let mut root = BTreeMap::new();
root.insert("name".to_string(), Item::Scalar(Value::String("example".to_string().into())));
root.insert("count".to_string(), Item::Scalar(Value::Int(42)));
doc.root = root;

let config = ToYamlConfig::default();
let yaml = to_yaml(&doc, &config).unwrap();
println!("{}", yaml);

Converting YAML to HEDL

use hedl_yaml::{from_yaml, FromYamlConfig};

let yaml = r#"
name: example
count: 42
active: true
"#;

// Use default configuration with high limits (500MB / 10M / 10K)
let config = FromYamlConfig::default();
let doc = from_yaml(yaml, &config).unwrap();
assert_eq!(doc.version, (2, 0));

Customizing Resource Limits

use hedl_yaml::{from_yaml, FromYamlConfig};

// For untrusted input, use conservative limits
let config = FromYamlConfig::builder()
    .max_document_size(10 * 1024 * 1024)  // 10 MB
    .max_array_length(100_000)             // 100K elements
    .max_nesting_depth(100)                // 100 levels
    .build();

let yaml = "name: test\nvalue: 123\n";
let doc = from_yaml(yaml, &config).unwrap();

Round-trip Conversion (with Metadata Loss)

use hedl_core::{Document, Item, Value};
use hedl_yaml::{to_yaml, from_yaml, ToYamlConfig, FromYamlConfig};
use std::collections::BTreeMap;

// Create original document
let mut doc = Document {
    version: (1, 0),
    schema_versions: BTreeMap::new(),
    aliases: BTreeMap::new(),
    structs: BTreeMap::new(),
    nests: BTreeMap::new(),
    root: BTreeMap::new(),
};
let mut root = BTreeMap::new();
root.insert("test".to_string(), Item::Scalar(Value::String("value".to_string().into())));
doc.root = root;

// Convert to YAML and back
let to_config = ToYamlConfig::default();
let yaml = to_yaml(&doc, &to_config).unwrap();

let from_config = FromYamlConfig::default();
let restored = from_yaml(&yaml, &from_config).unwrap();

// Data is preserved, but version defaults to v2.0 (not preserved in YAML)
assert_eq!(restored.version, (2, 0));

Preserving Metadata with Hints

use hedl_core::{Document, Item, Value};
use hedl_yaml::{to_yaml, ToYamlConfig};
use std::collections::BTreeMap;

let mut doc = Document {
    version: (1, 0),
    schema_versions: BTreeMap::new(),
    aliases: BTreeMap::new(),
    structs: BTreeMap::new(),
    nests: BTreeMap::new(),
    root: BTreeMap::new(),
};
let mut root = BTreeMap::new();
root.insert("count".to_string(), Item::Scalar(Value::Int(42)));
doc.root = root;

// Enable metadata hints in YAML output
let config = ToYamlConfig {
    include_metadata: true,  // Adds __type__ and __schema__ hints
    ..Default::default()
};
let yaml = to_yaml(&doc, &config).unwrap();
// YAML includes type hints, but they won't prevent data-only schemas

Re-exports

pub use error::ErrorContext;

pub use error::YamlError;

pub use from_yaml::from_yaml;

pub use from_yaml::from_yaml_value;

pub use from_yaml::FromYamlConfig;

pub use from_yaml::FromYamlConfigBuilder;

pub use from_yaml::DEFAULT_MAX_ARRAY_LENGTH;

pub use from_yaml::DEFAULT_MAX_DOCUMENT_SIZE;

pub use from_yaml::DEFAULT_MAX_NESTING_DEPTH;

Modules

error

YAML error types. Error types for YAML conversion operations.

from_yaml

YAML to HEDL conversion. YAML to HEDL conversion

yaml_scanner

YAML token scanning. YAML text scanner for extracting anchor and alias information.

Structs

ToYamlConfig

Configuration for YAML output

Functions

hedl_to_yaml

Convert HEDL document to YAML string with default configuration

to_yaml

Convert Document to YAML string

to_yaml_value

Convert Document to serde_yaml::Value

yaml_to_hedl

Convert YAML string to HEDL document with default configuration