---
title: ExternalFile — Validation Rules
aliases: [external-file, externalfile, external files, external libraries]
sources: [rcg-mobile-dev-agent/raw/006-contract-types-matrix.md, rcg-mobile-dev-agent/wiki/contracts/external-file.md]
last_updated: 2026-04-26
status: seed
---

# ExternalFile — Validation Rules

ExternalFile is the narrow escape hatch for shipping third-party JavaScript libraries and print fonts into the modeler. The allow-list is deliberately tight: essentially D3.js and font bundles named `PrintFont_*`. Unlike every other validator, `externalfileValidator.js` reaches into the binary (zip) payload to check its contents.

## What this contract represents

An `.externalfile.xml` file wraps a library bundle — typically `d3.js` plus its `LICENSE.txt`, or a thermal-printer font as a `PrintFont_*` archive. ExternalFile contracts are declared by authors and referenced by [[ui-plugins|UIPluginV2]] via `<Libraries><Library>`.

## File shape

-   Extension: `.externalfile.xml`
-   Root element: `<ExternalFile>`
-   `allowedLibraries` matches regex `[CcDd]3[Jj][Ss]|(My)?PrintFont_\w+`.

## Validation rules

### Cross-cutting (every contract)

-   Contract names must be unique workspace-wide — the name-uniqueness check runs both as the general cross-cutting rule **and** as ExternalFile's own self-scanning duplicate check.
-   Files must be readable, well-formed XML.

### Must

-   Root element is `<ExternalFile>`; `allowedLibraries` must match the D3.js-family or PrintFont\_\* pattern — arbitrary library names are rejected.
-   File name ends with `.externalfile.xml`. Custom ExternalFiles start with the customizing indicator in both the file name and the root `@name`.
-   A `PrintFont_<name>` bundle must contain exactly `PrintFont.js` and `LICENSE.txt` — no more, no less.
-   `<ExternalFile @name>` is globally unique across the workspace — two ExternalFile contracts cannot share the same name.

### Must not

-   The zip payload must not contain multiple `LICENSE.txt` files.
-   The zip payload must not contain multiple versions of the same file (for example both minified and non-minified of the same module).
-   The payload must not fail zip-parsing — malformed archives are rejected.

### Coerced (silently rewritten)

-   Mac `__MACOSX` resource forks in the zip are warned (the framework tolerates them) — clean archives before shipping.
-   A missing `LICENSE.txt` is warned — include the license from the library vendor.
-   `xmlns="*.xsd"` on the root is stripped.

## Reference

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

## See also

-   [[ui-plugins]] — UIPluginV2 lists ExternalFile libraries in its `<Libraries>` block.
-   [[print-layouts]] — PrintLayouts can reference `PrintFont_*` ExternalFiles for thermal printing.