Configure metadata and identity

Define metadataSchema, primaryKey, and labelKey so each Business Entity has stable join identity and operator-readable labels.

Prerequisites

Entity basics chosen — entityType, resourceType from Entity basics, types, and resource
Vendor sample payload or OpenAPI schema for property names
Configure business vocabulary planned or in progress

Where it lives

Layer	Location
Schema	`metadataSchema.properties` — indexed fields for search/ABAC
Identity	`primaryKey[]`, required `externalId` property
Display	`labelKey[]` — human title fields
UI	Business Entity Overview / vocabulary tabs

Manifest keys: metadataSchema, primaryKey, labelKey.

Builder MCP


Manifest keys	`metadataSchema`, `primaryKey`, `labelKey`
Help topics	`section`, `goldenExample`, `dependencyGraph`
Repair hooks	`fieldMappings`

Changing identity bands triggers downstream exposure and RBAC — read dependencyGraph before patch. Example fixture: help topic goldenExample (CRM company pattern).

How to set

Repair field mappings first when importing from a fixture:

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

Require indexed externalId on record and document storage entities:

{
  "key": "example-customers",
  "entityType": "recordStorage",
  "resourceType": "customer",
  "primaryKey": ["externalId"],
  "labelKey": ["name"],
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": { "type": "string", "index": true },
      "name": { "type": "string", "index": true, "filter": true }
    }
  }
}

Project vendor fields via Configure business vocabulary — schema and mappings must agree on every indexed property.
Set labelKey to operator-readable fields already mapped in fieldMappings.attributes.
Validate entity file:

aifabrix datasource validate <datasourceKey>
aifabrix validate <systemKey>

Defaults and examples

Element	Purpose	Example
`externalId`	Cross-entity join key	Indexed string in metadataSchema
`primaryKey`	Storage identity	`["externalId"]` for most record types
`labelKey`	UI and list display	`["name"]` or `["title"]`
`index: true`	Search and ABAC	On decision-relevant fields only

Example metadata band with filter flags:

{
  "metadataSchema": {
    "type": "object",
    "properties": {
      "externalId": { "type": "string", "index": true },
      "name": { "type": "string", "index": true, "filter": true },
      "ownerId": { "type": "string", "index": true, "filter": true },
      "country": { "type": "string", "index": true }
    }
  },
  "primaryKey": ["externalId"],
  "labelKey": ["name"]
}

Illustrative identity goals:

vendor id → normalized externalId (always indexed)
display name → labelKey source (searchable when agents need it)
governance dimensions → indexed fields referenced in top-level dimensions

Validate

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

System gate: missing externalId fails schema validation before upload. Empty search during integration tests often traces to incomplete metadataSchema.properties — not credential errors. Re-run datasource validate after every identity band edit; the compiler cross-checks primaryKey, labelKey, and indexed externalId on each pass.

Common mistakes

Mistake	Fix
Composite PK as cross-entity join key	Use `externalId` for joins
Schema properties without field mappings	Repair `fieldMappings`
`labelKey` pointing at unmapped field	Map attribute first
All vendor fields indexed	Index decision-relevant fields only

Limits

Identity bands are vendor-specific in mapping expressions — this page shows required shape, not every JSONPath dialect. Document storage entities may add file-specific properties while keeping externalId as the join key. After identity edits, re-run repair --expose when exposure schema lists derived from metadata change. Keep labelKey fields stable across releases — operator bookmarks and audit trails reference display labels tied to identity configuration.