JSON Schema Converter
Automatically transform JSON Schema into Flatfile Blueprint for streamlined data model setup
The JSON Schema Converter plugin for Flatfile automatically transforms a JSON Schema into a Flatfile Blueprint. A Blueprint is Flatfile’s Data Definition Language (DDL) used for defining data models, validations, and transformations.
The primary purpose of this plugin is to streamline the setup of a Flatfile Space. Instead of manually defining each field for your Sheets, you can provide a JSON Schema, and the plugin will generate the corresponding Workbooks and Sheets configuration. This is particularly useful for projects that already use JSON Schema for data validation or API definitions, allowing for a single source of truth for data structures.
The plugin is designed to be used in a server-side Flatfile listener, typically on the space:configure
event. It can fetch schemas from a URL, use a direct JSON object, or execute a function to retrieve the schema dynamically.
Installation
Configuration & Parameters
The plugin is configured via a single object passed to the configureSpaceWithJsonSchema
function. This object is of type JsonSetupFactory
.
JsonSetupFactory
Parameter | Type | Required | Description |
---|---|---|---|
workbooks | PartialWorkbookConfig[] | Yes | An array of workbook configurations to be created in the Space |
space | Partial<Flatfile.spaces.SpaceConfig> | No | Configuration details for the Space itself, like metadata or themes |
PartialWorkbookConfig
Parameter | Type | Required | Description |
---|---|---|---|
name | string | Yes | The name of the Workbook |
sheets | PartialSheetConfig[] | Yes | An array of sheet configurations within the Workbook |
actions | Flatfile.Action[] | No | Actions available at the Workbook level |
PartialSheetConfig
Parameter | Type | Required | Description |
---|---|---|---|
source | object | string | (() => object | Promise<object>) | Yes | The JSON Schema for the sheet. Can be a direct JSON Schema object, a string URL pointing to a schema file, or an async function that returns a schema object |
name | string | No | The name of the Sheet. Defaults to the title property from the root of the JSON Schema if not provided |
slug | string | No | A unique identifier for the sheet |
actions | Flatfile.Action[] | No | Actions available at the Sheet level |
Default Behavior
By default, the plugin will create Workbooks and Sheets as defined in the workbooks
array. For each sheet, it parses the source
JSON schema, converting its properties
into Flatfile fields. Nested objects in the schema are flattened into fields with names like parentKey_childKey
. The sheet’s name defaults to the schema’s title
if not explicitly provided.
Usage Examples
Basic Usage with URL Schema
Local Schema with Callback
Dynamic Schema from Function
Using fetchExternalReference with Error Handling
Troubleshooting
Job Fails on space:configure
Check the Job status in the Flatfile Dashboard for error messages. Common causes include:
- An invalid URL was provided for a schema
source
- The schema at the URL is not valid JSON
- A
$ref
in the schema points to a location that cannot be resolved
Fields Not Appearing as Expected
- Ensure the JSON schema has a
properties
object at the level you expect fields to be generated from - Nested objects are flattened with an underscore (
_
) separator. For example, anaddress
object with astreet
property becomes a field with the keyaddress_street
- Check the data types in your schema. Supported types include
string
,number
,integer
,boolean
, andarray
(which becomesstring-list
).enum
is also supported. Unrecognized types will be ignored
Notes
Special Considerations
- This plugin is intended for use in server-side listeners, specifically for the
space:configure
event - The plugin handles JSON schema references (
$ref
). It can resolve local references within the same schema (e.g.,#/definitions/address
) and external references to other files (e.g.,common.json#/definitions/name
). External references are resolved relative to the$id
property of the schema they are in - The plugin makes API calls on behalf of the user, including
api.spaces.update
andapi.workbooks.create
Error Handling
Errors during schema fetching (fetchExternalReference
) or reference resolution will bubble up. When used within a Flatfile listener, these unhandled exceptions will cause the associated Job to fail, which is the standard error handling pattern in the Flatfile ecosystem. The Job’s execution history will contain details about the error.
It is the user’s responsibility to ensure that the provided JSON schemas are valid and that any URLs are accessible from the server environment where the listener is running.