lcp 0.1.0

data/lib/lcp_ruby/schemas/model.json

@@ -0,0 +1,1161 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lcp-ruby.dev/schemas/model.json",
+  "title": "LCP Ruby Model Definition",
+  "description": "Schema for model metadata that defines database structure, validations, associations, scopes, and events. Models are defined in config/lcp_ruby/models/ as YAML files or via Ruby DSL.",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique model identifier. Used to reference the model from presenters, permissions, and associations.",
+      "examples": ["employee", "todo_item", "deal"]
+    },
+    "label": {
+      "type": "string",
+      "description": "Human-readable singular name for the model. Falls back to humanized name if omitted.",
+      "examples": ["Employee", "Todo Item"]
+    },
+    "label_plural": {
+      "type": "string",
+      "description": "Human-readable plural name for the model. Falls back to Rails pluralization of label.",
+      "examples": ["Employees", "Todo Items"]
+    },
+    "abstract": {
+      "type": "boolean",
+      "description": "When true, this model serves as a reusable template. Abstract models produce no AR class or DB table — their fields, associations, scopes, etc. are merged into child models that reference them via 'inherits'.",
+      "default": false
+    },
+    "inherits": {
+      "type": "string",
+      "description": "Name of a parent model to inherit from. The parent must be either abstract (abstract: true) or an STI parent (options.sti: true). The parent's fields, associations, scopes, events, validations, options, virtual_columns, display_templates, and indexes are merged into this model. Child values override parent values for same-named items. For abstract parents, the child gets its own table. For STI parents, the child shares the parent's table via Single Table Inheritance.",
+      "examples": ["_auditable", "_base_entity", "document"]
+    },
+    "_sti_child": {
+      "type": "boolean",
+      "description": "Internal marker injected by ModelInheritanceResolver for STI child models. Not user-configurable."
+    },
+    "table_name": {
+      "type": "string",
+      "description": "Override the database table name. Defaults to Rails convention (pluralized snake_case). Use '_virtual' for metadata-only models (no AR class or DB table).",
+      "examples": ["hr_employees", "_virtual"]
+    },
+    "fields": {
+      "type": "array",
+      "description": "Database columns and their configuration. Each field becomes an ActiveRecord attribute with optional validations and transforms.",
+      "items": { "$ref": "#/$defs/field" }
+    },
+    "associations": {
+      "type": "array",
+      "description": "ActiveRecord associations (belongs_to, has_many, has_one) with other LCP models or external AR classes.",
+      "items": { "$ref": "#/$defs/association" }
+    },
+    "validations": {
+      "type": "array",
+      "description": "Model-level validations not attached to a specific field (e.g., cross-field comparisons, custom validators).",
+      "items": { "$ref": "#/$defs/validation" }
+    },
+    "scopes": {
+      "type": "array",
+      "description": "Named query scopes for filtering records. Simple scopes use where/order/limit; complex scopes use type: custom or type: parameterized.",
+      "items": { "$ref": "#/$defs/scope" }
+    },
+    "events": {
+      "type": "array",
+      "description": "Lifecycle and field-change events dispatched to registered handlers in app/event_handlers/.",
+      "items": { "$ref": "#/$defs/event" }
+    },
+    "display_templates": {
+      "type": "object",
+      "description": "Named templates for rendering model records in different contexts (e.g., association lists, search results). Keys are template names.",
+      "additionalProperties": { "$ref": "#/$defs/display_template" },
+      "examples": [{ "default": { "template": "{first_name} {last_name}", "subtitle": "{department}", "icon": "user" } }]
+    },
+    "options": { "$ref": "#/$defs/model_options" },
+    "positioning": {
+      "description": "Enable drag-and-drop record ordering via the positioning gem. true uses defaults; object form allows customization.",
+      "oneOf": [
+        { "type": "boolean", "const": true },
+        {
+          "type": "object",
+          "properties": {
+            "field": {
+              "type": "string",
+              "description": "Column name storing the position integer.",
+              "default": "position"
+            },
+            "scope": {
+              "description": "Scope positioning within a parent (e.g., position per category). String for single scope, array for composite.",
+              "oneOf": [
+                { "type": "string" },
+                { "type": "array", "items": { "type": "string" } }
+              ],
+              "examples": ["category_id", ["project_id", "sprint_id"]]
+            }
+          },
+          "additionalProperties": false
+        }
+      ],
+      "examples": [true, { "field": "sort_order", "scope": "department_id" }]
+    },
+    "indexes": {
+      "type": "array",
+      "description": "Database indexes to create on the model's table. SchemaManager creates these at boot alongside the table.",
+      "items": { "$ref": "#/$defs/index" },
+      "examples": [[{ "columns": ["status", "created_at"] }, { "columns": ["email"], "unique": true }]]
+    },
+    "aggregates": {
+      "type": "object",
+      "description": "Legacy alias for virtual_columns. Prefer virtual_columns for new definitions.",
+      "additionalProperties": { "$ref": "#/$defs/aggregate" },
+      "examples": [{ "issues_count": { "function": "count", "association": "issues" }, "total_revenue": { "function": "sum", "association": "orders", "source_field": "amount" } }]
+    },
+    "virtual_columns": {
+      "type": "object",
+      "description": "Virtual columns computed via SQL subqueries, expressions, JOINs, or custom services. Each key is the column name, which becomes a virtual attribute referenceable in presenters.",
+      "additionalProperties": { "$ref": "#/$defs/aggregate" },
+      "examples": [{ "total_revenue": { "function": "sum", "association": "orders", "source_field": "amount" }, "health_score": { "service": "project_health", "type": "integer" } }]
+    },
+    "data_source": { "$ref": "#/$defs/data_source" },
+    "bind_to": {
+      "type": "string",
+      "description": "Fully qualified class name of an existing ActiveRecord model. When set, LCP uses this class as-is — no table creation (SchemaManager skip), no dynamic class (Builder skip). The class is resolved via constantize and registered in the LCP registry.",
+      "examples": ["LcpRuby::User", "::Employee", "Admin::Report"]
+    },
+    "bind_to_apply": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "enum": ["ransack", "scopes", "validations", "virtual_columns", "transforms",
+                 "computed_fields", "custom_fields", "workflow", "userstamps",
+                 "soft_delete", "auditing", "tree", "sequences", "positioning", "attachments",
+                 "enums", "service_accessors"]
+      },
+      "description": "Selective opt-in for LCP applicators on a bind_to model. Only listed features are applied to the bound class. Default: empty (no applicators run).",
+      "examples": [["ransack", "scopes"], ["workflow", "soft_delete"]]
+    },
+    "slug_field": {
+      "type": "string",
+      "description": "Name of a string field to use as URL slug. Enables human-readable URLs like /articles/my-slug. The field must be a DB-backed string column. When set, the dynamic model class overrides to_param and an exclusion validation against reserved route segments is auto-added.",
+      "examples": ["slug", "handle", "permalink"]
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": false,
+
+  "$defs": {
+    "model_options": {
+      "type": "object",
+      "description": "Model-wide feature toggles and configuration.",
+      "properties": {
+        "timestamps": {
+          "type": "boolean",
+          "description": "Add created_at and updated_at columns.",
+          "default": true
+        },
+        "label_method": {
+          "type": "string",
+          "description": "Method called on a record to produce its display label (used in association selects, display templates, etc.).",
+          "default": "to_s",
+          "examples": ["name", "title", "full_name"]
+        },
+        "custom_fields": {
+          "type": "boolean",
+          "description": "Enable runtime user-defined custom fields stored in a JSON column. Requires the custom_fields generator.",
+          "default": false
+        },
+        "soft_delete": {
+          "description": "Enable soft delete (discard/restore) instead of permanent destruction. Records are marked with a timestamp column rather than deleted.",
+          "oneOf": [
+            { "type": "boolean", "const": true },
+            {
+              "type": "object",
+              "properties": {
+                "column": {
+                  "type": "string",
+                  "description": "Name of the timestamp column for soft delete.",
+                  "default": "discarded_at"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [true, { "column": "archived_at" }]
+        },
+        "auditing": {
+          "description": "Enable change tracking. Records field-level diffs on create/update/destroy into an audit log model. Set to false (or omit) to disable.",
+          "oneOf": [
+            { "type": "boolean" },
+            {
+              "type": "object",
+              "properties": {
+                "only": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Whitelist: only track changes to these fields. Mutually exclusive with 'ignore'."
+                },
+                "ignore": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Blacklist: track all fields except these."
+                },
+                "track_associations": {
+                  "type": "boolean",
+                  "description": "Include association FK changes in audit diffs."
+                },
+                "track_attachments": {
+                  "type": "boolean",
+                  "description": "Include Active Storage attachment changes in audit diffs."
+                },
+                "expand_custom_fields": {
+                  "type": "boolean",
+                  "description": "Expand custom_fields JSON column into individual field diffs instead of logging raw JSON."
+                },
+                "expand_json_fields": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "List of JSON column names to expand into individual key diffs.",
+                  "examples": [["properties", "metadata"]]
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [true, { "ignore": ["updated_at", "position"], "expand_custom_fields": true }]
+        },
+        "userstamps": {
+          "description": "Automatically track which user created/updated each record via FK columns pointing to the user model.",
+          "oneOf": [
+            { "type": "boolean", "const": true },
+            {
+              "type": "object",
+              "properties": {
+                "created_by": {
+                  "type": "string",
+                  "description": "FK column name for the creating user.",
+                  "default": "created_by_id"
+                },
+                "updated_by": {
+                  "type": "string",
+                  "description": "FK column name for the last updating user.",
+                  "default": "updated_by_id"
+                },
+                "store_name": {
+                  "type": "boolean",
+                  "description": "Also store the user's display name in a separate column (e.g., created_by_name) as a snapshot for display without joins.",
+                  "default": false
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [true, { "store_name": true }, { "created_by": "author_id", "updated_by": "editor_id" }]
+        },
+        "sti": {
+          "type": "boolean",
+          "description": "Enable Single Table Inheritance. Adds a 'type' string column to distinguish AR subclasses. Child models reference this model via 'inherits' and share its table. Each child gets its own AR class, presenter, permissions, and workflow.",
+          "default": false
+        },
+        "tree": {
+          "description": "Enable self-referential tree hierarchy with parent/children associations, traversal methods, and cycle detection.",
+          "oneOf": [
+            { "type": "boolean", "const": true },
+            {
+              "type": "object",
+              "properties": {
+                "parent_field": {
+                  "type": "string",
+                  "description": "FK column pointing to the parent record. Must be declared in fields as integer type.",
+                  "default": "parent_id"
+                },
+                "children_name": {
+                  "type": "string",
+                  "description": "Name of the auto-generated has_many association for child records.",
+                  "default": "children"
+                },
+                "parent_name": {
+                  "type": "string",
+                  "description": "Name of the auto-generated belongs_to association for the parent record.",
+                  "default": "parent"
+                },
+                "dependent": {
+                  "type": "string",
+                  "description": "What happens to children when a parent is destroyed.",
+                  "enum": ["destroy", "nullify", "restrict_with_exception", "restrict_with_error", "discard"],
+                  "default": "destroy"
+                },
+                "max_depth": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Maximum nesting depth for cycle detection and traversal limits.",
+                  "default": 10
+                },
+                "ordered": {
+                  "type": "boolean",
+                  "description": "Enable position-based ordering of siblings within the same parent. Requires a position field.",
+                  "default": false
+                },
+                "position_field": {
+                  "type": "string",
+                  "description": "Column name for sibling ordering when ordered: true.",
+                  "default": "position"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [true, { "parent_field": "manager_id", "children_name": "subordinates", "ordered": true }]
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "field": {
+      "type": "object",
+      "description": "A database column with type, validations, and optional transforms.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Column name in the database. Must be unique within the model.",
+          "examples": ["title", "email", "hire_date", "salary"]
+        },
+        "type": {
+          "type": "string",
+          "description": "Data type. Base types: string, text, integer, float, decimal, boolean, date, datetime, enum, file, rich_text, json, uuid, attachment, array. Built-in types (email, phone, url, color, bigint) and user-defined types from config/lcp_ruby/types/ are also valid.",
+          "examples": ["string", "integer", "boolean", "date", "enum", "email", "attachment", "array"]
+        },
+        "item_type": {
+          "type": "string",
+          "description": "Element type for array fields. Required when type is 'array'.",
+          "enum": ["string", "integer", "float"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable label. Falls back to humanized field name."
+        },
+        "default": {
+          "description": "Default value for new records. Type must match the field type."
+        },
+        "transforms": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Value transforms applied before save: strip, downcase, upcase, normalize_url, normalize_phone, etc.",
+          "examples": [["strip", "downcase"]]
+        },
+        "column_options": { "$ref": "#/$defs/column_options" },
+        "validations": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/validation" },
+          "description": "Field-level validations applied to this column."
+        },
+        "enum_values": {
+          "type": "array",
+          "items": {},
+          "description": "For enum fields: list of allowed values. Can be strings or {value, label} objects.",
+          "examples": [["draft", "active", "archived"], [{ "value": "m", "label": "Male" }, { "value": "f", "label": "Female" }]]
+        },
+        "computed": {
+          "type": ["string", "object"],
+          "description": "Read-only computed field. String form is a Ruby expression; object form uses a service.",
+          "examples": ["first_name + ' ' + last_name"]
+        },
+        "sequence": {
+          "description": "Auto-numbering sequence field. Assigns a unique sequential value on record creation. Requires the gapfree_sequences generator. Use `true` as shorthand for all defaults (global scope, raw counter, start 1, step 1).",
+          "oneOf": [
+            { "type": "boolean", "const": true },
+            {
+              "type": "object",
+              "properties": {
+                "scope": {
+                  "type": "array",
+                  "items": { "type": "string" },
+                  "description": "Scope columns or virtual keys (_year, _month, _day). Counter resets independently per unique scope combination.",
+                  "examples": [["_year"], ["department_id", "_year"]]
+                },
+                "format": {
+                  "type": "string",
+                  "description": "Template for the final value. Supports %{sequence}, %{sequence:Nd} (zero-padded), %{_year}, %{_month}, %{_day}, and %{field_name}.",
+                  "examples": ["INV-%{_year}-%{sequence:04d}", "TKT-%{sequence:06d}"]
+                },
+                "start": {
+                  "type": "integer",
+                  "minimum": 0,
+                  "description": "Initial counter value for a new scope.",
+                  "default": 1
+                },
+                "step": {
+                  "type": "integer",
+                  "minimum": 1,
+                  "description": "Increment per record.",
+                  "default": 1
+                },
+                "readonly": {
+                  "type": "boolean",
+                  "description": "When true, the field is rendered as a disabled input in forms (visible but not editable).",
+                  "default": true
+                },
+                "assign_on": {
+                  "type": "string",
+                  "description": "When to assign: 'create' (before_create only) or 'always' (also fills blank values on update).",
+                  "enum": ["create", "always"],
+                  "default": "create"
+                }
+              },
+              "additionalProperties": false
+            }
+          ],
+          "examples": [
+            true,
+            { "format": "TKT-%{sequence:06d}" },
+            { "scope": ["_year"], "format": "INV-%{_year}-%{sequence:04d}" }
+          ]
+        },
+        "options": {
+          "type": "object",
+          "description": "Type-specific options. For attachments: content_type, max_size, max_files, variants. For other types: custom options passed to the type handler.",
+          "examples": [{ "content_type": ["image/png", "image/jpeg"], "max_size": 5242880 }]
+        },
+        "source": {
+          "description": "Data source for virtual/external fields. 'external' means the field is not backed by a DB column. Object form uses a service (e.g., json_field extractor).",
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "object",
+              "properties": {
+                "service": {
+                  "type": "string",
+                  "description": "Data provider service name from app/lcp_services/data_providers/."
+                },
+                "options": {
+                  "type": "object",
+                  "description": "Options passed to the data provider service."
+                }
+              },
+              "required": ["service"],
+              "additionalProperties": false
+            }
+          ],
+          "examples": ["external", { "service": "json_field", "options": { "column": "properties", "key": "color" } }]
+        },
+        "lcp_managed": {
+          "type": "boolean",
+          "description": "For bind_to: models only. When true, LCP additively adds this field as a column to the bound table at boot (ALTER TABLE ADD COLUMN if missing, additive only). When false (default), the field is metadata-only and the column is expected to exist on the host class. Ignored on dynamic models. See docs/design/bind_to_managed_fields_and_associations.md.",
+          "default": false
+        }
+      },
+      "required": ["name", "type"],
+      "additionalProperties": false
+    },
+
+    "column_options": {
+      "type": "object",
+      "description": "Database column options passed directly to the Rails migration column definition.",
+      "properties": {
+        "limit": {
+          "type": "integer",
+          "description": "Maximum length for string columns or byte size for binary columns.",
+          "examples": [255, 1000]
+        },
+        "null": {
+          "type": "boolean",
+          "description": "Whether the column allows NULL values.",
+          "default": true
+        },
+        "precision": {
+          "type": "integer",
+          "description": "Total number of digits for decimal columns.",
+          "examples": [10, 15]
+        },
+        "scale": {
+          "type": "integer",
+          "description": "Number of digits after the decimal point for decimal columns.",
+          "examples": [2, 4]
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "validation": {
+      "type": "object",
+      "description": "A validation rule applied to a field or at model level.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Validation type. Maps to Rails validators (e.g., presence → validates_presence_of).",
+          "enum": ["presence", "length", "numericality", "format", "inclusion", "exclusion", "uniqueness", "confirmation", "custom", "comparison", "service", "array_length", "array_inclusion", "array_uniqueness"]
+        },
+        "options": {
+          "type": "object",
+          "description": "Options passed to the validator (e.g., {minimum: 3} for length, {greater_than: 0} for numericality).",
+          "examples": [{ "minimum": 1, "maximum": 255 }, { "greater_than": 0 }]
+        },
+        "when": {
+          "$ref": "#/$defs/condition",
+          "description": "Conditional validation — only runs when the condition is met."
+        },
+        "message": {
+          "type": "string",
+          "description": "Custom error message override.",
+          "examples": ["must be at least 3 characters"]
+        },
+        "validator_class": {
+          "type": "string",
+          "description": "Fully qualified class name for type: custom validators.",
+          "examples": ["PhoneNumberValidator"]
+        },
+        "field_ref": {
+          "type": "string",
+          "description": "Reference to another field for cross-field validations (e.g., comparison).",
+          "examples": ["start_date"]
+        },
+        "operator": {
+          "type": "string",
+          "description": "Comparison operator for cross-field validations.",
+          "examples": ["gt", "gte", "lt", "lte"]
+        },
+        "service": {
+          "type": "string",
+          "description": "Service class name for type: service validations.",
+          "examples": ["EmailDomainValidator"]
+        },
+        "field": {
+          "type": "string",
+          "description": "Target field name for model-level validations (when validation is not nested under a field)."
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": false
+    },
+
+    "association": {
+      "type": "object",
+      "description": "An ActiveRecord association linking this model to another model.",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Association type.",
+          "enum": ["belongs_to", "has_many", "has_one"]
+        },
+        "name": {
+          "type": "string",
+          "description": "Association name used in code and presenter references.",
+          "examples": ["department", "employees", "manager"]
+        },
+        "target_model": {
+          "type": "string",
+          "description": "Name of the associated LCP model. Omit for non-LCP (external AR) classes.",
+          "examples": ["department", "employee"]
+        },
+        "class_name": {
+          "type": "string",
+          "description": "Explicit AR class name. Use when the association name doesn't match the model (e.g., 'manager' → 'User').",
+          "examples": ["User", "LcpRuby::Dynamic::Employee"]
+        },
+        "foreign_key": {
+          "type": "string",
+          "description": "FK column name. Defaults to Rails convention ({name}_id for belongs_to).",
+          "examples": ["manager_id", "department_id"]
+        },
+        "primary_key": {
+          "type": "string",
+          "description": "Column on the target model (for belongs_to) or owning model (for has_many/has_one) that the foreign_key matches against. Defaults to the target model's primary key (usually 'id'). Not allowed with through: or polymorphic: true.",
+          "examples": ["vema_code", "external_id", "sku"]
+        },
+        "dependent": {
+          "type": "string",
+          "description": "Behavior when the owning record is destroyed.",
+          "enum": ["destroy", "delete", "delete_all", "nullify", "restrict_with_exception", "restrict_with_error", "discard"]
+        },
+        "required": {
+          "type": "boolean",
+          "description": "For belongs_to: make the association mandatory (adds presence validation on FK)."
+        },
+        "inverse_of": {
+          "type": "string",
+          "description": "Name of the reciprocal association on the target model. Helps Rails avoid extra queries.",
+          "examples": ["employees", "department"]
+        },
+        "counter_cache": {
+          "type": ["string", "boolean"],
+          "description": "For belongs_to: maintain a counter column on the parent. true uses Rails convention ({plural}_count), string overrides the column name.",
+          "examples": [true, "members_count"]
+        },
+        "touch": {
+          "type": ["string", "boolean"],
+          "description": "For belongs_to: touch the parent's updated_at when this record changes. String form touches a specific column.",
+          "examples": [true, "last_activity_at"]
+        },
+        "polymorphic": {
+          "type": "boolean",
+          "description": "For belongs_to: enable polymorphic association (stores type + id)."
+        },
+        "as": {
+          "type": "string",
+          "description": "For has_many/has_one: the polymorphic interface name on the target model.",
+          "examples": ["commentable", "attachable"]
+        },
+        "through": {
+          "type": "string",
+          "description": "For has_many :through — name of the join association on this model.",
+          "examples": ["employee_skills"]
+        },
+        "source": {
+          "type": "string",
+          "description": "For has_many :through — source association name on the join model when it differs from the association name.",
+          "examples": ["skill"]
+        },
+        "autosave": {
+          "type": "boolean",
+          "description": "Automatically save associated records when the parent is saved."
+        },
+        "validate": {
+          "type": "boolean",
+          "description": "Run validations on associated records when saving."
+        },
+        "order": {
+          "type": "object",
+          "description": "Default ordering for the association (e.g., {created_at: 'desc'}).",
+          "examples": [{ "created_at": "desc" }, { "position": "asc" }]
+        },
+        "nested_attributes": { "$ref": "#/$defs/nested_attributes" },
+        "lcp_managed": {
+          "type": "boolean",
+          "description": "For bind_to: models only. When true, LCP applies the AR macro on the host class (and for belongs_to, additively adds the FK column). When false (default), the association is metadata-only and must be declared by the host class in Ruby. Ignored on dynamic models. See docs/design/bind_to_managed_fields_and_associations.md.",
+          "default": false
+        },
+        "skip_inverse_check": {
+          "type": "boolean",
+          "description": "For belongs_to only. When true, suppresses the missing-inverse warning from `lcp_ruby:validate`. Use for intentionally one-directional associations (e.g. audit references like `created_by` or `author`, where reverse traversal would be noise). Setting this on has_many/has_one is rejected at boot — that case is a real bug.",
+          "default": false
+        }
+      },
+      "required": ["type", "name"],
+      "additionalProperties": false
+    },
+
+    "nested_attributes": {
+      "description": "Enable accepts_nested_attributes_for on this association.",
+      "oneOf": [
+        {
+          "const": true,
+          "description": "Enable with safe defaults (reject_if: all_blank, update_only: true)."
+        },
+        {
+          "type": "object",
+          "description": "Enable with explicit options.",
+          "properties": {
+            "allow_destroy": {
+              "type": "boolean",
+              "description": "Allow removing associated records via _destroy param."
+            },
+            "reject_if": {
+              "type": "string",
+              "description": "Rejection strategy for new nested records. 'all_blank' skips when all values are blank.",
+              "examples": ["all_blank"]
+            },
+            "limit": {
+              "type": "integer",
+              "description": "Maximum number of nested records allowed."
+            },
+            "update_only": {
+              "type": "boolean",
+              "description": "When true, existing nested records are updated in-place instead of being destroyed and recreated. New records can still be created when none exists."
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+
+    "scope": {
+      "type": "object",
+      "description": "A named query scope for filtering records.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Scope name. Used in predefined filters, permission scopes, and URL params.",
+          "examples": ["active", "recent", "by_department"]
+        },
+        "type": {
+          "type": "string",
+          "description": "'custom' means implemented in the host app as a class method. 'parameterized' accepts typed parameters from the UI.",
+          "enum": ["custom", "parameterized"]
+        },
+        "where": {
+          "type": "object",
+          "description": "Simple where clause. Keys are column names, values are match values.",
+          "examples": [{ "status": "active" }, { "published": true }]
+        },
+        "where_not": {
+          "type": "object",
+          "description": "Negated where clause. Generates scope with where.not(...).",
+          "examples": [{ "status": "archived" }]
+        },
+        "order": {
+          "type": "object",
+          "description": "Sort order applied by this scope.",
+          "examples": [{ "created_at": "desc" }]
+        },
+        "limit": {
+          "type": "integer",
+          "description": "Maximum number of records returned by this scope.",
+          "examples": [10, 50]
+        },
+        "parameters": {
+          "type": "array",
+          "description": "Parameter definitions for type: parameterized scopes. Each parameter is cast from request params and passed to the scope method.",
+          "items": { "$ref": "#/$defs/scope_parameter" }
+        }
+      },
+      "required": ["name"],
+      "additionalProperties": false,
+      "examples": [
+        { "name": "active", "where": { "status": "active" } },
+        { "name": "above_value", "type": "parameterized", "parameters": [{ "name": "min_value", "type": "float", "required": true, "min": 0 }] }
+      ]
+    },
+
+    "scope_parameter": {
+      "type": "object",
+      "description": "A typed parameter for a parameterized scope. Values are cast from string request params at runtime.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Parameter name (used as the key in request params).",
+          "examples": ["min_value", "status", "department_id"]
+        },
+        "type": {
+          "type": "string",
+          "description": "Parameter data type. Determines how the raw string value is cast.",
+          "enum": ["integer", "float", "decimal", "string", "enum", "date", "datetime", "boolean", "model_select"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Human-readable label for the parameter in the filter UI."
+        },
+        "required": {
+          "type": "boolean",
+          "description": "If true, the scope is skipped when this parameter is missing."
+        },
+        "default": {
+          "description": "Default value used when the parameter is not provided."
+        },
+        "values": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "For type: enum — list of allowed values. Input not in this list is rejected.",
+          "examples": [["active", "inactive", "pending"]]
+        },
+        "model": {
+          "type": "string",
+          "description": "For type: model_select — the LCP model name to populate the select dropdown.",
+          "examples": ["department", "category"]
+        },
+        "min": {
+          "type": "number",
+          "description": "For numeric types — minimum allowed value (clamped, not rejected)."
+        },
+        "max": {
+          "type": "number",
+          "description": "For numeric types — maximum allowed value (clamped, not rejected)."
+        }
+      },
+      "required": ["name", "type"],
+      "additionalProperties": false
+    },
+
+    "index": {
+      "type": "object",
+      "description": "A database index created on the model's table by SchemaManager.",
+      "properties": {
+        "columns": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Column names included in the index. Order matters for composite indexes.",
+          "examples": [["status", "created_at"], ["email"]]
+        },
+        "unique": {
+          "type": "boolean",
+          "description": "Create a unique index (enforces uniqueness constraint at the DB level)."
+        },
+        "name": {
+          "type": "string",
+          "description": "Custom index name. Auto-generated if omitted."
+        }
+      },
+      "required": ["columns"],
+      "additionalProperties": false
+    },
+
+    "event": {
+      "type": "object",
+      "description": "A lifecycle or field-change event dispatched to registered handlers in app/event_handlers/.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Event name. For lifecycle events: after_create, after_update, before_destroy, after_destroy. For field_change: a custom name.",
+          "examples": ["after_create", "on_status_change"]
+        },
+        "type": {
+          "type": "string",
+          "description": "Event type. 'lifecycle' fires on AR callbacks; 'field_change' fires when a specific field value changes.",
+          "enum": ["lifecycle", "field_change"]
+        },
+        "field": {
+          "type": "string",
+          "description": "For type: field_change — the field name to monitor for changes.",
+          "examples": ["status", "assigned_to_id"]
+        },
+        "condition": {
+          "type": ["string", "object"],
+          "description": "Optional condition that must be met for the event to fire.",
+          "examples": [{ "field": "status", "operator": "eq", "value": "completed" }]
+        }
+      },
+      "required": ["name"],
+      "additionalProperties": false
+    },
+
+    "display_template": {
+      "type": "object",
+      "description": "Template for rendering a model record in association lists, search results, or menu badges. Uses {field_name} interpolation.",
+      "properties": {
+        "template": {
+          "type": "string",
+          "description": "Text template with {field_name} placeholders.",
+          "examples": ["{first_name} {last_name}", "{name} (#{code})"]
+        },
+        "subtitle": {
+          "type": "string",
+          "description": "Secondary line template shown below the main template.",
+          "examples": ["{department} — {job_title}"]
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon name displayed alongside the template.",
+          "examples": ["user", "briefcase", "folder"]
+        },
+        "badge": {
+          "type": "string",
+          "description": "Field name whose value is rendered as a badge next to the template.",
+          "examples": ["status"]
+        },
+        "renderer": {
+          "type": "string",
+          "description": "Custom renderer name for the entire display template."
+        },
+        "partial": {
+          "type": "string",
+          "description": "ERB partial path for fully custom rendering."
+        },
+        "options": {
+          "type": "object",
+          "description": "Options passed to the renderer or partial."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "data_source": {
+      "type": "object",
+      "description": "External data source configuration. When present, the model reads from an API instead of the database. Phase 1 is read-only (index + show).",
+      "properties": {
+        "type": {
+          "type": "string",
+          "description": "Data source adapter type.",
+          "enum": ["rest_json", "host"]
+        },
+        "base_url": {
+          "type": "string",
+          "description": "Base URL for REST JSON API. Required when type is 'rest_json'.",
+          "examples": ["https://api.example.com"]
+        },
+        "resource": {
+          "type": "string",
+          "description": "API resource path (pluralized). Defaults to model name pluralized.",
+          "examples": ["buildings", "products"]
+        },
+        "provider": {
+          "type": "string",
+          "description": "Host-provided class name implementing the data source contract. Required when type is 'host'.",
+          "examples": ["ErpProductProvider", "GisServiceAdapter"]
+        },
+        "timeout": {
+          "type": "integer",
+          "description": "HTTP request timeout in seconds.",
+          "default": 30
+        },
+        "id_field": {
+          "type": "string",
+          "description": "Remote field name for the primary key. Mapped to :id locally.",
+          "default": "id"
+        },
+        "auth": {
+          "type": "object",
+          "description": "Authentication configuration for REST JSON APIs.",
+          "properties": {
+            "type": {
+              "type": "string",
+              "description": "Authentication type.",
+              "enum": ["bearer", "basic", "header"]
+            },
+            "token_env": {
+              "type": "string",
+              "description": "Environment variable name containing the bearer token.",
+              "examples": ["BUILDINGS_API_TOKEN"]
+            },
+            "username_env": {
+              "type": "string",
+              "description": "Environment variable name for basic auth username."
+            },
+            "password_env": {
+              "type": "string",
+              "description": "Environment variable name for basic auth password."
+            },
+            "header_name": {
+              "type": "string",
+              "description": "Custom header name for header auth type.",
+              "default": "X-API-Key"
+            },
+            "value_env": {
+              "type": "string",
+              "description": "Environment variable name for header auth value."
+            }
+          },
+          "required": ["type"],
+          "additionalProperties": false
+        },
+        "pagination": {
+          "type": "object",
+          "description": "Pagination configuration for REST JSON APIs.",
+          "properties": {
+            "style": {
+              "type": "string",
+              "description": "Pagination style.",
+              "enum": ["offset_limit", "page_number", "cursor"],
+              "default": "offset_limit"
+            },
+            "offset_param": { "type": "string", "default": "offset" },
+            "limit_param": { "type": "string", "default": "limit" },
+            "page_param": { "type": "string", "default": "page" },
+            "size_param": { "type": "string", "default": "per_page" },
+            "sort_param": { "type": "string", "default": "sort" }
+          },
+          "additionalProperties": false
+        },
+        "cache": {
+          "type": "object",
+          "description": "Caching configuration. Wraps the adapter with CachedWrapper when present.",
+          "properties": {
+            "ttl": {
+              "type": "integer",
+              "description": "Cache TTL for individual record lookups (seconds).",
+              "default": 300
+            },
+            "list_ttl": {
+              "type": "integer",
+              "description": "Cache TTL for search/list operations (seconds).",
+              "default": 60
+            },
+            "stale_on_error": {
+              "type": "boolean",
+              "description": "Serve expired cached data when the API is unreachable.",
+              "default": true
+            }
+          },
+          "additionalProperties": false
+        },
+        "field_mapping": {
+          "type": "object",
+          "description": "Maps local field names to remote API field names. Keys are local names, values are remote names.",
+          "additionalProperties": { "type": "string" },
+          "examples": [{ "name": "building_name", "address": "building_address" }]
+        },
+        "supported_operators": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Filter operators supported by this API. Unsupported operators are silently dropped.",
+          "examples": [["eq", "cont", "gt", "lt"]]
+        },
+        "endpoints": {
+          "type": "object",
+          "description": "Custom endpoint configuration for REST JSON APIs.",
+          "properties": {
+            "show": {
+              "type": "object",
+              "properties": {
+                "path": { "type": "string", "description": "URL path for show endpoint. Use :id placeholder.", "examples": ["buildings/:id"] },
+                "response_path": { "type": "string", "description": "Dot-path to navigate into JSON response.", "examples": ["data"] }
+              },
+              "additionalProperties": false
+            },
+            "search": {
+              "type": "object",
+              "properties": {
+                "method": { "type": "string", "enum": ["GET", "POST"], "default": "GET" },
+                "path": { "type": "string" },
+                "response_path": { "type": "string", "examples": ["data.items"] },
+                "total_count_path": { "type": "string", "examples": ["data.total"] }
+              },
+              "additionalProperties": false
+            },
+            "batch": {
+              "type": "object",
+              "properties": {
+                "path": { "type": "string" },
+                "response_path": { "type": "string" }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": false,
+      "examples": [
+        { "type": "host", "provider": "ErpProductProvider" },
+        { "type": "rest_json", "base_url": "https://api.example.com", "resource": "buildings", "auth": { "type": "bearer", "token_env": "API_TOKEN" } }
+      ]
+    },
+
+    "condition": {
+      "description": "Conditional trigger: field-based condition object (with field/operator/value keys), service reference, or a method name string.",
+      "type": ["object", "string"],
+      "examples": [
+        { "field": "status", "operator": "eq", "value": "active" },
+        "can_archive?"
+      ]
+    },
+
+    "aggregate": {
+      "description": "A virtual aggregate column definition. Exactly one of three types must be used: declarative (function+association), custom SQL expression, or service-based computation.",
+      "oneOf": [
+        {
+          "type": "object",
+          "description": "Declarative aggregate: SQL aggregate function over a has_many association.",
+          "properties": {
+            "function": {
+              "type": "string",
+              "description": "SQL aggregate function.",
+              "enum": ["count", "sum", "min", "max", "avg"]
+            },
+            "association": {
+              "type": "string",
+              "description": "Name of a has_many association on the model.",
+              "examples": ["issues", "orders", "comments"]
+            },
+            "source_field": {
+              "type": "string",
+              "description": "Field on the target model to aggregate. Required for sum/min/max/avg; optional for count (defaults to *).",
+              "examples": ["amount", "created_at", "score"]
+            },
+            "where": {
+              "type": "object",
+              "description": "Hash equality conditions on the target model. Supports :current_user placeholder for per-user aggregates.",
+              "examples": [{ "status": "open" }, { "assignee_id": ":current_user" }]
+            },
+            "distinct": {
+              "type": "boolean",
+              "description": "Use DISTINCT in the aggregate function (e.g., COUNT(DISTINCT ...) or SUM(DISTINCT ...)).",
+              "default": false
+            },
+            "default": {
+              "description": "Default value via COALESCE wrap. COUNT always defaults to 0 even without this setting."
+            },
+            "include_discarded": {
+              "type": "boolean",
+              "description": "When false (default), excludes soft-deleted records from the aggregate. Only applies when the target model uses soft_delete.",
+              "default": false
+            },
+            "type": {
+              "type": "string",
+              "description": "Explicit result type override. Normally inferred from function and source field type.",
+              "enum": ["string", "integer", "float", "decimal", "boolean", "date", "datetime"]
+            }
+          },
+          "required": ["function", "association"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Custom SQL aggregate: raw SQL subquery returning a single value.",
+          "properties": {
+            "sql": {
+              "type": "string",
+              "description": "Custom SQL subquery returning a single value. Use %{table} placeholder for the parent model's table name.",
+              "examples": ["SELECT SUM(r.score * r.weight) / NULLIF(SUM(r.weight), 0) FROM ratings r WHERE r.project_id = %{table}.id"]
+            },
+            "type": {
+              "type": "string",
+              "description": "Result type. Required for SQL aggregates.",
+              "enum": ["string", "integer", "float", "decimal", "boolean", "date", "datetime"]
+            },
+            "default": {
+              "description": "Default value via COALESCE wrap."
+            }
+          },
+          "required": ["sql", "type"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Expression-based virtual column: inline SQL expression with optional JOIN and GROUP BY.",
+          "properties": {
+            "expression": {
+              "type": "string",
+              "description": "SQL expression evaluated in the SELECT clause. Use %{table} placeholder for the parent model's table name.",
+              "examples": ["(SELECT COUNT(*) FROM tasks WHERE tasks.project_id = %{table}.id AND tasks.due_date < CURRENT_DATE)"]
+            },
+            "type": {
+              "type": "string",
+              "description": "Result type. Required for expression columns.",
+              "enum": ["string", "integer", "float", "decimal", "boolean", "date", "datetime"]
+            },
+            "join": {
+              "type": "string",
+              "description": "SQL JOIN clause to append when this column is included. Use %{table} placeholder.",
+              "examples": ["LEFT OUTER JOIN companies ON companies.id = %{table}.company_id"]
+            },
+            "group": {
+              "type": "boolean",
+              "description": "Whether this column requires GROUP BY on the parent table's primary key.",
+              "default": false
+            },
+            "default": {
+              "description": "Default value via COALESCE wrap."
+            },
+            "auto_include": {
+              "type": "boolean",
+              "description": "Automatically include this virtual column in all queries for this model.",
+              "default": false
+            }
+          },
+          "required": ["expression", "type"],
+          "additionalProperties": false
+        },
+        {
+          "type": "object",
+          "description": "Service-based aggregate: computed by a Ruby service class.",
+          "properties": {
+            "service": {
+              "type": "string",
+              "description": "Service key looked up in app/lcp_services/aggregates/. The service class must implement self.call(record, options:).",
+              "examples": ["project_health", "custom_score"]
+            },
+            "type": {
+              "type": "string",
+              "description": "Result type. Required for service aggregates.",
+              "enum": ["string", "integer", "float", "decimal", "boolean", "date", "datetime"]
+            },
+            "options": {
+              "type": "object",
+              "description": "Options hash passed to the service."
+            }
+          },
+          "required": ["service", "type"],
+          "additionalProperties": false
+        }
+      ]
+    }
+  }
+}