Version: v1alpha1 (draft)
Status: Draft — not yet normative
Date: August 2026
This document uses RFC 2119 keywords: MUST, MUST NOT, SHOULD, MAY.
| Term | Definition |
|------|------------|
| Manifest | A YAML or JSON document conforming to this spec |
| Application | The root kind: Application manifest describing a complete UI |
kind: Application
| Component | A named, reusable UI block with a type and props |
type
props
| Template | A layout definition assigning components to slots or zones |
| Slot | A named region within a layout (e.g. header, main) |
header
main
| Zone | An ordered list of widgets in a slot (WordPress-style) |
| Route | A URL pattern mapping to a template |
| Catalog | Published JSON Schema defining allowed component types |
| Compiler | Tool that validates and emits runtime JSON manifests |
| Renderer | Runtime that consumes compiled manifests and renders UI |
---
Every ADP manifest MUST include:
schemaVersion
apiVersion
adp.io/v1alpha1
adp.io/v1
metadata.version
deprecated: true
x-sunset
Manifests MAY be authored as YAML (.application.yaml) or JSON (.application.json). Semantics MUST be identical. Runtimes MUST NOT consume YAML directly; compilers MUST normalise to JSON before validation.
.application.yaml
.application.json
An Application spec MUST contain at minimum:
Application
| Field | Required | Description |
|-------|----------|-------------|
| site.title | YES | Application display name |
site.title
| templates | YES | At least one template |
templates
| routes | YES | At least one route |
routes
All other fields are OPTIONAL.
Theme MAY use preset shorthand or reference a DTCG token file:
ADP separates top tab bar from sidebar source:
navigation.tabs
content.docs.nav.mode: auto
content.docs.nav.mode: manual
content.docs.nav.mode
Rules:
layout
{ ref: id }
{ type: ComponentType }
null
FlexibleLayout
slots
zones
match
template
spec.templates
route-manifest.json
Implementations MUST publish a component-catalog.schema.json (meta-schema) and a catalog instance such as catalogs/default.catalog.json:
component-catalog.schema.json
catalogs/default.catalog.json
Custom component types MUST be registered via plugin schema layers. Unknown types MUST cause validation failure in strict mode.
A conforming compiler MUST:
1. Parse YAML or JSON manifest
2. Normalise to JSON
3. Validate against application.schema.json (JSON Schema 2020-12)
application.schema.json
4. Validate cross-reference rules (see validation-rules.md)
5. Validate component props against catalog schema
6. Emit runtime manifests:
ui-config.json
docs-nav.json
Manifests MAY include external files using Backstage-style placeholders:
../../
$yaml:
$json:
$text:
Vendor extensions MUST use the x-adp- prefix:
x-adp-
Implementations MUST preserve unknown x-adp-* fields. Non-prefixed unknown fields MUST be rejected in strict mode.
x-adp-*
An implementation is ADP-conformant if and only if it:
1. Accepts manifests with apiVersion: adp.io/v1alpha1 and kind: Application
apiVersion: adp.io/v1alpha1
2. Validates all MUST-level requirements in this spec and validation-rules.md
3. Rejects manifests with unknown fields in strict mode
4. Emits runtime JSON manifests from valid Application specs
5. Resolves routes to templates at render time