---
title: UIPluginV2 — Validation Rules
aliases: [uiplugin, uiplugin-v2, uipluginv2, ui plugins]
sources: [rcg-mobile-dev-agent/raw/006-contract-types-matrix.md, rcg-mobile-dev-agent/wiki/contracts/uiplugin-v2.md]
last_updated: 2026-04-26
status: seed
---

# UIPluginV2 — Validation Rules

UIPluginV2 is how authors ship bespoke UI components into the modeler. A plugin bundles HTML, CSS, JavaScript, labels, and an explicit `Interface` contract that UIDescriptions bind to. The legacy `UIPlugin` (v1) is deprecated — only v2 is fully validated.

## What this contract represents

A `.uipluginv2.xml` file wraps a self-contained web component: its `Interface` lists the properties and events exposed to the host UIDescription, `Libraries` declares external JavaScript it depends on (which must themselves be `ExternalFile` contracts), and `UIComponentHTML/CSS/JS` carry the component source.

## File shape

-   Extension: `.uipluginv2.xml`
-   Root element: `<UIPluginV2>`
-   Required child sequence: `Interface` → `Labels?` → `Libraries` → `UIComponentHTML` → `UIComponentCSS` → `UIComponentJS`.

## Validation rules

### Cross-cutting (every contract)

-   Contract names must be unique workspace-wide.
-   Files must be readable, well-formed XML.

### Must

-   Root element is `<UIPluginV2>`.
-   File name ends with `.uipluginv2.xml`. Custom plugins start with the customizing indicator in both the file name and the root `@name`.
-   The child element sequence must be `Interface` → optional `Labels` → `Libraries` → `UIComponentHTML` → `UIComponentCSS` → `UIComponentJS`, in that order.
-   Every `<Libraries><Library @name>` must resolve to an `ExternalFile` contract that actually exists.
-   In UIComponentJS, any call to `PluginManager.throwEvent("X")` must reference an event declared in `Interface`. Un-declared event names are rejected.
-   `PluginManager.locale.labels.X` must resolve to a declared `Label`; `PluginManager.helpers.X` must resolve to a declared helper (plus the allowlist `isDefined`, `createDateToday`, `createDateNow`); `PluginManager.deviceInfo.X` must resolve to a supported entity (allowlist `isApple`, `isWindows`, `isAndroid`, `isPhone`).

### Must not

-   Two `Interface` properties, two list properties, two events, two labels, or two `UIComponent @name` values cannot share the same name / id within one plugin.

### Coerced (silently rewritten)

-   A plugin flagged `MODIFIED_CORE` is warned — the recommended path is to copy the core plugin into a custom plugin instead of editing the core copy.
-   `xmlns="*.xsd"` on the root is stripped.

## Reference

-   Internal schema reference: `rcg-mobile-dev-agent/wiki/contracts/uiplugin-v2.md`.
-   Cross-repo raw source: `rcg-mobile-dev-agent/raw/006-contract-types-matrix.md`.

## See also

-   [[user-interface]] — UIDescription binds to UIPluginV2 instances.
-   [[external-files]] — ExternalFile contracts supply the JavaScript libraries a plugin depends on.