Build a record storage entity

Step-by-step checklist for entityType: recordStorage — CRM-style entities with normalized metadata, sync, and governed capabilities.

Prerequisites

External system JSON with type: openapi (or compatible type)
Resource type registered in catalog (customer, contact, deal, …)
Integration folder: integration/<systemKey>/

Where it lives

One JSON file per business entity, for example integration/<systemKey>/<systemKey>-datasource-companies.json.

Required root fields: key, displayName, systemKey, entityType, resourceType.

How to set

Copy a known-good record fixture and trim — do not start from {}. Align systemKey with the system file and list the file in application.yaml.
Set identity band (required for recordStorage):

{
  "key": "example-companies",
  "displayName": "Companies",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"],
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": {
        "type": "string",
        "index": true,
        "description": "Stable join identity across datasources"
      },
      "name": { "type": "string", "index": true, "filter": true }
    }
  }
}

Add fieldMappings.attributes — map vendor payload paths to normalized names. See Field mappings.
Configure sync — inbound record sync (schedule, operations, pagination). Validator expects sync shape for recordStorage.
Configure exposed — governed capabilities (read, search, create, …) with OpenAPI operation bindings.
Add dimensions (recommended) — top-level dimensions object with local or fk bindings. See Configure business policies.
Repair manifest drift:

aifabrix repair <systemKey> --dry-run
aifabrix repair <systemKey> --expose --rbac

Validate in tight loops:

aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>

Upload and E2E after integration is green — see Test ladder.

Defaults and examples

Field	recordStorage rule
`key`	Unique datasource key listed in `application.yaml`
`displayName`	Human label in UI and logs
`systemKey`	Must match `<systemKey>-system.json`
`entityType`	Must be `recordStorage`
`resourceType`	Top-level catalog key (`customer`, not vendor name)
`primaryKey`	Array of normalized attribute names
`externalId`	Required indexed string in `metadataSchema` — global join identity
`sync`	Record pull/push configuration
`exposed`	Capability gateway for AI and workers

Typical CRM split: one business entity file per entity (companies → customer, contacts → contact, deals → deal).

Minimal capabilities and exposed bands (trim from a validated fixture):

{
  "capabilities": [
    { "key": "list", "description": "List companies", "riskLevel": "low" },
    { "key": "get", "description": "Get company by id", "riskLevel": "low" }
  ],
  "exposed": {
    "filterable": ["name", "country"],
    "schema": {
      "externalId": "metadata.externalId",
      "name": "metadata.name",
      "country": "metadata.country"
    }
  }
}

Validate

aifabrix resource-type list
aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>
aifabrix test-integration <systemKey>
aifabrix datasource test-e2e <datasourceKey> --app <systemKey>

Common mistakes

Mistake	Fix
Missing `externalId` in metadataSchema	Add indexed string property
Missing root `resourceType`	Set catalog key; create in catalog first
recordStorage without sync	Add sync block or confirm entityType choice
One file mixing entity types	Split into one JSON per entity
Skipping datasource validate	Run `datasource validate` after each JSON edit

Limits

This page covers manifest shape — not vendor API quirks. OpenAPI operation IDs, pagination, and CIP transforms may need CIP execution. Foreign keys and protection are separate govern steps. After first green datasource validate, keep running it after every JSON edit — it is faster than full system validate while iterating on fieldMappings or sync. Upload only when both system and business entity validators pass without warnings you cannot explain. Treat displayName changes as operator-facing — they do not replace stable key or externalId semantics used by sync and search.

Before first upload, confirm entityType is recordStorage, root resourceType appears in resource-type list, and systemKey matches the system file — these three checks prevent most probe-upload failures.

Documentation Index