Automatically transform JSON Schema into Flatfile Blueprint for streamlined data model setup
space:configure
event. It can fetch schemas from a URL, use a direct JSON object, or execute a function to retrieve the schema dynamically.
configureSpaceWithJsonSchema
function. This object is of type 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 |
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 |
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 |
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.
space:configure
source
$ref
in the schema points to a location that cannot be resolvedproperties
object at the level you expect fields to be generated from_
) separator. For example, an address
object with a street
property becomes a field with the key address_street
string
, number
, integer
, boolean
, and array
(which becomes string-list
). enum
is also supported. Unrecognized types will be ignoredspace:configure
event$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 inapi.spaces.update
and api.workbooks.create
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.