JSON import

Import blueprints, fields, and sample data in a single JSON file. This is the fastest way to set up a project structure: define everything in JSON, import it, and start working.

How to import

In the Diggama dashboard:

1. Navigate to Blueprints in the sidebar
2. Click the Import JSON button in the top-right corner
3. Paste your JSON or upload a .json file
4. Click Import

The import runs in the background. You'll receive a notification when it's done, with the number of blueprints and resources created.

TIP

If the import fails, you'll get a notification with the error message. The entire import is wrapped in a database transaction, so nothing is created on failure.

JSON format

The import expects a JSON array of blueprints. Each blueprint contains its definition, fields, and optional sample data:

[
  {
    "name": "Blog posts",
    "icon": "newspaper",
    "type": "resource",
    "record_title": "Title",
    "fields": [
      { "name": "Title", "type": "text", "rules": ["required"] },
      { "name": "Content", "type": "rich-text" }
    ],
    "data": [
      {
        "Title": "My first post",
        "Content": "<p>Hello world!</p>"
      }
    ]
  }
]

Order matters

If blueprint B has a reference field pointing to blueprint A, A must appear before B in the array, or already exist in the project.

Blueprint properties

Property	Type	Required	Description
name	string	Yes	Display name. The slug is auto-generated from this.
icon	string	No	Heroicon name (default: cube). See available icons.
type	string	No	resource, singular_resource, or readonly_resource (default: resource).
record_title	string	No	Name of the field to use as resource title. If omitted, the first text field is used.
fields	array	Yes	Field definitions (see below).
data	array	No	Sample resources to create.
variants	array	No	Multilingual variants (see Variants).

Field properties

Property	Type	Required	Description
name	string	Yes	Display name. Also used as the key in data. The slug is auto-generated.
type	string	Yes	One of the 21 field types.
rules	array	No	Validation rules, e.g. ["required"].
description	string	No	Help text shown below the field.
metadata	object	No	Type-specific configuration.

Field types

Type	JSON value	Description	Has metadata
Text	text	Single-line text input	No
Rich text	rich-text	HTML editor (WYSIWYG)	No
Choice	enum	Dropdown (single select)	Yes
Multi-choice	multi-enum	Multiple select (tags)	Yes
Number	number	Numeric input with min/max/step	Yes
Money	money	Amount + currency	Yes
Email	email	Validated email address	No
Image	image	Image upload	No
File	file	File upload	No
Link	link	Validated URL	No
Color	color	Hex color picker	No
Date	date	Date picker	No
Date & time	datetime	Date and time picker	No
Boolean	boolean	Toggle on/off	No
Slug	slug	Auto-generated from another field	Yes
Relation (single)	reference	Link to one resource	Yes
Relation (multiple)	references	Link to multiple resources	Yes
User	user	Project member selector	No
Duration	duration	Duration in minutes/hours/days	Yes
Address	address	Structured postal address	Yes
Page builder	html-page	Block-based page (see Page builder)	Yes

Field metadata

Only some field types require metadata. Here's the configuration for each.

enum / multi-enum

{
  "metadata": {
    "options": {
      "draft": "draft",
      "published": "published",
      "archived": "archived"
    }
  }
}

Options are key-value pairs where key and value are identical.

For multi-enum, you can also set:

Property	Type	Description
min_selections	integer	Minimum number of selections
max_selections	integer	Maximum number of selections

number

{
  "metadata": {
    "min": 0,
    "max": 1000,
    "step": 0.01,
    "unit": "kg",
    "precision": 2,
    "format": "grouped"
  }
}

All properties are optional:

Property	Type	Description
min	number	Minimum value
max	number	Maximum value
step	number	Increment (default: 1)
unit	string	Suffix label (e.g. kg, %)
precision	integer	Decimal places to display
format	string	"grouped" for thousand separators

money

{
  "metadata": {
    "default_currency": "EUR",
    "currencies": ["EUR", "USD", "GBP"]
  }
}

Property	Type	Description
default_currency	string	ISO currency code (default: EUR)
currencies	array	Allowed currencies (all if omitted)

Supported currencies: EUR, USD, GBP, CHF, CAD, AUD, JPY, CNY, SEK, NOK, DKK, PLN, CZK, HUF, RON, BGN, HRK, INR, BRL, MXN, ZAR, TRY, RUB, KRW, SGD, HKD, NZD, THB, TWD, AED, SAR, ILS, MAD, XOF, XAF.

slug

{
  "metadata": {
    "source": "title"
  }
}

source is the slug of the source field (auto-generated from the field name).

reference / references

Use reference_to with the slug of the target blueprint. The import resolves it to the internal ID automatically:

{
  "metadata": {
    "reference_to": "categories"
  }
}

The target blueprint can be in the same import (declared earlier) or already exist in the project.

Additional options for references:

Property	Type	Description
min	integer	Minimum number of selections
max	integer	Maximum number of selections
display_fields	string or array	Field slug(s) to show in the selector

duration

{
  "metadata": {
    "unit": "minutes",
    "min": 0,
    "max": 480,
    "display_format": "auto"
  }
}

Property	Type	Description
unit	string	minutes, hours, or days (default: minutes)
min	number	Minimum value
max	number	Maximum value
display_format	string	auto, minutes, hours, or hhmm (default: auto)

address

{
  "metadata": {
    "default_country": "FR",
    "countries": ["FR", "BE", "CH", "CA"]
  }
}

Property	Type	Description
default_country	string	ISO country code
countries	array	Allowed countries (all if omitted)

html-page

{
  "metadata": {
    "blocks": ["hero", "features", "cta"],
    "template": null
  }
}

Property	Type	Description
blocks	array	Block types editors may add (all if omitted or empty). See the block reference
template	string	Starting template that pre-fills new pages

Sample data

The data array contains resources to create. Each entry is an object where keys are field names (not slugs): the import maps them automatically.

{
  "data": [
    {
      "Title": "My post",
      "Category": "news",
      "Featured": true
    }
  ]
}

All imported resources are published immediately.

Data values by field type

Field type	Value format	Example
text	string	"Hello"
rich-text	string (HTML)	"<p>Hello <b>world</b></p>"
enum	string	"news"
multi-enum	array of strings	["news", "featured"]
number	number	42.5
money	object	{"amount": 29.99, "currency": "EUR"}
email	string	"[email protected]"
image	string or null	null
file	string or null	null
link	string (URL)	"https://example.com"
color	string (hex)	"#FF5733"
date	string	"2026-01-15"
datetime	string	"2026-01-15 14:30:00"
boolean	boolean	true
slug	string	"my-post"
reference	string (target resource slug)	"acme-corp"
references	array of strings (slugs)	["tag-1", "tag-2"]
user	integer (user ID)	1
duration	number	90
address	object	{"street": "1 Main St", "city": "Paris", "postal_code": "75001", "country": "FR"}
html-page	object (block tree)	{"version": 1, "blocks": [{"id": "hero-1", "type": "hero", "props": {"title": "Hello"}}]}

Address sub-fields

Field	Type	Description
street	string	Street line 1
street2	string	Street line 2 (optional)
postal_code	string	Postal / ZIP code
city	string	City
state	string	State or region (optional)
country	string	ISO country code (e.g. FR)

Cross-blueprint references in data

Reference and references fields accept resource slugs as values. The import resolves them to internal IDs automatically.

For this to work, the target resource must have a field named Slug (or slug) in its data:

[
  {
    "name": "Categories",
    "fields": [
      { "name": "Name", "type": "text", "rules": ["required"] },
      { "name": "Slug", "type": "slug", "metadata": { "source": "name" } }
    ],
    "data": [
      { "Name": "Tech", "Slug": "tech" }
    ]
  },
  {
    "name": "Posts",
    "fields": [
      { "name": "Title", "type": "text", "rules": ["required"] },
      { "name": "Category", "type": "reference", "metadata": { "reference_to": "categories" } }
    ],
    "data": [
      { "Title": "My post", "Category": "tech" }
    ]
  }
]

The value "tech" in the Category field is resolved to the internal ID of the "Tech" resource.

Variants

To import multilingual blueprints, add a variants array:

{
  "name": "Pages",
  "variants": [
    { "name": "English", "slug": "en", "is_default": true },
    { "name": "French", "slug": "fr", "is_default": false }
  ],
  "fields": [ ... ]
}

Property	Type	Description
name	string	Display name
slug	string	Variant identifier (e.g. en, fr)
is_default	boolean	Exactly one variant must be the default

Available icons

Icons are Heroicons (outline style). Use just the name without any prefix:

academic-cap adjustments-horizontal archive-box arrow-down-tray arrow-trending-up banknotes beaker bell bolt book-open bookmark briefcase building-office building-storefront calculator calendar camera chart-bar chart-pie chat-bubble-left-right check-circle clipboard-document-list clock cloud code-bracket cog command-line credit-card cube currency-dollar document document-text envelope face-smile film fire flag folder gift globe-alt heart home inbox key light-bulb link list-bullet lock-closed map megaphone musical-note newspaper paint-brush paper-airplane pencil phone photo puzzle-piece rocket-launch server shopping-bag shopping-cart sparkles star tag ticket trophy truck tv user user-group video-camera wallet wrench x-circle

Full example

A complete CRM import with cross-blueprint references:

[
  {
    "name": "Companies",
    "icon": "building-office",
    "type": "resource",
    "record_title": "Name",
    "fields": [
      { "name": "Name", "type": "text", "rules": ["required"] },
      { "name": "Slug", "type": "slug", "metadata": { "source": "name" } },
      { "name": "Website", "type": "link" },
      { "name": "Industry", "type": "enum", "metadata": { "options": { "SaaS": "SaaS", "E-commerce": "E-commerce", "Fintech": "Fintech" } } },
      { "name": "Employees", "type": "number", "metadata": { "min": 1, "format": "grouped" } },
      { "name": "Revenue", "type": "money", "metadata": { "default_currency": "USD" } },
      { "name": "Active", "type": "boolean" }
    ],
    "data": [
      {
        "Name": "Acme Corp",
        "Slug": "acme-corp",
        "Website": "https://acme.com",
        "Industry": "SaaS",
        "Employees": 150,
        "Revenue": { "amount": 5000000, "currency": "USD" },
        "Active": true
      },
      {
        "Name": "GreenCart",
        "Slug": "greencart",
        "Website": "https://greencart.com",
        "Industry": "E-commerce",
        "Employees": 15,
        "Revenue": { "amount": 800000, "currency": "USD" },
        "Active": true
      }
    ]
  },
  {
    "name": "Contacts",
    "icon": "user-group",
    "type": "resource",
    "record_title": "Name",
    "fields": [
      { "name": "Name", "type": "text", "rules": ["required"] },
      { "name": "Email", "type": "email", "rules": ["required"] },
      { "name": "Company", "type": "reference", "metadata": { "reference_to": "companies" } },
      { "name": "Role", "type": "text" },
      { "name": "Status", "type": "enum", "metadata": { "options": { "New": "New", "Contacted": "Contacted", "Qualified": "Qualified", "Won": "Won", "Lost": "Lost" } } },
      { "name": "Tags", "type": "multi-enum", "metadata": { "options": { "decision-maker": "decision-maker", "technical": "technical", "vip": "vip" } } }
    ],
    "data": [
      {
        "Name": "Sarah Chen",
        "Email": "[email protected]",
        "Company": "acme-corp",
        "Role": "Head of Marketing",
        "Status": "Qualified",
        "Tags": ["decision-maker"]
      },
      {
        "Name": "Emily Parker",
        "Email": "[email protected]",
        "Company": "greencart",
        "Role": "Founder",
        "Status": "Won",
        "Tags": ["decision-maker", "vip"]
      }
    ]
  }
]