Schema Lint
Stable diagnostic codes emitted by omnigraph schema plan.
omnigraph schema plan emits code-tagged diagnostics for every change it
rejects. Codes have the form OG-XXX-NNN and identify the rule (not the
human-readable message), so CI suppressions and severity overrides can pin
to stable identifiers.
[OG-DS-104] removing property 'Person.age' is not supportedThe catalog is small in v0. Five rules across two families today. The chassis reserves prefixes for the remaining families (constraint deletion, backward-incompat, naming, vector, etc.); those will fill in over time without renumbering existing codes.
Families
| Prefix | Family | Status |
|---|---|---|
| DS | Destructive (data-loss) | shipped |
| MF | Maybe-fail / data-dependent | shipped |
| CD | Constraint deletion (relaxation warning) | reserved |
| BC | Backward-incompatible (rename) | implicit in @rename_from; will be codified |
| NM | Naming conventions | reserved |
| OW | Ownership (per-resource Cedar) | reserved |
| NL | Non-linear (branch-merge divergence) | reserved |
| VE | Vector / embedding | reserved |
| ED | Edge / graph topology | reserved |
| LK | Lock duration / cost | reserved |
Catalog (v0)
| Code | Family | Tier | Default severity | Meaning |
|---|---|---|---|---|
OG-DS-101 | Destructive | destructive | error | drop graph type with rows (reserved; not yet emitted) |
OG-DS-102 | Destructive | destructive | error | drop node type with rows |
OG-DS-103 | Destructive | destructive | error | drop edge type with rows |
OG-DS-104 | Destructive | destructive | error | drop property with rows |
OG-DS-105 | Destructive | destructive | error | drop populated vector column (reserved) |
OG-MF-103 | Maybe-fail | validated | error | add required property without @default to populated type |
OG-MF-104 | Maybe-fail | validated | error | tighten nullable to non-nullable (reserved) |
OG-MF-106 | Maybe-fail | destructive | error | narrowing scalar type |
destructive rules forbid actions that throw away data. validated
maybe-fail rules forbid actions whose success depends on the data already
in the graph, so they need an explicit allowance or a migration script.
Workflow
- Author your candidate schema in a new
.pgfile. - Run
omnigraph schema plan ./graph.omni --schema ./next.pgto preview. - If diagnostics fire, treat them as a decision point:
- Adjust the schema to keep history (the safest path).
- Or, when the data loss is intentional, rerun
schema applywith--allow-data-lossto promote soft drops to hard drops.
omnigraph schema applyruns the migration. It takes a per-branch schema-apply lock so the migration sees a stable snapshot.
Suppression and severity (planned)
Two pieces of the chassis are designed but not shipped yet:
- Severity configuration in
omnigraph.yaml(lint: { OG-DS-103: error }). - In-schema suppression via
@allow(OG-XXX-NNN, "rationale")annotations.
Until those land, treat every code in the catalog as error and adjust the
schema (or pass --allow-data-loss deliberately) rather than suppressing.