YAML Schema to Flatfile Blueprint Converter

​

Installation

Install the plugin using npm:

npm install @flatfile/plugin-convert-yaml-schema

​

Configuration & Parameters

​

ModelToSheetConfig

Configuration object for each Sheet to be created from a YAML schema:

​

Options

Optional configuration object for the Workbook and plugin behavior:

​

PartialWorkbookConfig

Configuration for the parent Workbook:

​

Callback Function

Optional function executed after Space and Workbook configuration:

(event: FlatfileEvent, workbookIds: string[], tick: TickFunction) => any | Promise<any>

​

Usage Examples

​

Basic Usage

import { FlatfileListener } from '@flatfile/listener'
import { configureSpaceWithYamlSchema } from '@flatfile/plugin-convert-yaml-schema'

export default function (listener) {
  listener.use(
    configureSpaceWithYamlSchema([
      { sourceUrl: 'http://example.com/schemas/my-schema.yml' },
    ])
  )
}

​

Advanced Configuration

import { FlatfileListener } from '@flatfile/listener'
import { configureSpaceWithYamlSchema } from '@flatfile/plugin-convert-yaml-schema'

export default function (listener) {
  listener.use(
    configureSpaceWithYamlSchema(
      [
        {
          sourceUrl: 'https://example.com/schemas/person.yml',
          name: 'Custom Person Sheet',
        },
        {
          sourceUrl: 'https://example.com/schemas/product.yml',
        },
      ],
      {
        workbookConfig: {
          name: 'My Custom Workbook',
          actions: [
            {
              operation: 'submitActionFg',
              mode: 'foreground',
              label: 'Submit all data',
              primary: true,
            },
          ],
        },
        debug: true,
      }
    )
  )
}

​

Using Callback Function

import api from '@flatfile/api'
import { FlatfileListener } from '@flatfile/listener'
import { configureSpaceWithYamlSchema } from '@flatfile/plugin-convert-yaml-schema'

export default function (listener) {
  const callback = async (event, workbookIds, tick) => {
    const { spaceId } = event.context
    await tick(50, 'Workbook configured, creating welcome document...')
    await api.documents.create(spaceId, {
      title: 'Getting Started',
      body: '<h1>Welcome!</h1><p>Your data templates are ready.</p>',
    })
    await tick(100, 'Document created')
  }

  listener.use(
    configureSpaceWithYamlSchema(
      [{ sourceUrl: 'https://example.com/schemas/person.yml' }],
      { debug: true },
      callback
    )
  )
}

​

Troubleshooting

​

Debug Mode

The most effective troubleshooting tool is the debug: true option. When enabled, the complete generated Blueprint object is printed to the console where the listener is running. This allows you to inspect the exact Workbook, Sheet, and Field configuration that the plugin produced.

listener.use(
  configureSpaceWithYamlSchema(
    [{ sourceUrl: 'https://example.com/schemas/person.yml' }],
    { debug: true }
  )
)

​

Common Error Scenarios

Network/URL Issues: If the plugin fails to fetch a schema from a sourceUrl (e.g., due to a network error, 404 Not Found, or invalid URL), it will throw an error with a message like:

Error: Error fetching external reference: API returned status 404: Not Found

YAML Parsing Errors: Errors during YAML parsing will bubble up and cause the configuration to fail. Ensure your YAML schema files are valid and properly formatted.

​

Notes

​

Requirements and Limitations

• This plugin must be used in a server-side listener environment
• It is designed to run on the space:configure event
• The YAML schema must be publicly accessible via the provided sourceUrl
• The plugin internally converts YAML to JSON and uses @flatfile/plugin-convert-json-schema, so supported YAML schema features are limited to what the underlying JSON Schema converter supports

​

Default Behavior

• If no name is provided for a Sheet, the title from the YAML schema is used
• If no name is provided for the Workbook, it defaults to “YAML Schema Workbook”
• The debug option defaults to false

​

Error Handling

The plugin’s external fetching logic includes error handling for network failures and HTTP errors. When errors occur, they are caught by the Flatfile listener runner and reported in the corresponding Job’s execution history.