Eco Manager Wiki

Appearance

09 — Validation and Safety ​

The Admin Console must make powerful changes safe.

Runtime metadata controls API behavior, frontend forms, validation, filtering, permissions, and user workflows. A bad metadata change can break production behavior.

Validation Types ​

Shape Validation ​

Zod validates input structure.

Examples:

  • key is required,
  • name is required,
  • value type is valid,
  • UUIDs are valid.

Referential Validation ​

The backend validates references.

Examples:

  • property group exists,
  • entity type exists,
  • relationship source and target types exist,
  • template references valid property groups.

Semantic Validation ​

The backend validates meaning.

Examples:

  • relationship cardinality is coherent,
  • hierarchy rules do not conflict,
  • root types are allowed,
  • sensitive property values use Vault-backed handling.

Compatibility Validation ​

The backend validates impact on existing runtime data.

Examples:

  • changing property type would invalidate existing values,
  • deleting entity type would orphan existing entities,
  • restricting parent types would make existing hierarchy invalid,
  • changing tag group to single-select would conflict with existing multi-tag assignments.

Draft Validation Output ​

Validation results should be structured.

text
severity: info | warning | error
code: string
message: string
path: optional metadata path
metadata: json

Errors block publishing.

Warnings require acknowledgement.

Info messages are advisory.

Required Validation Rules ​

Key Rules ​

  • Keys must be lowercase snake_case.
  • Keys must be unique in a model version.
  • Published keys should be treated as stable identifiers.
  • Renaming a key should be treated as a migration, not a simple edit.

Hierarchy Rules ​

  • Entity type parent/child rules must not conflict.
  • Root entity types must be explicitly allowed.
  • Types marked is_hierarchy_allowed=false cannot be placed in the containment tree.

Relationship Rules ​

  • Relationship definitions must reference valid entity types.
  • Cardinality must be enforceable.
  • Self-reference requires explicit permission.
  • Relationship definitions must not be used for containment.

Property Rules ​

  • Value type must be valid.
  • Validation JSON must match value type.
  • Sensitive values must not be stored as ordinary JSON property values.
  • Required property changes require compatibility checks.

Destructive Change Policy ​

Destructive changes should be blocked unless explicitly approved.

Examples:

  • delete entity type with runtime entities,
  • delete property definition with values,
  • delete relationship definition with relationships,
  • change value type with existing values,
  • reduce relationship cardinality with existing conflicts.

Deprecation Over Deletion ​

Prefer deprecation to deletion.

A deprecated metadata item may be:

  • hidden from new forms,
  • blocked from new assignments,
  • still visible for historical data,
  • migratable later.

Publishing Gate ​

A model may be published only if:

  • validation has run,
  • no errors exist,
  • warnings are acknowledged,
  • destructive changes are approved,
  • compatibility checks pass,
  • user has publish permission,
  • audit event is recorded.

Runtime Safety ​

Runtime APIs must always validate against the current published model.

Never trust frontend metadata alone.

The backend is the source of truth for:

  • permission checks,
  • root scope checks,
  • property validation,
  • hierarchy rules,
  • relationship rules,
  • lifecycle rules.