@objectstack/spec Metadata Capability Evaluation

Version: @objectstack/spec v3.0.0 | Evaluated: February 12, 2026 | Last Updated: Phase 8
Scope: All 12 spec modules evaluated against HotCRM's 7 business packages + AI package
Validation Engine: Zod 4.3.6
v3.0.0 Breaking Changes: Removed hub, auth, driver, permission modules. New studio module added with defineStudioPlugin() and contributions API.

This document provides a comprehensive gap analysis between the metadata capabilities offered by @objectstack/spec and their actual adoption in HotCRM. It covers all 12 exported modules in v3.0.0 (data, system, kernel, ai, automation, api, ui, contracts, integration, security, studio), categorizes each capability as Used, Partially Used, or Not Used, and proposes an actionable improvement plan.

v3.0.0 Module List (12 modules)

Note on ObjectSchema.create() vs ObjectSchema.parse(): v3.0.0 introduced ObjectSchema.create() as the recommended lightweight API for defining objects. It provides the same type safety with less overhead than parse(). All 94 HotCRM objects use ObjectSchema.create().

Zod 4 Compatibility: @objectstack/spec v3.0.0 uses Zod 4.3.6 as its validation engine. Zod 4 is largely backward-compatible with Zod 3 patterns (z.string(), z.object(), z.enum(), etc.). Nine files across HotCRM import zod directly (see Zod 4 Compatibility section below). All existing patterns are compatible with Zod 4.

Executive Summary

Key Finding: With Phase 8 work, HotCRM has significantly improved its spec adoption from ~13% to ~25%. UI schemas are now fully adopted (PageSchema, ViewSchema, DashboardSchema, FormViewSchema all validated). The studio module is adopted via defineStudioPlugin(). System-level configs (cache, notifications, audit) and API configs (webhooks) are now formally defined. The data layer remains the most heavily used module with expanded field type usage.

Module-by-Module Analysis

1. @objectstack/spec/data — Data Layer

The data module is HotCRM's most heavily used spec module, imported in all 94 object files and 71 hook files.

Field Types: Used vs Available

Progress: Field type usage has increased from 15 to 22 types. All CRM-critical relationship types (masterDetail, summary, lookup) are now in use. Geographic (location, address), media (file, image), and multi-select patterns are adopted.

2. @objectstack/spec/ui — UI Layer

Key Finding: UI schema adoption is now complete for core metadata types. All page layouts, list views, dashboards, and forms validate against their respective schemas using satisfies type checking and .parse() runtime validation.

3. @objectstack/spec/automation — Automation Layer

Key Finding: Workflow definitions are now validated with WorkflowRuleSchema. State machines have been formally adopted for status lifecycle management.

4. @objectstack/spec/ai — AI Layer

Key Finding: MCP integration is well-implemented and validated. Agent definitions now use AgentSchema for formal validation.

5. @objectstack/spec (root) + @objectstack/spec/kernel — Configuration & Plugin System

6. @objectstack/spec/system — System Layer

7. @objectstack/spec/api — API Layer

8. @objectstack/spec/security — Security Layer

9. @objectstack/spec/integration — Integration Layer

10. @objectstack/spec/studio — Studio Module (New in v3.0.0)

11. @objectstack/spec/contracts — Service Contracts

v3.0.0 Note: The hub, auth, driver, and permission modules were removed in v3.0.0. Their functionality has been consolidated into other modules (security absorbed permission, kernel absorbed auth/driver, hub functionality is deprecated).

Gap Analysis Summary

Resolved Gaps (Completed in Phase 7–8)

These gaps from the original evaluation have been addressed:

Remaining High-Impact Gaps

Lower-Priority Gaps (Future Consideration)

Prompt Improvement Recommendations

Based on the gap analysis, the following improvements to the project's AI coding prompts (GitHub Copilot instructions) are recommended:

1. Enforce Schema Validation in Prompts

Current instruction: "All business objects are defined in TypeScript using the ServiceObject interface."

Proposed addition:

- All *.page.ts files MUST import and validate against PageSchema from @objectstack/spec/ui
- All *.view.ts files MUST import and validate against ViewSchema from @objectstack/spec/ui
- All *.workflow.ts files MUST validate against WorkflowRuleSchema from @objectstack/spec/automation
- Plugin definitions MUST use PluginSchema from @objectstack/spec/kernel instead of `any` type
- State machines MUST be defined using StateMachineSchema from @objectstack/spec/automation

2. Expand Field Type Guidance

Current instruction: Generic field types mentioned.

Proposed addition:

- Use Field.master_detail() for parent-child relationships where the child cannot exist without the parent (e.g., invoice_line→invoice). This enforces cascade delete and enables Field.summary() rollups on the parent. Use Field.lookup() for optional associations where records are independent.
- Use Field.summary() for rollup/aggregate fields on parent objects
- Use Field.multiselect() when multiple options can be selected
- Use Field.tags() for free-form tagging
- Use Field.location() and Field.address() for geographic data
- Use Field.file() and Field.image() for attachment fields

3. Add UI Metadata Guidance

Proposed addition to File Suffix Protocol:

- *.page.ts: Record detail layouts using PageSchema from @objectstack/spec/ui
- *.view.ts: List/grid/kanban views using ViewSchema from @objectstack/spec/ui
- *.dashboard.ts: Dashboard layouts using DashboardSchema from @objectstack/spec/ui
- *.report.ts: Report definitions using ReportSchema from @objectstack/spec/ui
- *.form.ts: Form layouts using FormViewSchema from @objectstack/spec/ui

4. Add Security Metadata Guidance

Proposed addition:

- *.permission.ts: Permission sets and field permissions using @objectstack/spec/security
- *.sharing.ts: Sharing rules and territory models using @objectstack/spec/security

5. Add Automation Best Practices

Proposed addition:

- Complex status fields SHOULD have a corresponding state machine definition (*.statemachine.ts)
- Approval flows MUST use ApprovalProcessSchema from @objectstack/spec/automation
- Scheduled automations SHOULD use TimeTriggerSchema for schedule configuration

Metrics & Methodology

How This Evaluation Was Conducted

1. Spec Module Inventory: All 12 exported modules of @objectstack/spec v3.0.0 were cataloged from package.json exports and their .d.ts type definitions.
2. Import Analysis: All from '@objectstack/spec/*' imports across HotCRM's 6 business packages + AI package were collected and categorized.
3. Pattern Matching: Untyped metadata patterns (plain objects for pages, views, workflows, plugins) were identified by examining file contents against corresponding spec schemas.
4. JSON Schema Cross-Reference: The 1,256 JSON schemas in @objectstack/spec/json-schema/ were cross-referenced against HotCRM's metadata usage.

Schema Count by Domain (from json-schema/)

Note: v3.0.0 removed the hub (34 schemas), identity (23 schemas) domains, reducing the total from 1,256 to 1,199.

Zod 4 Compatibility

@objectstack/spec v3.0.0 uses Zod 4.3.6 as its validation engine. The following files in HotCRM import zod directly:

Compatibility Status: All 9 files are compatible with Zod 4. Seven use import type (type-only imports that are erased at compile time). The two runtime imports (core/zod-helper.ts and crm/lead.schema.ts) use standard Zod patterns (z.string(), z.object(), z.enum()) that are fully backward-compatible in Zod 4. No migration action is required.

Conclusion

HotCRM has built a solid foundation using @objectstack/spec's metadata system. With Phase 7–8 work, adoption has grown from ~13% to ~25% of available spec capabilities. Key achievements:

1. UI metadata fully typed — All page layouts, list views, dashboards, and forms validate against spec schemas using satisfies and .parse()
2. Expanded field types — 22 of 44 field types adopted, including masterDetail, summary, select({multiple:true}), file, image, location, address
3. Formal automation schemas — Workflows and state machines validated against spec schemas
4. Studio module adopted — defineStudioPlugin() used for admin extensions
5. System-level configs — Cache, notification, audit, webhook, and API configurations formally defined
6. Security metadata — Permission sets defined via PermissionSetSchema
7. Zod 4 compatible — All direct Zod imports confirmed compatible with Zod 4.3.6

The remaining gaps are primarily in integration connectors, report definitions, event bus configuration, and advanced API features. These represent future opportunities as the platform matures.