## Problem Canvas does not have a published, machine-readable description of the authored Code Component `component.yml` envelope. Metadata rules are distributed across local CLI validation, JSON Schema prop definitions, Drupal config schema, and PHP entity constraints, causing incomplete feedback and duplicated logic. The CLI also cannot determine authoritatively whether metadata will be accepted by the target Drupal site. The CLI and site may run different Canvas versions, and the site may have different extensions, field types, widgets, and alter hooks. Errors discovered only during push can occur after other components have already been updated. Developers need useful local structural feedback while retaining authoritative, non-mutating validation against the target site. ## Proposal ### Validation overview ```text component.yml ├─ JSON Schema → envelope, prop schemas, and default examples ├─ ESLint → portable authoring and project rules └─ Drupal target → authoritative acceptance ``` - `component-metadata.schema.json` is a hand-authored draft-07 schema for the stable authored document envelope. - Definitions under `props.properties` are already JSON Schema and are validated directly rather than generated from Drupal config schema. - The required ESLint configuration owns portable authoring rules and project conventions. - Drupal config schema determines which JSON Schema vocabulary Canvas can store. - The target Drupal site is authoritative for Canvas support and site-dependent behavior. - Local validation is best effort and clearly reports when target acceptance was not validated. - Same-version `pull → validate → push` must work. - `scaffold` removal remains outside scope. ### Authored format Required: - `name` - `machineName` Optional and normalized after raw validation: - `status` - `required` - `props` - `slots` - `dataDependencies.entityFields` Additional rules: - `type` is supplied during push, not authored. - `drupalSettings` and `urls` are derived from source code. - Projected `x-allowed-*` keys are rejected and omitted by `pull`. - Unknown keys are rejected at fully defined metadata levels. - `pull` continues emitting optional fields explicitly. - Files do not contain `$schema` or a schema version. ### Local schema and prop validation - Maintain the repository-root `component-metadata.schema.json` directly; do not translate `config/schema/canvas.json_schema.yml`. - Use the envelope schema to validate raw YAML before defaults are applied and map failures to YAML locations where practical. - Check each prop definition against the draft-07 meta-schema. The meta-schema validates JSON Schema usage, while the envelope adds portable Canvas requirements such as a nonempty prop `title` and an explicit `type`. - Validate the first prop example, which Canvas uses as the default, against its containing prop schema when that schema is locally resolvable. - Statically import the Canvas module-root `schema.json` into the CLI bundle. At runtime, register each entry under `$defs` at `json-schema-definitions://canvas.module/<name>` so Canvas-owned prop references resolve offline. - Leave Canvas-specific policy such as array cardinality, content entity reference relationships, and image URL restrictions to Drupal, along with references provided by target extensions, target-version differences, field/widget availability, entity-model checks, and alter hooks. ### Rolling publication and CLI bundling Publication and bundling use the same repository-root `component-metadata.schema.json`, not separate maintained copies: - Publish the file as the current rolling authored-envelope schema at: `https://git.drupalcode.org/project/canvas/-/raw/1.x/component-metadata.schema.json` - Let editors and other external tools use the published URL. - Statically import the same file into the CLI package so each CLI build contains a reproducible offline snapshot. - Do not fetch either `component-metadata.schema.json` or the module-root `schema.json` at CLI runtime. - Do not define independently versioned metadata contracts. - Files found in release tags are historical source snapshots, not supported compatibility contracts. - A released CLI snapshot may differ from the later rolling `1.x` file; neither promises target acceptance. - Do not declare `$schema` or a contract version in `component.yml`. A component may target multiple sites running different Canvas versions, and each site accepts its installed contract. ### Shared Ajv package and dialect - Add a private workspace package containing the strict draft-07 Ajv factory. - Include standard format validators and Canvas-supported string formats such as `idn-email`, `idn-hostname`, `iri`, `iri-reference`, and `duration`. The additional validators come from `ajv-formats-draft2019`, but do not change the schema dialect from draft-07. - Use the shared factory in the UI and CLI. - Bundle the private package into the published CLI. - Migrate existing Canvas-owned draft 2020-12 schemas to draft-07 atomically. - Update CI path rules so package, UI, CLI, schema, and backend tests run when relevant inputs change. ### Authoritative target validation Expose one authenticated, non-mutating Drupal operation that: - accepts a complete normalized Code Component API payload; - constructs an in-memory create or update candidate; - runs the same entity and metadata constraint chain used by create and update; - returns `204` when valid or the existing structured constraint violations when invalid; and - never saves or mutates stored configuration. `canvas validate`: 1. Validates raw YAML against the bundled envelope schema. 2. Checks prop definitions and locally resolvable first examples directly as JSON Schema. 3. Runs ESLint portable authoring and project rules and aggregates diagnostics. 4. Normalizes valid metadata and constructs the complete payload. 5. Submits each payload to target validation when authenticated access is available. 6. Warns when only local checks were completed and target acceptance was not validated. `canvas push` passes its existing API service through the same target-validation path and preflights every complete component payload before the first create, update, or delete. Older sites without the operation produce a warning and retain current per-component save-time validation, so partial push remains possible. `canvas build` remains offline. Discovery, Workbench, and headless consumers retain defensive parsing without becoming target-aware. ### ESLint Use the required ESLint configuration for portable authoring rules and project conventions, including: - required names identifying defined props; - default examples for required props; - nonempty string examples; - prop names; - imports and exports; and - directory names and hierarchy. Canvas-specific metadata acceptance remains Drupal-owned, without duplicate blocking ESLint diagnostics. ### Testing - Structural fixtures verify the hand-authored envelope schema in TypeScript and PHP JSON Schema validators. - Prop fixtures verify direct example validation and Canvas-owned `$ref` resolution. - ESLint rule tests verify required-prop relationships and nonempty string examples. - Target-only fixtures verify that Canvas implementation policy is not duplicated in local schema validation or ESLint. - Functional tests verify Canvas-specific and Drupal-authoritative constraints. - Functional tests cover authentication, authorization, valid and invalid payloads, structured violations, and no-save behavior. - CLI tests cover raw validation, normalization, YAML diagnostics, pull round trips, target-unavailable warnings, and all-component push preflight. --- *The proposal was generated and refined with careful and extensive planning using an AI coding agent.*