JSON Format Reference

This page documents the JSON format used by InfoBuilder for exporting and importing stores. It is intended for both humans and automated systems (AI agents, scripts, integrations) that need to produce or consume InfoBuilder-compatible files.

A JSON Schema (draft-07) is included at the bottom of this page for machine validation.

Top-level structure

Every InfoBuilder export is a single JSON object with these root keys:

{
  "version": 1,
  "exportedAt": "2025-05-31T14:30:00.000Z",
  "store": { ... },
  "entityTypes": [ ... ],
  "relationshipTypes": [ ... ],
  "entities": [ ... ],
  "relationships": [ ... ]
}

Key	Type	Required	Description
`version`	integer	Yes	Export format version. Must be `1`.
`exportedAt`	string (ISO-8601)	Yes	UTC timestamp of when the export was generated.
`store`	object	Yes	Store metadata (name, description).
`entityTypes`	array	Yes	Schema definitions for each kind of entity.
`relationshipTypes`	array	Yes	Schema definitions for each kind of relationship.
`entities`	array	Yes	Actual entity instances.
`relationships`	array	Yes	Actual relationship instances.

`store`

Metadata for the store being exported:

{
  "name": "My Contacts",
  "description": "People, organisations, and meetings."
}

Key	Type	Required	Description
`name`	string	Yes	Store name. Must be non-empty after trimming whitespace.
`description`	string \| null	No	Optional human-readable description of the store's purpose.

`entityTypes`

An array of entity type definitions. Each entity type defines a kind of object in the store (e.g. "Person", "Organisation", "Album"). Names must be unique within the export.

{
  "name": "person",
  "display_name": "Person",
  "icon": "person",
  "fields": [ ... ]
}

Key	Type	Required	Description
`name`	string	Yes	Machine-readable identifier used to reference this type in entity instances and relationship type definitions.
`display_name`	string	Yes	Human-readable label shown in the InfoBuilder UI.
`icon`	string \| null	No	Lowercase alphanumeric slug (e.g. `"person"`, `"briefcase"`). Must match `/^[a-z0-9-]{1,40}$/` or be `null`.
`fields`	array	No	Array of field definitions. Defaults to empty.

`relationshipTypes`

An array of relationship type definitions. Each describes a named link between two entity types (e.g. "WorksFor" from "person" to "organisation"). Names must be unique within the export.

{
  "name": "WorksFor",
  "source_entity_type": "person",
  "target_entity_type": "organisation",
  "directed": true,
  "inverse_label": "Employs",
  "fields": [ ... ]
}

Key	Type	Required	Description
`name`	string	Yes	Machine-readable identifier used to reference this type in relationship instances.
`source_entity_type`	string	Yes	The `name` of the entity type that is the source (origin) of this relationship.
`target_entity_type`	string	Yes	The `name` of the entity type that is the target (destination) of this relationship.
`directed`	boolean	No	Whether the relationship is one-way (`true`) or bidirectional (`false`). Defaults to `true` on import if omitted.
`inverse_label`	string \| null	No	Label to read the relationship in the opposite direction (e.g. "Employs" is the inverse of "WorksFor"). Nullable.
`fields`	array	No	Array of field definitions for attributes on the relationship itself. Defaults to empty.

Field definition

Both entity types and relationship types can carry an array of field definitions. Each field definition describes one attribute that instances of that type can hold.

{
  "name": "email",
  "data_type": "email",
  "required": false,
  "display_order": 1
}

Key	Type	Required	Description
`name`	string	Yes	Field name. Used as the key in `field_values` on instances.
`data_type`	string (enum)	Yes	The field's data type. See valid values below.
`required`	boolean	No	Whether the field must be present when creating or updating instances. Defaults to `false`.
`display_order`	integer	No	Position in UI forms and tables (0 = first). Defaults to `0`.

Valid `data_type` values

Value	Description
`string`	Short single-line text.
`text`	Long multi-line text.
`email`	Email address.
`phone`	Phone number.
`url`	Web URL.
`date`	Calendar date (e.g. `2025-05-31`).
`datetime`	Date and time (ISO-8601, e.g. `2025-05-31T14:30:00Z`).
`partial_date`	Partial date where day or month may be unknown (e.g. `2025-05` or `2025`).

`entities`

An array of actual entity instances. Each instance belongs to one of the entity types defined in entityTypes.

{
  "_id": "550e8400-e29b-41d4-a716-446655440000",
  "entity_type": "person",
  "field_values": {
    "full_name": "Alice Johnson",
    "email": "alice@example.com",
    "birthday": "1990-03-15"
  }
}

Key	Type	Required	Description
`_id`	string (UUID)	Yes	The entity's original UUID. Prefixed with `_` to avoid namespace conflicts. Used during import to re-link relationships; a new UUID is assigned on import.
`entity_type`	string	Yes	Must match the `name` of an entry in `entityTypes`.
`field_values`	object	No	Key-value pairs of field data. Keys are field names from the entity type's `fields` array. Values are arbitrary JSON (string, number, boolean, null).

`relationships`

An array of actual relationship instances. Each instance connects two entities via one of the relationship types defined in relationshipTypes. Relationships with missing entity references are silently skipped on import.

{
  "relationship_type": "WorksFor",
  "source_entity_id": "550e8400-e29b-41d4-a716-446655440000",
  "target_entity_id": "660e8400-e29b-41d4-a716-446655440001",
  "field_values": {
    "job_title": "Senior Engineer",
    "start_date": "2020-01-15"
  }
}

Key	Type	Required	Description
`relationship_type`	string	Yes	Must match the `name` of an entry in `relationshipTypes`.
`source_entity_id`	string (UUID)	Yes	Must match the `_id` of an entity in `entities`.
`target_entity_id`	string (UUID)	Yes	Must match the `_id` of an entity in `entities`.
`field_values`	object	No	Key-value pairs of relationship attribute data. Keys are field names from the relationship type's `fields` array.

Complete example

A minimal but complete export with two entity types, one relationship type, two entities, and one relationship:

{
  "version": 1,
  "exportedAt": "2025-05-31T14:30:22.456Z",
  "store": {
    "name": "My Contacts",
    "description": "People and the organisations they work for."
  },
  "entityTypes": [
    {
      "name": "person",
      "display_name": "Person",
      "icon": "person",
      "fields": [
        { "name": "full_name",  "data_type": "string", "required": true,  "display_order": 0 },
        { "name": "email",      "data_type": "email",  "required": false, "display_order": 1 },
        { "name": "birthday",   "data_type": "date",   "required": false, "display_order": 2 }
      ]
    },
    {
      "name": "organisation",
      "display_name": "Organisation",
      "icon": "briefcase",
      "fields": [
        { "name": "name",    "data_type": "string", "required": true,  "display_order": 0 },
        { "name": "website", "data_type": "url",    "required": false, "display_order": 1 }
      ]
    }
  ],
  "relationshipTypes": [
    {
      "name": "WorksFor",
      "source_entity_type": "person",
      "target_entity_type": "organisation",
      "directed": true,
      "inverse_label": "Employs",
      "fields": [
        { "name": "job_title",  "data_type": "string", "required": false, "display_order": 0 },
        { "name": "start_date", "data_type": "date",   "required": false, "display_order": 1 }
      ]
    }
  ],
  "entities": [
    {
      "_id": "550e8400-e29b-41d4-a716-446655440000",
      "entity_type": "person",
      "field_values": {
        "full_name": "Alice Johnson",
        "email": "alice@example.com",
        "birthday": "1990-03-15"
      }
    },
    {
      "_id": "660e8400-e29b-41d4-a716-446655440001",
      "entity_type": "organisation",
      "field_values": {
        "name": "Acme Corp",
        "website": "https://acme.example.com"
      }
    }
  ],
  "relationships": [
    {
      "relationship_type": "WorksFor",
      "source_entity_id": "550e8400-e29b-41d4-a716-446655440000",
      "target_entity_id": "660e8400-e29b-41d4-a716-446655440001",
      "field_values": {
        "job_title": "Senior Engineer",
        "start_date": "2020-01-15"
      }
    }
  ]
}

Import validation rules

InfoBuilder enforces these rules when a file is imported. Files that fail validation are rejected with an error; the existing stores are never modified.

version must equal 1.
store.name must be present and non-empty after trimming whitespace.
All entityTypes[].name values must be unique within the file.
All relationshipTypes[].name values must be unique within the file.
Each relationshipTypes[].source_entity_type and target_entity_type must match a name in entityTypes.
Each entities[].entity_type must match a name in entityTypes.
Each relationships[].relationship_type must match a name in relationshipTypes.
Each relationships[].source_entity_id and target_entity_id must match a _id in entities (relationships with missing references are silently skipped, not rejected).
Each data_type value must be one of the eight valid types listed above.
Each icon slug must match /^[a-z0-9-]{1,40}$/ or be null.

Import always creates a new store — it never overwrites an existing one. All IDs are re-generated as fresh UUIDs on import.

JSON Schema (draft-07)

The following JSON Schema can be used to validate an InfoBuilder export file programmatically. Copy the schema block and pass it to any JSON Schema validator.

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "InfoBuilder Export Format",
  "description": "Schema for InfoBuilder version-1 store export/import files.",
  "type": "object",
  "required": ["version", "exportedAt", "store", "entityTypes", "relationshipTypes", "entities", "relationships"],
  "additionalProperties": false,
  "properties": {
    "version":           { "type": "integer", "const": 1 },
    "exportedAt":        { "type": "string", "format": "date-time" },
    "store":             { "$ref": "#/definitions/Store" },
    "entityTypes":       { "type": "array", "items": { "$ref": "#/definitions/EntityTypeDefinition" } },
    "relationshipTypes": { "type": "array", "items": { "$ref": "#/definitions/RelationshipTypeDefinition" } },
    "entities":          { "type": "array", "items": { "$ref": "#/definitions/EntityInstance" } },
    "relationships":     { "type": "array", "items": { "$ref": "#/definitions/RelationshipInstance" } }
  },
  "definitions": {
    "Store": {
      "type": "object",
      "required": ["name"],
      "additionalProperties": false,
      "properties": {
        "name":        { "type": "string", "minLength": 1 },
        "description": { "type": ["string", "null"] }
      }
    },
    "FieldDefinition": {
      "type": "object",
      "required": ["name", "data_type"],
      "additionalProperties": false,
      "properties": {
        "name":          { "type": "string" },
        "data_type":     { "type": "string", "enum": ["string", "text", "email", "phone", "url", "date", "datetime", "partial_date"] },
        "required":      { "type": "boolean", "default": false },
        "display_order": { "type": "integer", "default": 0 }
      }
    },
    "EntityTypeDefinition": {
      "type": "object",
      "required": ["name", "display_name"],
      "additionalProperties": false,
      "properties": {
        "name":         { "type": "string" },
        "display_name": { "type": "string" },
        "icon":         { "type": ["string", "null"], "pattern": "^[a-z0-9-]{1,40}$" },
        "fields":       { "type": "array", "items": { "$ref": "#/definitions/FieldDefinition" }, "default": [] }
      }
    },
    "RelationshipTypeDefinition": {
      "type": "object",
      "required": ["name", "source_entity_type", "target_entity_type"],
      "additionalProperties": false,
      "properties": {
        "name":                 { "type": "string" },
        "source_entity_type":   { "type": "string" },
        "target_entity_type":   { "type": "string" },
        "directed":             { "type": "boolean", "default": true },
        "inverse_label":        { "type": ["string", "null"] },
        "fields":               { "type": "array", "items": { "$ref": "#/definitions/FieldDefinition" }, "default": [] }
      }
    },
    "EntityInstance": {
      "type": "object",
      "required": ["_id", "entity_type"],
      "additionalProperties": false,
      "properties": {
        "_id":          { "type": "string" },
        "entity_type":  { "type": "string" },
        "field_values": { "type": "object" }
      }
    },
    "RelationshipInstance": {
      "type": "object",
      "required": ["relationship_type", "source_entity_id", "target_entity_id"],
      "additionalProperties": false,
      "properties": {
        "relationship_type":  { "type": "string" },
        "source_entity_id":   { "type": "string" },
        "target_entity_id":   { "type": "string" },
        "field_values":       { "type": "object" }
      }
    }
  }
}

← Back to file list

JSON Format Reference

Top-level structure

store

entityTypes

relationshipTypes