USM

Appearance

usm/schema-v1 ​

The v1 JSON Schema — the validation contract for all .usm files, defining system, service, and feature file types with required fields and constraints.

Intent ​

The v1.json schema is the single source of truth for what constitutes a valid .usm file. It defines three file types (system, service, feature), their required fields, and the structure of flows, contracts, tests, and other complex types. All validation (CLI and MCP) runs against this schema.

Flows ​

Schema validation flow (schema-validate) ​

A .usm file is validated against the v1 schema

  1. parse → .usm YAML content into JS object
  2. observe → $type discriminator selects systemFile, serviceFile, or featureFile
  3. observe → Ajv validates against selected definition
  4. submit → validation result with errors

Flow Diagrams ​

mermaid
sequenceDiagram
    participant User
    participant Browser
    participant Server

    User->>Browser: parse .usm YAML content into JS object
    Browser-->>User: shows $type discriminator selects systemFile, serviceFile, or featureFile
    Browser-->>User: shows Ajv validates against selected definition
    User->>Browser: submit validation result with errors

Contracts ​

schema-three-types ​

The schema must support exactly three file types: system, service, feature

Acceptance criteria:

  • [ ] oneOf selects systemFile, serviceFile, or featureFile
  • [ ] Common fields: $schema, $id, $type, $version, summary
  • [ ] $id pattern: ^[a-z0-9][a-z0-9-]/[a-z0-9][a-z0-9-]$
  • [ ] Flow steps require id and action
  • [ ] Contracts require id and description
  • [ ] Tests require id and expect

schema-additional-properties-false ​

Each file type must set additionalProperties: false to prevent undocumented fields

Acceptance criteria:

  • [ ] systemFile.additionalProperties is false
  • [ ] serviceFile.additionalProperties is false
  • [ ] featureFile.additionalProperties is false

Tests ​

schema-rejects-unknown-type ​

Given:

  • usm_with_type_widget: true

Then:

  • assertion: validation fails with enum error for $type

schema-rejects-extra-fields ​

Given:

  • feature_with_extra_top_level_field: true

Then:

  • assertion: validation fails with additionalProperties error

Implementation ​

  • Primary: schema/v1.json
  • Test code status: none

See Also ​

  • usm/cli-validate