uc-apx validate

uc-apx validate runs two independent validators against your exported APEX application. They answer different questions and have different requirements.

Two Validators

Local validator (always runs)

A fast, dependency-free structural pass built into uc-apx. Checks:

Issue kind	Severity	What it flags
`duplicateID`	error	Two constructs on the same page share an ID
`brokenReference`	error	An `@name` reference doesn’t resolve to any parsed construct
`missingName`	warning	A construct kind that requires `name:` is missing it
`emptyPage`	warning	A page has no child components
`invalidSlot`	warning	A region uses a `layout.slot` that isn’t valid for its page’s template

Limitations: The local checker can’t see invalid property names, wrong value types, missing required children, or invalid component nesting. It only knows the shape of the parse tree, not the full MMD schema.

Official validator (`--official`)

Wraps Oracle’s apex validate command from SQLcl 26.1.2+. Validates against the full APEXlang MMD schema — the same validation APEX Builder runs before saving. This is the source of truth.

Requirements:

SQLcl 26.1.2+ must be installed and sql must be on $PATH
Or pass --sql-bin /path/to/sql to point at the binary explicitly

Usage

uc-apx validate [flags]

Flags

Flag	Type	Default	Description
`--official`			Also run SQLcl `apex validate` for full MMD-schema checks (requires SQLcl 26.1.2+)
`--sql-bin`	string	`sql`	Path to the SQLcl binary used by `--official`
`--strict-system-refs`			Report `@/...` system-template refs (e.g. `@/standard`, `@/drawer`) as `brokenReference`. Off by default — they resolve against APEX’s built-in template library, not the parsed app
`--compact`			Suppress full errors/warnings arrays; emit only the summary with per-kind counts. Useful for agents when high-volume issues would flood the context

Global Flags

Flag	Type	Default	Description
`--app-dir`	string	`.`	Path to the APEX application directory
`--json`			Output in JSON format instead of TOON

Example: Clean App

Running against examples/brookstrut (no issues):

uc-apx --app-dir examples/brookstrut validate

valid: true
errors[0]:
warnings[0]:
summary:
  errorCount: 0
  warningCount: 0
  errorsByKind:
  warningsByKind:

Exit code: 0

Example: App with Violations

Running against examples/validation-errors — a deliberately broken app with two errors and three warnings:

uc-apx --app-dir examples/validation-errors validate

valid: false
errors[2]{severity,kind,message,id,name,file,line}:
  error,duplicateID,"duplicate region 'content' in page '1' (first seen in pages/p00001-home.apx:7)",content,Welcome Duplicate,pages/p00001-home.apx,16
  error,brokenReference,reference 'non-existent-authz' in property 'security.authorizationScheme' does not resolve to any component,broken-ref,Restricted Section,pages/p00001-home.apx,25
warnings[3]{severity,kind,message,id,name,file,line}:
  warning,missingName,region 'sidebar' has no name property,sidebar,"",pages/p00002-reports.apx,7
  warning,emptyPage,page 'Administration' (10) has no child components,"10",Administration,pages/p00010-admin.apx,1
  warning,invalidSlot,"region 'sidebar' on page 2 uses slot 'leftColumn' which is not valid for pageTemplate /standard (valid: body, breadcrumbBar, ...)",sidebar,sidebar,pages/p00002-reports.apx,7
summary:
  errorCount: 2
  warningCount: 3
  errorsByKind:
    brokenReference: 1
    duplicateID: 1
  warningsByKind:
    emptyPage: 1
    invalidSlot: 1
    missingName: 1

Exit code: 1 (non-zero when errorCount > 0)

JSON output

{
  "valid": false,
  "errors": [
    {
      "severity": "error",
      "kind": "duplicateID",
      "message": "duplicate region 'content' in page '1' (first seen in pages/p00001-home.apx:7)",
      "id": "content",
      "name": "Welcome Duplicate",
      "file": "pages/p00001-home.apx",
      "line": 16
    },
    {
      "severity": "error",
      "kind": "brokenReference",
      "message": "reference 'non-existent-authz' in property 'security.authorizationScheme' does not resolve to any component",
      "id": "broken-ref",
      "name": "Restricted Section",
      "file": "pages/p00001-home.apx",
      "line": 25
    }
  ],
  "warnings": [
    {
      "severity": "warning",
      "kind": "missingName",
      "message": "region 'sidebar' has no name property",
      "id": "sidebar",
      "file": "pages/p00002-reports.apx",
      "line": 7
    },
    {
      "severity": "warning",
      "kind": "emptyPage",
      "message": "page 'Administration' (10) has no child components",
      "id": "10",
      "name": "Administration",
      "file": "pages/p00010-admin.apx",
      "line": 1
    },
    {
      "severity": "warning",
      "kind": "invalidSlot",
      "message": "region 'sidebar' on page 2 uses slot 'leftColumn' which is not valid for pageTemplate /standard (valid: body, breadcrumbBar, fullWidthContent, footer, ...)",
      "id": "sidebar",
      "name": "sidebar",
      "file": "pages/p00002-reports.apx",
      "line": 7
    }
  ],
  "summary": {
    "errorCount": 2,
    "warningCount": 3,
    "errorsByKind": { "brokenReference": 1, "duplicateID": 1 },
    "warningsByKind": { "emptyPage": 1, "invalidSlot": 1, "missingName": 1 }
  }
}

Compact output (for agents)

When there are many issues, use --compact to get only the summary counts without the full list:

uc-apx --app-dir examples/validation-errors validate --compact

valid: false
compact: true
errors[0]:
warnings[0]:
summary:
  errorCount: 2
  warningCount: 3
  errorsByKind:
    brokenReference: 1
    duplicateID: 1
  warningsByKind:
    emptyPage: 1
    invalidSlot: 1
    missingName: 1

Strict system-ref mode

By default, @/standard, @/drawer, and other built-in template refs are not checked (they resolve against APEX’s internal theme library, not your app). Pass --strict-system-refs to report them as brokenReference errors:

uc-apx --app-dir examples/validation-errors validate --strict-system-refs

This raises the error count from 2 → 5 (the three @/standard page-template refs on each page become errors).

Official Validator Output Shape

When --official is passed, the JSON output gains an official block:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "summary": { "errorCount": 0, "warningCount": 0, ... },
  "official": {
    "success": true,
    "exitCode": 0,
    "stdout": "Validation successful.\n",
    "stderr": ""
  }
}

On failure, official.success is false and official.stdout / official.stderr contain the SQLcl output. Always check official.success, not just the top-level valid field, because the official check runs independently of the local check.

Gate your pipeline on official.success == true for the strongest guarantee:

result=$(uc-apx --app-dir . validate --official --json)
if [ "$(echo $result | jq '.official.success')" != "true" ]; then
  echo "Validation failed"
  echo $result | jq '.official.stdout'
  exit 1
fi