Skip to main content

Import Profiles

Import Profiles are reusable scope trees that drive the JSON import pipeline. Instead of re-specifying which entities a JSON payload should populate every time, you author a profile once and reuse it for every payload of that shape.

Find the admin at Admin → Import. Route: /admin/import. API: /import-profiles (CRUD) and /import (the apply endpoint).

What a profile contains​

A profile names a scope tree — a nested structure that maps JSON paths to target entity types and their parent keys. For example:

{
  "name": "HH-DM Sebring import",
  "scope": {
    "Event": {
      "field": "event",
      "children": {
        "Session": { "field": "sessions", "primaryKey": "name" },
        "Car":     { "field": "cars",     "primaryKey": "carNumber" }
      }
    }
  }
}

When you POST a JSON payload to /import with this profile, the server:

  1. Walks the payload following the scope tree
  2. Resolves each target entity (create or update by primary key)
  3. Wires parent foreign keys automatically as it descends
  4. Returns a per-entity counts summary

The admin​

The admin screen is master/detail:

  • Left — list of saved profiles
  • Right — scope-tree editor + a JSON pasting area for a preview / dry-run apply

The editor lets you add / remove / rename nodes, set the field and primaryKey per node, and toggle child types. There is also a raw-JSON tab for power editing.

Apply​

Once a profile is saved, run the import:

POST /import
{
  "profileId": "<id>",
  "payload": { ... your JSON ... },
  "dryRun": false
}

Set dryRun: true to get the would-affect counts without writing anything.

What you can do today​

  • Author / edit / delete import profiles
  • Paste a payload and apply it through a profile
  • Dry-run preview to confirm counts before committing

What's coming​

  • CSV import — today only JSON is wired; CSV parsing is planned via the edge ingester adapter
  • Re-runnable import history — see what was applied, revert
  • Schema-validated payloads — declare expected shape per profile and reject invalid payloads early