ebuilder-sql-query-input-validation

name	ebuilder-sql-query-input-validation
description	Input and validation playbook for query-* definitions in configs/sql.*.yml. USE FOR: inputParams typing, validation rules, checksBefore/checksAfter guards, and deterministic guard logic. DO NOT USE FOR: post-processing pipeline or output field shaping.

eBuilder Query Input and Validation

Purpose

Use this skill when defining and validating inputs for query-* entries.

Scope

• Input schema in inputParams.
• Validation via rules.
• Runtime guards with checksBefore and checksAfter.

Input Type Guidance

Allowed input parameter types include:

• int, decimal, number, string, bool, dateTime, datetime, array, object, uuid

Use nested properties for objects and items for arrays.

Validation Rules

Use rules per parameter for constraints such as:

• required, nullable, allowEmpty
• enum, enumFromConstant, caseInsensitive
• min, max, dateOnly, useLocalTimeZone

For primitive arrays, define item-level constraints in items.rules.

• allowEmpty in items.rules controls whether each array item can be empty.
• min and max in items.rules control per-item numeric bounds.
• min and max in parent rules still apply to the parameter itself.

Guard Patterns

Use checksBefore to reject invalid requests early. Use checksAfter to assert expected result-state invariants.

Preferred condition format:

• if: ${{ ... }} with elseThrowErrorCode and optional logs.

Example

query:
  query-items-by-status:
    datasource: main
    inputParams:
      status:
        type: string
        rules:
          - required: true
          - enum:
              - active
              - archived
    responseType: list
    checksBefore:
      - if: ${{ ${status} !== undefined }}
        elseThrowErrorCode: 400
    command: |
      SELECT id AS "id", title AS "title", status AS "status"
      FROM items
      WHERE status = ${status}

Primitive Array Item Rules Example

query:
  query-filter-by-scores:
    datasource: main
    inputParams:
      scores:
        type: array
        items:
          type: number
          rules:
            - min: 0
            - max: 100
      tags:
        type: array
        items:
          type: string
          rules:
            - allowEmpty: false
    checksBefore:
      - if: ${{ Array.isArray(${scores}) && ${scores}.length > 0 }}
        elseThrowErrorCode: 400
    responseType: list
    command: |
      SELECT id AS "id", score AS "score"
      FROM items
      WHERE $EB_IN_ARRAY_ARG(score, ${scores})

Deterministic Checks

1. Every required input has a corresponding schema entry.
2. Rules match parameter type semantics.
3. Array item constraints are defined under items.rules when needed.
4. Guard expressions are deterministic and side-effect free.
5. Deprecated guard forms (param/op/value) are not used.
6. Error codes in guards are intentional and documented.