Skip to content

Conversation

@horner
Copy link

@horner horner commented Jul 5, 2025

See issue:
#7009

Overview

This PR implements YAML support for SurveyJS Creator, allowing users to work with survey definitions in YAML format as an interchangeable alternative to JSON.

Why YAML?

  • Human-friendly: YAML is significantly easier to read and write by hand than JSON, especially for complex survey structures.
  • Better for version control: Line-based diffs in Git are easier to interpret and resolve in YAML.
  • DevOps and infrastructure alignment: YAML is the de facto format for configuration in modern ecosystems (e.g., Kubernetes, GitHub Actions, Ansible).

Features Added

🔧 Core YAML Utilities

  • SurveyYAML utility class with parsing, stringification, and validation methods
  • Format conversion between JSON and YAML with error handling
  • Custom formatting options for YAML output (indentation, line width, etc.)

📝 Creator API Extensions

New properties and methods added to SurveyCreatorBase:

// Get/set survey as YAML
creator.yamlText = yamlString;
const yaml = creator.yamlText;

// File operations
creator.exportToYAMLFile('survey.yml');
creator.importFromYAMLFileDOM();

// Utility methods
const yaml = creator.toYAML();
creator.fromYAML(yamlString);

🎛️ YAML Editor Plugin

  • New editor tab extending the existing JSON editor functionality
  • Real-time YAML validation with error reporting
  • Toolbar actions for import/export/copy operations
  • Seamless integration with the existing tab system

📁 File Import/Export

  • Native file operations for .yaml and .yml formats
  • Browser-compatible download/upload functionality
  • Action creators for UI integration
  • Error handling for invalid files

Example Usage

Basic YAML Survey Definition

title: Customer Satisfaction Survey
description: Please help us improve our service
pages:
  - name: page1
    elements:
      - type: text
        name: firstName
        title: First Name
        isRequired: true
      - type: rating
        name: satisfaction
        title: Overall Satisfaction
        rateMin: 1
        rateMax: 10

Programmatic Usage

// Convert existing JSON survey to YAML
const yamlString = SurveyYAML.jsonToYaml(jsonString);

// Parse YAML survey definition
const surveyObj = SurveyYAML.parse(yamlString);

// Round-trip conversion
creator.yamlText = yamlString;
const backToYaml = creator.yamlText;

Implementation Details

  • Leverages js-yaml library for robust YAML parsing
  • Maintains backward compatibility - all existing JSON APIs unchanged
  • Follows existing patterns in the codebase for consistency
  • Comprehensive error handling with user-friendly messages
  • Full Unicode support for international content

Testing

  • 10/10 manual tests passing covering all functionality
  • Round-trip conversion validation (JSON ↔ YAML ↔ JSON)
  • Error handling for invalid YAML syntax
  • Special characters and Unicode support
  • File operations simulation
  • Integration tests for creator API

Documentation

  • 📚 Complete API documentation with examples
  • 🔍 Usage examples for HTML, React, and Node.js
  • 📋 Sample YAML surveys demonstrating features
  • 🛠️ Migration guide from existing JSON surveys

Browser Compatibility

Works in all modern browsers supporting:

  • ES6+ features
  • File API for import/export
  • Blob API for downloads

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant