Object Specs Directory

Status: Active
Date: 2025-12-21
Last Updated: 2026-01-25

This directory contains object specifications in YAML format. All v1 specs have been archived to object_specs_archived/ and the system now uses specs from this directory.

Current State

✅ All v2 specs moved from object_specs_v2/ to this directory
✅ File naming: {object_type}.yaml (no _v2 suffix)
✅ System uses specs from object_specs/ directory
✅ Display length constraints added for listable fields

Spec Files

All object spec files are located here:

base_object.yaml - Core object fields
backlog_item.yaml - Backlog item fields
goal.yaml - Goal fields
milestone.yaml - Milestone fields
workstream.yaml - Workstream fields
requirement.yaml - Requirement fields
And many more...

See the directory listing for the complete set of spec files.

High-volume kinds

Kinds designated as high-volume (see ../configs/high_volume_kinds.yaml) retain full specs here but require efficient, compressed storage (stream storage or timeseries). The legacy one-file-per-object (CAS) format is deprecated for them. See docs/architecture/HIGH_VOLUME_STORAGE_DEPRECATION.md.

Each high-volume kind spec includes storage_profile: stream at the top level (after visibility) so the resolved spec does not inherit cas_entity from auditable via base_object; the canonical list and code that enforces stream storage live in ../configs/high_volume_kinds.yaml and pkg/storage/stream_config.go. Examples include metric kinds, mcp_session, zqk_session, and verification_matrix (matrix registry metadata and frequent updates use stream segments + stream_current).

Display Length Constraints

All fields with the listable trait should include a display_length constraint in their validation section. This ensures consistent table formatting across CLI commands.

Example:

job_type:
    traits:
        - listable
    validation:
        required: true
        display_length: 28  # Maximum characters for table display

See ../documentation/display-length-constraints-v1.0.md for complete guidelines.