By name: ui5-best-practices-integration-cards
description: MUST be loaded before any UI Integration Cards (also called UI5 Integration Cards) task — creating, modifying, validating, previewing, or reviewing a card, its manifest.json, its Configuration Editor (dt/Configuration.js), or any analytical chart configuration. Provides the official guidelines, validation rules, supported chart types, and Configuration Editor patterns.
Best practices for UI Integration Cards development
Rules an agent must follow when creating, modifying, validating, or previewing a UI Integration Card. Adherence is critical for working cards.
When to load each reference
| Trigger | Load |
|---|---|
| Working on or planning an Analytical card | references/analytical_chart_types.md |
dt/Configuration.js exists, is being created, or is being modified |
references/configuration_editor_example.md |
If the trigger applies, load before producing any output. Do not work from memory.
1. Core rules
| Rule | Detail |
|---|---|
| Prefer declarative cards | Types: List, Table, Calendar, Timeline, Object, Analytical. Create an Extension only in exceptional cases. |
Use create_integration_card MCP tool |
When creating a new declarative card. |
| Parameter binding syntax | {parameters>/parameterKey/value} — single braces, > separator, value suffix. |
| Destination binding syntax | {{destinations.destinationName}} — double braces, dot. Configure under sap.card/configuration/destinations/. Reference by name; never replace with raw URL. |
| Use destinations for service URLs | Wrap every external service URL in a destination under sap.card/configuration/destinations/ and reference it as {{destinations.name}}. |
| i18n binding | Bind every non-data, user-visible string to the i18n model. |
| Links | Use the actions property; never inline <a> or hand-rolled URL handlers. |
| Validate before declaring done | See 3. Validation. |
| Show preview when requested | See 4. Preview. |
| Don't modify provided data | Use it as supplied. |
| JSON responses only | The endpoint behind sap.card/data/request must return JSON. For OData services, append $format=json to the request URL or parameters. |
2. Data placement
sap.card/data/ is the only correct top-level location for the data request.
| Path | Purpose |
|---|---|
sap.card/data/path |
Primary data path |
sap.card/content/data/path |
Content-specific path; overrides the primary path if set |
sap.card/header/data/path |
Header-specific path; overrides the primary path if set |
Forbidden: putting the request itself under sap.card/content/data/ or sap.card/header/data/.
Symptom — "No data to display": typically caused by a content/data block that overrides the primary data path. Verify 2. Data placement before debugging anything else.
3. Validation
| Rule | Detail |
|---|---|
| Valid JSON | manifest.json must parse. |
sap.app/type |
Must be "card". |
| Schema validation | Use run_manifest_validation MCP tool. |
| No deprecated properties | In manifest.json or elsewhere. |
| Not a UI5 project | Except for Component-type cards. |
4. Preview
If asked to preview, first check the card folder for an existing preview entry point — package.json start script, README.md, or an existing HTML file. Reuse it if present. Otherwise create an HTML page with a <ui-integration-card> element pointing at the manifest, and serve via an http server.
5. Configuration Editor
The editor lets the Administrator, Page/Content Administrator, and Translator personas customize a card without editing manifest.json directly.
Two pieces:
dt/Configuration.js— exports a function that returnsnew Designtime({ form: {...} }).manifest.json— references the file atsap.card/configuration/editor.
Design as the Administrator persona.
| Rule | Detail |
|---|---|
| Mirror the manifest | Editor reflects the current structure and parameters of manifest.json exactly. manifestpath can target any existing path — a configuration/parameters/*/value for parameterized fields, or a direct path like /sap.card/header/icon/shape for static manifest properties. |
| All existing fields editable | Title, subtitle, header icon, parameters — make them configurable. |
| Ask the user | Before deciding which fields to expose, ask: "Make all manifest fields editable? Anything else to add?" |
| No invented fields | Never add an editor field that does not exist in manifest.json. |
| Keep in sync | Add to or remove from the editor when adding to or removing from manifest.json. |
Load references/configuration_editor_example.md for the canonical paired example.
6. Analytical cards
Load references/analytical_chart_types.md for the full chart-type catalog (UIDs and per-type examples).
| Rule | Detail |
|---|---|
Set chartType |
sap.card/content/chartType is required. |
| Match feeds to chart type | measures, dimensions, and feeds must match the UIDs the chart type expects. The reference file lists them per chart. |
| Each feed needs three keys | type (Dimension|Measure), uid, values. |
chartProperties |
Use it for labels, colors, legend, etc. Do not invent keys. Omit entirely if defaults are fine. |
Minimal feeds example (donut/pie):
"feeds": [
{ "type": "Dimension", "uid": "color", "values": ["Store Name"] },
{ "type": "Measure", "uid": "size", "values": ["Revenue"] }
]