Skip to content

Yaml support #7010

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Yaml support #7010

wants to merge 3 commits into from

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.

2 participants