lcp 0.1.0

data/lib/lcp_ruby/schemas/page.json

@@ -0,0 +1,877 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lcp-ruby.dev/schemas/page.json",
+  "title": "LCP Ruby Page Definition",
+  "description": "Schema for page metadata that defines a standalone page composed of zones (presenter regions and/or widgets). Pages are defined in config/lcp_ruby/pages/ as YAML files. Each page has a unique name, optional slug for routing, and one or more zones that display presenter content or widgets (KPI cards, text blocks, lists).",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Unique identifier for this page. Used in view group references and dialog targets.",
+      "examples": ["main_dashboard", "quick_create_order", "employee_overview"]
+    },
+    "slug": {
+      "type": "string",
+      "description": "URL slug that makes this page routable. Pages without a slug are only accessible as dialog targets. Must be unique across all pages.",
+      "examples": ["dashboard", "overview", "reports"]
+    },
+    "model": {
+      "type": "string",
+      "description": "The model this page is associated with. Standalone dashboard pages may omit this. Used for permission checks and breadcrumb context.",
+      "examples": ["employee", "order", "task"]
+    },
+    "layout": {
+      "type": "string",
+      "description": "Layout mode for zone arrangement. 'semantic' uses named areas (main, sidebar). 'grid' uses CSS grid with explicit row/col positioning.",
+      "enum": ["semantic", "grid"],
+      "default": "semantic",
+      "examples": ["semantic", "grid"]
+    },
+    "title": {
+      "type": "string",
+      "description": "Page title (literal). Carries the canonical default-locale value; serves as the I18n.t default when `title_key:` is also set, or stands alone when it isn't. Same literal-as-default precedence as chart widgets / filter_form / kpi_card per CLAUDE.md § i18n.",
+      "examples": ["HR Turnover Dashboard"]
+    },
+    "title_key": {
+      "type": "string",
+      "description": "i18n key for the page title. Falls back to `title:` literal, then to humanized page name.",
+      "examples": ["lcp_ruby.dashboard.title", "lcp_ruby.pages.overview"]
+    },
+    "index_presenter": {
+      "type": "string",
+      "description": "Presenter to use for the index action when this page owns the slug. Useful for composite pages where the main zone presenter has no index columns. The index_presenter must have index columns defined.",
+      "examples": ["company", "order"]
+    },
+    "dialog": {
+      "$ref": "#/$defs/dialog_config",
+      "description": "Dialog rendering configuration. When present, this page can be rendered inside a modal dialog."
+    },
+    "filter_form": {
+      "type": "array",
+      "description": "Value-based filter fields rendered as a form above zones. Uses the same syntax as presenter form fields. Field values are propagated to all zone query pipelines via ScopeApplicator. Cascade (depends_on) and multi-select (input_options.multi) supported on association_select.",
+      "items": { "$ref": "#/$defs/filter_form_field" }
+    },
+    "scope_filters": {
+      "type": "array",
+      "description": "Predefined AR-scope toggles rendered as a separate widget above zones. Each entry maps a UI option to a named ActiveRecord scope on the page model. Semantically different from filter_form: (which filters by column value) — scope filters dispatch a named scope on the model.",
+      "items": { "$ref": "#/$defs/scope_filter" }
+    },
+    "auto_submit": {
+      "description": "Filter form submit behavior. ':derive' (default) auto-submits when no field has multi: or depends_on:; otherwise renders Apply button. 'true' forces auto-submit (boot-rejected if any field has depends_on:). 'false' forces Apply button.",
+      "oneOf": [
+        { "type": "string", "enum": ["derive"] },
+        { "type": "boolean" }
+      ],
+      "default": "derive"
+    },
+    "visible_when": {
+      "description": "Page-level visibility gate. Same shape as zone-level visible_when (role shortcut or full condition object). Validated at boot by RuntimeInvariantValidator (AUTH-002/003). Use `{ role: any }` for an explicit public opt-in.",
+      "anyOf": [
+        { "$ref": "#/$defs/role_condition" },
+        { "$ref": "#/$defs/condition_object" }
+      ]
+    },
+    "zones": {
+      "type": "array",
+      "description": "List of zones (content regions) on this page. Each zone displays either a presenter or a widget. Order matters for semantic layout; grid layout uses explicit positions.",
+      "items": { "$ref": "#/$defs/zone" },
+      "minItems": 1
+    }
+  },
+  "required": ["name", "zones"],
+  "additionalProperties": false,
+
+  "$defs": {
+    "dialog_config": {
+      "type": "object",
+      "description": "Configuration for rendering this page as a modal dialog.",
+      "properties": {
+        "size": {
+          "type": "string",
+          "description": "Dialog size preset.",
+          "enum": ["small", "medium", "large", "fullscreen"],
+          "default": "medium"
+        },
+        "closable": {
+          "type": "boolean",
+          "description": "Whether the dialog can be closed by clicking outside or pressing Escape.",
+          "default": true
+        },
+        "title_key": {
+          "type": "string",
+          "description": "i18n key for the dialog title bar. Falls back to page title.",
+          "examples": ["lcp_ruby.dialogs.quick_create", "lcp_ruby.dialogs.confirm"]
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "zone": {
+      "type": "object",
+      "description": "A content region within the page. Either a presenter zone (displays a full presenter) or a widget zone (displays a KPI card, text block, or list).",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Unique identifier for this zone within the page."
+        },
+        "type": {
+          "type": "string",
+          "description": "Zone type. 'presenter' (default) renders a full presenter. 'widget' renders a standalone widget. 'custom' renders a host-app partial.",
+          "enum": ["presenter", "widget", "custom"],
+          "default": "presenter"
+        },
+        "presenter": {
+          "type": "string",
+          "description": "Presenter name to render in this zone. Required for presenter zones.",
+          "examples": ["employees", "dashboard_tasks"]
+        },
+        "area": {
+          "type": "string",
+          "description": "Named area for semantic layout placement.",
+          "enum": ["main", "tabs", "sidebar", "below"],
+          "default": "main",
+          "examples": ["main", "tabs", "sidebar", "below"]
+        },
+        "widget": {
+          "description": "Widget configuration for widget zones.",
+          "oneOf": [
+            { "$ref": "#/$defs/kpi_card_widget" },
+            { "$ref": "#/$defs/text_widget" },
+            { "$ref": "#/$defs/list_widget" },
+            { "$ref": "#/$defs/chart_widget" },
+            { "$ref": "#/$defs/embed_widget" },
+            { "$ref": "#/$defs/workflow_graph_widget" }
+          ]
+        },
+        "position": {
+          "$ref": "#/$defs/grid_position",
+          "description": "Explicit grid positioning for grid layout pages."
+        },
+        "scope": {
+          "type": "string",
+          "description": "Named scope to apply to the zone's data query. Must exist on the resolved model.",
+          "examples": ["recent", "active", "open_tasks"]
+        },
+        "limit": {
+          "type": "integer",
+          "description": "Maximum number of records to display in this zone.",
+          "minimum": 1,
+          "examples": [5, 10]
+        },
+        "visible_when": {
+          "description": "Condition for conditional zone visibility. Supports role shortcut or full condition objects.",
+          "type": "object"
+        },
+        "scope_context": {
+          "type": "object",
+          "description": "Mapping of column names on the zone's model to dynamic references resolved from the parent record or request context. Used to scope zone data to the parent record (e.g., { employee_id: ':record.id' }).",
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string" },
+              { "type": "integer" },
+              { "type": "number" },
+              { "type": "boolean" }
+            ]
+          }
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the zone's tab label. Recommended for tab zones. Falls back to humanized zone name.",
+          "examples": ["pages.employee_detail.tabs.leave_requests", "pages.employee_detail.tabs.trainings"]
+        },
+        "default_scope": {
+          "type": "string",
+          "description": "Named scope applied before zone scope. Both are cumulative. Must exist on the resolved model.",
+          "examples": ["active", "published"]
+        },
+        "width": {
+          "type": "integer",
+          "description": "CSS grid column ratio for semantic layout (1-12 scale). Controls main/sidebar proportions.",
+          "minimum": 1,
+          "maximum": 12
+        },
+        "filters": {
+          "type": "string",
+          "description": "Filter mode for this zone. 'full' enables advanced filter builder, 'quick' enables quick search only, 'none' disables filtering. Default: 'quick' for tab zones, 'none' for others.",
+          "enum": ["full", "quick", "none"]
+        },
+        "record_click": {
+          "type": "string",
+          "description": "Row click behavior in presenter zone tables. 'navigate' does full-page navigation, 'dialog' opens record in a dialog, 'none' disables row clicking.",
+          "enum": ["navigate", "dialog", "none"],
+          "default": "navigate"
+        },
+        "submit_redirect": {
+          "type": "string",
+          "description": "Redirect behavior after successful form submission in a form zone. 'self' redirects back to the composite page (re-renders the show view with updated data).",
+          "enum": ["self"]
+        },
+        "record_source": {
+          "oneOf": [
+            {
+              "type": "object",
+              "description": "Loads a single record by ID from a URL parameter.",
+              "properties": {
+                "param": {
+                  "type": "string",
+                  "description": "URL parameter name containing the record ID to load.",
+                  "examples": ["author_id", "category_id"]
+                }
+              },
+              "required": ["param"],
+              "additionalProperties": false
+            },
+            {
+              "type": "string",
+              "description": "String shorthand: 'selection' maps to the master-detail selected record.",
+              "enum": ["selection"]
+            }
+          ]
+        },
+        "depends_on": {
+          "type": "array",
+          "description": "List of model names whose changes trigger auto-refresh of this zone via Turbo Streams.",
+          "items": { "type": "string" },
+          "examples": [["employee"], ["order", "product"]]
+        },
+        "selection": {
+          "type": "string",
+          "description": "Selection mode for master-detail split view. Only valid on sidebar presenter zones.",
+          "enum": ["single"]
+        },
+        "partial": {
+          "type": "string",
+          "description": "For type: custom — host-app partial path to render in this zone.",
+          "examples": ["employees/gantt_chart", "products/stats_sidebar"]
+        },
+        "model": {
+          "type": "string",
+          "description": "For type: custom — model name for scoped_records. Defaults to the page's primary model. Enables cross-model zones.",
+          "examples": ["note", "task"]
+        },
+        "eager": {
+          "type": "boolean",
+          "description": "For type: custom — render inline during initial page load instead of via lazy Turbo Frame. Default: false.",
+          "default": false
+        },
+        "apply_scope_context": {
+          "type": "boolean",
+          "description": "For type: custom — when true (default), builds scoped_records from scope_context. When false, only scope_context_values hash is passed.",
+          "default": true
+        }
+      },
+      "required": ["name"],
+      "additionalProperties": false
+    },
+
+    "kpi_card_widget": {
+      "type": "object",
+      "description": "KPI card widget displaying an aggregate value over a model's records, or a Prometheus metric value via value_source.",
+      "properties": {
+        "type": { "type": "string", "const": "kpi_card" },
+        "model": {
+          "type": "string",
+          "description": "Model to aggregate over. Required unless value_source is used.",
+          "examples": ["order", "task"]
+        },
+        "aggregate": {
+          "type": "string",
+          "description": "Aggregate function to compute. Required unless value_source is used.",
+          "enum": ["count", "sum", "avg", "min", "max"]
+        },
+        "aggregate_field": {
+          "type": "string",
+          "description": "Field to aggregate. Required for sum/avg/min/max. Defaults to 'id' for count.",
+          "examples": ["total_amount", "price", "score"]
+        },
+        "value_source": {
+          "type": "object",
+          "description": "Read value from a Prometheus metric instead of model aggregate. Mutually exclusive with model+aggregate.",
+          "properties": {
+            "type": {
+              "type": "string",
+              "const": "metric",
+              "description": "Source type. Currently only 'metric' (Prometheus) is supported."
+            },
+            "name": {
+              "type": "string",
+              "description": "Prometheus metric name.",
+              "examples": ["lcp_ruby_requests_total", "lcp_ruby_models_loaded"]
+            },
+            "labels": {
+              "type": "object",
+              "description": "Label filter to select a specific time series.",
+              "additionalProperties": { "type": "string" }
+            }
+          },
+          "required": ["type", "name"],
+          "additionalProperties": false
+        },
+        "format": {
+          "type": "string",
+          "description": "Display format for the aggregate value.",
+          "examples": ["currency", "number", "percent"]
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon name displayed on the KPI card.",
+          "examples": ["shopping-cart", "dollar-sign", "check-square"]
+        },
+        "link_to": {
+          "type": "string",
+          "description": "Page slug to navigate to when the KPI card is clicked.",
+          "examples": ["orders", "tasks"]
+        },
+        "label": {
+          "type": "string",
+          "description": "KPI card label (literal). DataResolver#widget_label resolves label and label_key the same way as on chart widgets; the schema lists both for consistency.",
+          "examples": ["Current headcount"]
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the KPI card label.",
+          "examples": ["lcp_ruby.dashboard.total_orders"]
+        },
+        "compare_scope": {
+          "type": "string",
+          "description": "Named scope for comparison period. Shows trend indicator (up/down/neutral + percentage).",
+          "examples": ["last_month", "previous_quarter"]
+        }
+      },
+      "required": ["type"],
+      "oneOf": [
+        {
+          "description": "Model-based KPI: aggregate over a model's records.",
+          "required": ["model", "aggregate"],
+          "not": { "required": ["value_source"] }
+        },
+        {
+          "description": "Metric-based KPI: read from a Prometheus metric.",
+          "required": ["value_source"],
+          "not": {
+            "anyOf": [
+              { "required": ["model"] },
+              { "required": ["aggregate"] },
+              { "required": ["aggregate_field"] }
+            ]
+          }
+        }
+      ],
+      "additionalProperties": false
+    },
+
+    "text_widget": {
+      "type": "object",
+      "description": "Text widget displaying translated content.",
+      "properties": {
+        "type": { "type": "string", "const": "text" },
+        "content_key": {
+          "type": "string",
+          "description": "i18n key for the text content.",
+          "examples": ["lcp_ruby.dashboard.welcome"]
+        }
+      },
+      "required": ["type", "content_key"],
+      "additionalProperties": false
+    },
+
+    "list_widget": {
+      "type": "object",
+      "description": "List widget displaying recent records from a model.",
+      "properties": {
+        "type": { "type": "string", "const": "list" },
+        "model": {
+          "type": "string",
+          "description": "Model to list records from.",
+          "examples": ["task", "order"]
+        },
+        "link_to": {
+          "type": "string",
+          "description": "Page slug for the 'view all' link.",
+          "examples": ["tasks", "orders"]
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the list widget header.",
+          "examples": ["lcp_ruby.dashboard.recent_tasks"]
+        }
+      },
+      "required": ["type", "model"],
+      "additionalProperties": false
+    },
+
+    "chart_series_item": {
+      "type": "object",
+      "description": "One series in a multi-series chart widget. Inherits group_by/group_period/aggregate/aggregate_field from the chart-level keys unless overridden.",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Legend label for this series (literal). Mutually-compatible with name_key (key wins if both present)."
+        },
+        "name_key": {
+          "type": "string",
+          "description": "i18n key for the legend label."
+        },
+        "color": {
+          "type": "string",
+          "description": "CSS color (hex, named, rgb(), hsl(), var(--…)). Overrides chart-level colors[index] and palette default."
+        },
+        "aggregate": {
+          "type": "string",
+          "enum": ["count", "sum", "avg", "min", "max"],
+          "description": "Per-series aggregate. Inherits from chart-level when omitted."
+        },
+        "aggregate_field": {
+          "type": "string",
+          "description": "Field to aggregate. Required when this series' resolved aggregate is not count."
+        },
+        "group_by": {
+          "type": "string",
+          "description": "Field on the model to group by. Inherits from chart-level when omitted."
+        },
+        "group_period": {
+          "type": "string",
+          "enum": ["day", "week", "month", "quarter", "year"],
+          "description": "Date truncation period. Inherits from chart-level when omitted."
+        },
+        "scope": {
+          "type": "string",
+          "description": "Named scope on the model. Applied cumulatively with chart-level scope."
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "chart_widget": {
+      "type": "object",
+      "description": "Chart widget displaying grouped data as a visual chart. Requires the 'chartkick' gem.",
+      "properties": {
+        "type": { "type": "string", "const": "chart" },
+        "chart_type": {
+          "type": "string",
+          "enum": ["line", "bar", "column", "pie", "donut", "area"]
+        },
+        "model": {
+          "type": "string",
+          "description": "Model to query for chart data.",
+          "examples": ["order", "task"]
+        },
+        "group_by": {
+          "type": "string",
+          "description": "Field to group records by.",
+          "examples": ["status", "created_at", "category"]
+        },
+        "group_period": {
+          "type": "string",
+          "description": "Date truncation period for date fields.",
+          "enum": ["day", "week", "month", "quarter", "year"]
+        },
+        "aggregate": {
+          "type": "string",
+          "description": "Aggregate function to compute per group.",
+          "enum": ["count", "sum", "avg", "min", "max"]
+        },
+        "aggregate_field": {
+          "type": "string",
+          "description": "Field to aggregate. Required for sum/avg/min/max.",
+          "examples": ["total_amount", "price"]
+        },
+        "scope": {
+          "type": "string",
+          "description": "Chart-widget-level named scope on model. Applied cumulatively with each series' own scope."
+        },
+        "link_to": {
+          "type": "string",
+          "description": "Page slug for the 'view all' link.",
+          "examples": ["orders", "tasks"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Chart title (literal). Counterpart to label_key."
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the chart title.",
+          "examples": ["lcp_ruby.dashboard.orders_by_month"]
+        },
+        "series": {
+          "type": "array",
+          "minItems": 1,
+          "items": { "$ref": "#/$defs/chart_series_item" },
+          "description": "Multi-series array. When absent, top-level group_by/aggregate define an implicit single series."
+        },
+        "stacked": {
+          "type": "boolean",
+          "description": "Stack series on Y axis. Legal for column/bar/line/area; hard error for pie/donut."
+        },
+        "legend": {
+          "oneOf": [
+            { "type": "boolean" },
+            { "type": "string", "enum": ["auto", "top", "bottom", "left", "right"] }
+          ],
+          "description": "Legend visibility/position. 'auto' shows for multi-series and all pie/donut; hides for single-series non-pie."
+        },
+        "colors": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Index-keyed series colors (column/bar/line/area) or per-slice colors (pie/donut)."
+        },
+        "min": {
+          "type": "number",
+          "description": "Y axis minimum."
+        },
+        "max": {
+          "type": "number",
+          "description": "Y axis maximum."
+        },
+        "xtitle": {
+          "type": "string",
+          "description": "X axis title (literal)."
+        },
+        "xtitle_key": {
+          "type": "string",
+          "description": "i18n key for X axis title."
+        },
+        "ytitle": {
+          "type": "string",
+          "description": "Y axis title (literal)."
+        },
+        "ytitle_key": {
+          "type": "string",
+          "description": "i18n key for Y axis title."
+        },
+        "empty": {
+          "type": "string",
+          "description": "Message shown when ALL series are empty (literal)."
+        },
+        "empty_key": {
+          "type": "string",
+          "description": "i18n key for empty-state message."
+        },
+        "prefix": {
+          "type": "string",
+          "description": "Value prefix (e.g., '€')."
+        },
+        "suffix": {
+          "type": "string",
+          "description": "Value suffix (e.g., '%')."
+        },
+        "precision": {
+          "type": "integer",
+          "description": "Decimal places for values."
+        },
+        "thousands": {
+          "type": "string",
+          "description": "Thousands separator (e.g., ' ' for CZ locale)."
+        },
+        "points": {
+          "type": "boolean",
+          "description": "Show line/area dot markers."
+        },
+        "curve": {
+          "type": "boolean",
+          "description": "Line smoothing for line/area."
+        },
+        "discrete": {
+          "type": "boolean",
+          "description": "Treat X axis as categorical (not numeric)."
+        },
+        "fill_zeros": {
+          "type": "boolean",
+          "description": "When set with group_period (day/month/quarter/year), pads each series with 0 for every missing period between min and max keys. Default false — sparse data stays sparse. Use it to keep stacked-area / line charts visually continuous when some series have gaps. Mixed per-series group_period values disable the fill."
+        },
+        "sort": {
+          "type": "string",
+          "enum": ["asc", "desc", "none", "value_asc", "value_desc"],
+          "description": "Category sort order."
+        },
+        "download": {
+          "type": "boolean",
+          "description": "Chartkick PNG download button."
+        },
+        "height": {
+          "type": "string",
+          "description": "CSS height (e.g., '320px')."
+        },
+        "library": {
+          "type": "object",
+          "description": "Raw Chart.js options passthrough. Deep-merged over platform defaults; last-word.",
+          "additionalProperties": true
+        }
+      },
+      "required": ["type", "chart_type", "model", "group_by", "aggregate"],
+      "additionalProperties": false
+    },
+
+    "embed_widget": {
+      "type": "object",
+      "description": "Embed widget displaying an external BI tool or web page via iframe.",
+      "properties": {
+        "type": { "type": "string", "const": "embed" },
+        "provider": {
+          "type": "string",
+          "description": "Registered embed provider name (e.g., 'metabase', 'grafana').",
+          "examples": ["metabase", "grafana"]
+        },
+        "resource_type": {
+          "type": "string",
+          "description": "Provider-specific resource type.",
+          "examples": ["dashboard", "question", "panel"]
+        },
+        "resource_id": {
+          "description": "Provider-specific resource identifier.",
+          "oneOf": [
+            { "type": "string" },
+            { "type": "integer" }
+          ]
+        },
+        "params": {
+          "type": "object",
+          "description": "Additional parameters passed to the embed provider.",
+          "additionalProperties": true
+        },
+        "height": {
+          "type": "string",
+          "description": "CSS height for the iframe.",
+          "default": "400px",
+          "examples": ["400px", "600px", "80vh"]
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the embed widget label."
+        }
+      },
+      "required": ["type", "provider", "resource_type", "resource_id"],
+      "additionalProperties": false
+    },
+
+    "workflow_graph_widget": {
+      "type": "object",
+      "description": "Workflow graph widget displaying a Mermaid.js state diagram from the workflow definition.",
+      "properties": {
+        "type": { "type": "string", "const": "workflow_graph" },
+        "model": {
+          "type": "string",
+          "description": "Model name to resolve the workflow definition. Defaults to the page model when omitted.",
+          "examples": ["purchase_order", "candidate"]
+        },
+        "direction": {
+          "type": "string",
+          "description": "Mermaid diagram direction.",
+          "enum": ["LR", "TD"],
+          "default": "LR"
+        },
+        "show_transition_labels": {
+          "type": "boolean",
+          "description": "Show transition names on edges.",
+          "default": true
+        },
+        "show_roles": {
+          "type": "boolean",
+          "description": "Show allowed roles on transition edges.",
+          "default": false
+        },
+        "show_guards": {
+          "type": "boolean",
+          "description": "Show guard indicator on guarded transitions.",
+          "default": false
+        },
+        "show_audit_trail": {
+          "type": "boolean",
+          "description": "Highlight the path this record actually took through the workflow.",
+          "default": false
+        },
+        "highlight_available": {
+          "type": "boolean",
+          "description": "Highlight transitions available to the current user.",
+          "default": false
+        },
+        "collapse_universal": {
+          "type": "boolean",
+          "description": "Collapse universal (from: *) transitions into a single node.",
+          "default": true
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the widget label."
+        }
+      },
+      "required": ["type"],
+      "additionalProperties": false
+    },
+
+    "filter_form_field": {
+      "type": "object",
+      "description": "A single filter form field. Uses the same shape as a presenter form field (input_type + input_options). Supported input_types are checked at boot against ALLOWED_FILTER_INPUT_TYPES (filter UI subset); inappropriate types (hidden, file_upload, tree_select, array_input, field_picker, formatting_options, import_mapper) are boot-rejected via FilterFormValidator.",
+      "properties": {
+        "field": {
+          "type": "string",
+          "description": "Field name on the page's primary model. Becomes the URL key under page_filter[<field>] (or page_filter[<field>][] when input_options.multi: true).",
+          "examples": ["bu_code", "division_id", "status", "hired_at"]
+        },
+        "input_type": {
+          "type": "string",
+          "description": "Form input type. v1 allowlist enforced at boot via FilterFormValidator::ALLOWED_FILTER_INPUT_TYPES.",
+          "examples": ["association_select", "select", "multi_select", "date_range", "boolean", "number"]
+        },
+        "model": {
+          "type": "string",
+          "description": "Association target model for association_select / multi_select input_types.",
+          "examples": ["business_unit", "division", "company"]
+        },
+        "input_options": {
+          "type": "object",
+          "description": "Per-field rendering options. Common keys: multi (boolean), depends_on (cascade), include_blank, values (for select), default. Full reference in docs/reference/forms.md.",
+          "additionalProperties": true,
+          "properties": {
+            "primary_key": {
+              "description": "Column on the association target whose value is posted as the dropdown's option value (and used in cascade depends_on URLs). Constrained to a column-name shape to keep YAML-supplied values from leaking into Rails reflection paths as arbitrary strings.",
+              "type": "string",
+              "pattern": "^[a-zA-Z_][a-zA-Z0-9_]*$",
+              "examples": ["vema_code", "uuid"]
+            }
+          }
+        },
+        "default": {
+          "description": "Default value when no URL parameter is present. Must be an Array when input_options.multi: true."
+        },
+        "label": {
+          "type": "string",
+          "description": "Field label (literal). Same precedence as chart widgets — `label_key` wins when present, `label` is its default, humanized field name is the final fallback. See CLAUDE.md § i18n.",
+          "examples": ["Business Unit", "Termination date"]
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the field label."
+        },
+        "placeholder": {
+          "type": "string",
+          "description": "Placeholder text for text-like inputs."
+        }
+      },
+      "required": ["field", "input_type"],
+      "additionalProperties": false
+    },
+
+    "scope_filter": {
+      "type": "object",
+      "description": "A single scope filter declaration. Each entry maps UI options to named ActiveRecord scopes on the page model. Single-selection only in v1 (no multi:, no depends_on:).",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Unique name within the page. Becomes URL key under scope_filter[<name>].",
+          "examples": ["lifecycle", "visibility"]
+        },
+        "label": {
+          "type": "string",
+          "description": "Widget label (literal). Same precedence as filter_form fields — see CLAUDE.md § i18n."
+        },
+        "label_key": {
+          "type": "string",
+          "description": "i18n key for the widget label."
+        },
+        "scopes": {
+          "type": "object",
+          "description": "Map of scope key (must be a named AR scope on the page model) to either a literal label string or an entry hash with label/label_key.",
+          "additionalProperties": {
+            "oneOf": [
+              { "type": "string" },
+              {
+                "type": "object",
+                "properties": {
+                  "label":     { "type": "string" },
+                  "label_key": { "type": "string" }
+                },
+                "additionalProperties": false
+              }
+            ]
+          }
+        },
+        "default": {
+          "type": "string",
+          "description": "Which scope key is selected on first load. Must be one of the declared scopes: keys, or omitted for no default."
+        },
+        "widget": {
+          "type": "string",
+          "description": "Render style for the scope filter widget.",
+          "enum": ["select", "radio", "button_group"],
+          "default": "select"
+        }
+      },
+      "required": ["name", "scopes"],
+      "additionalProperties": false
+    },
+
+    "grid_position": {
+      "type": "object",
+      "description": "CSS grid positioning for grid layout pages. Uses a 12-column grid.",
+      "properties": {
+        "row": {
+          "type": "integer",
+          "description": "Starting grid row.",
+          "minimum": 1
+        },
+        "col": {
+          "type": "integer",
+          "description": "Starting grid column (1-12).",
+          "minimum": 1
+        },
+        "width": {
+          "type": "integer",
+          "description": "Number of columns to span.",
+          "minimum": 1
+        },
+        "height": {
+          "type": "integer",
+          "description": "Number of rows to span.",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+
+    "role_condition": {
+      "type": "object",
+      "description": "Simple role-based visibility condition. Zone is visible only to users with the specified role(s).",
+      "properties": {
+        "role": {
+          "oneOf": [
+            { "type": "string" },
+            {
+              "type": "array",
+              "items": { "type": "string" }
+            }
+          ],
+          "description": "Role name or array of role names."
+        }
+      },
+      "required": ["role"],
+      "additionalProperties": false
+    },
+
+    "condition_object": {
+      "type": "object",
+      "description": "Full condition object supporting field, service, compound (all/any/not), and collection conditions. See condition operators reference for details.",
+      "properties": {
+        "field": { "type": "string" },
+        "operator": { "type": "string" },
+        "value": {},
+        "all": {
+          "type": "array",
+          "items": {}
+        },
+        "any": {
+          "type": "array",
+          "items": {}
+        },
+        "not": {
+          "type": "object"
+        },
+        "service": { "type": "string" },
+        "collection": { "type": "string" },
+        "quantifier": { "type": "string" },
+        "condition": { "type": "object" }
+      }
+    }
+  }
+}