Configure business vocabulary

Map vendor API fields to business attributes and dimension bindings so Business Entities become Enterprise Knowledge — not raw payloads.

Prerequisites

Datasource JSON from create + fixture copy or manual authoring
Resource type registered in catalog
Business vocabulary agreed (customer, owner, region — not vendor field jargon)

Where it lives

Each datasource file: integration/<systemKey>/<datasourceKey>.json

Band	Location
Identity	Root: `key`, `displayName`, `systemKey`, `entityType`, `resourceType`
Attributes	`fieldMappings.attributes` — vendor → normalized expressions
Dimensions	Top-level `dimensions` + `dimensionBinding` (not under fieldMappings)
Schema	`metadataSchema.properties` — includes indexed `externalId`

Not valid: nesting resourceType under fieldMappings — it is a root field only.

Builder MCP


Manifest section	`datasource.fieldMappings`
UI tab	Business Vocabulary (`?tab=mappings`)
Help topics	`section`, `goldenExample`, `dependencyGraph`
Repair hooks	`fieldMappings`, `expose`

Read dependencyGraph before patch — vocabulary edits affect metadata schema and exposure.

How to set

Copy a fixture or map from vendor OpenAPI — treat import output as draft only.
Set root resourceType — catalog key for this entity (customer, document, …).
Map identifiers — ensure externalId and primaryKey align with normalized fields.
Define fieldMappings.attributes — one entry per business field with source expression.
Mark searchable and display fields — index/filter flags in metadataSchema for decision-relevant data only.
Attach dimensions — top-level dimensions keys reference attribute fields; see Configure business policies.
Declare relationships — foreignKeys[] before protection on linked entities.
Repair and validate:

aifabrix repair <systemKey> --dry-run
aifabrix repair <systemKey> --expose
aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>

Defaults and examples

Element	Purpose	Example
`resourceType` (root)	Business entity for capabilities	`customer`, `contact`, `deal`
`externalId`	Join identity	Indexed string in metadataSchema
attributes	Normalized vendor mapping	`"name": { "source": "$.properties.name" }`
Searchable	Query and AI context	`name`, `industry`, `status`
Dimensions	ABAC boundaries	`customerRegion`, `ownerId`

Example fieldMappings.attributes fragment:

{
  "key": "example-customers",
  "displayName": "Customers",
  "systemKey": "example-crm",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"],
  "fieldMappings": {
    "attributes": {
      "externalId": { "source": "$.id", "type": "string" },
      "name": { "source": "$.properties.name", "type": "string" },
      "country": { "source": "$.properties.country", "type": "string" }
    }
  },
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": { "type": "string", "index": true },
      "name": { "type": "string", "index": true, "filter": true },
      "country": { "type": "string", "index": true }
    }
  }
}

Illustrative mapping goals:

vendor id → normalized externalId (indexed)
name → customer display name (searchable)
country → customerRegion dimension via top-level dimensions

Validate

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

Empty search or certification failures often trace to incomplete fieldMappings — not auth errors. Re-run validate after changing any fieldMappings.attributes entry; the compiler cross-checks metadataSchema.properties and indexed externalId on every pass.

Common mistakes

Mistake	Fix
Vendor field names unchanged	Rename to business attributes
`resourceType` under fieldMappings	Move to root next to `entityType`
All fields searchable	Expose decision-relevant fields only
Dimensions only in RBAC UI	Define top-level `dimensions` on JSON
Skipping repair after edits	`repair --expose` syncs metadataSchema
Ignoring `systemKey` drift	Match parent system file before validate

Limits

Field mapping expressions are vendor-specific — this page shows shape, not every JSONPath dialect. Complex transforms may require CIP steps in CIP execution. Keep displayName aligned with operator vocabulary and verify externalId stays indexed after every attribute change — search and governance tests depend on stable join identity. When adding dimensions, update top-level dimensions and attribute sources together — changing only RBAC YAML without JSON bindings produces false confidence. Run datasource validate after every attribute edit; validate <systemKey> before upload when multiple datasource files changed in the same commit.

Documentation Index