USM

Appearance

usm/schema-v1 ​

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

Why this exists ​

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

How it works ​

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

Guarantees ​

schema-three-types ​

The schema must support every file type advertised by the UsmFileType union, with the discriminator enum and oneOf in agreement

Acceptance criteria:

  • [ ] oneOf selects systemFile, serviceFile, featureFile, dataFile, or feedbackFile
  • [ ] Every $type in commonFields.enum has a matching oneOf/$defs branch
  • [ ] 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
  • [ ] dataFile.additionalProperties is false

Test specifications ​

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

schema-accepts-data-file ​

Given:

  • usm_with_type_data: true

Then:

  • assertion: validation passes for a minimal $type: data file
  • assertion: validation passes for a fully-populated $type: data file

schema-discriminator-matches-enum ​

Given:

  • iterate_every_discriminator_type: true

Then:

  • assertion: every $type in the discriminator enum validates against its branch

Implementation ​

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

See Also ​

  • usm/cli-validate