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

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 sections: datasource.metadata, datasource.identity.

Builder MCP


Manifest sections	`datasource.metadata`, `datasource.identity`
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

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 }
    }
  }
}

Project vendor fields via Configure business vocabulary — schema and mappings must agree.
Validate entity file:

aifabrix datasource validate <datasourceKey>

Validate

System gate: aifabrix validate <systemKey>. Missing externalId fails schema validation before upload.

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