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:

Navigate to Blueprints in the sidebar
Click the Import JSON button in the top-right corner
Paste your JSON or upload a .json file
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:

json

[
  {
    "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 20 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
Reference	`reference`	Link to one resource	Yes
References	`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

Field metadata

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

`enum` / `multi-enum`

json

{
  "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`

json

{
  "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`

json

{
  "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`

json

{
  "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:

json

{
  "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`

json

{
  "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`

json

{
  "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)

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.

json

{
  "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	`"hello@example.com"`
`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"}`

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:

json

[
  {
    "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:

json

{
  "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:

json

[
  {
    "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": "sarah@acme.com",
        "Company": "acme-corp",
        "Role": "Head of Marketing",
        "Status": "Qualified",
        "Tags": ["decision-maker"]
      },
      {
        "Name": "Emily Parker",
        "Email": "emily@greencart.com",
        "Company": "greencart",
        "Role": "Founder",
        "Status": "Won",
        "Tags": ["decision-maker", "vip"]
      }
    ]
  }
]

JSON import ​

How to import ​

JSON format ​

Blueprint properties ​

Field properties ​

Field types ​

Field metadata ​

enum / multi-enum ​

number ​

money ​

slug ​

reference / references ​

duration ​

address ​

Sample data ​

Data values by field type ​

Address sub-fields ​

Cross-blueprint references in data ​

Variants ​

Available icons ​

Full example ​

JSON import

How to import

JSON format

Blueprint properties

Field properties

Field types

Field metadata

`enum` / `multi-enum`

`number`

`money`

`slug`

`reference` / `references`

`duration`

`address`

Sample data

Data values by field type

Address sub-fields

Cross-blueprint references in data

Variants

Available icons

Full example