Validation

TREVL ships with a JSON Schema (draft 2020-12) that formally defines the structure of TREVL YAML documents. Use it to validate components before rendering — in your editor, CI pipeline, or from an AI agent.

Ruby gem

The trevl gem includes a built-in validator:

require "trevl"

result = Trevl.validate(<<~YAML)
  components:
  - id: salary_chart
    type: chart
    api: myapi
    highchartsData:
      series:
      - data:
          y: "$salary.data.value"
YAML

result.valid?   # => true
result.errors   # => []

Error feedback

When validation fails, errors include the component ID and a human-readable description:

result = Trevl.validate(<<~YAML)
  components:
  - id: broken_chart
    type: chart
YAML

result.valid?   # => false
result.errors
# => ["[broken_chart] Missing required field(s): api, highchartsData (at )"]

Single component validation

Trevl::Validator.validate_component({
  "id" => "c1",
  "type" => "chart",
  "api" => "myapi",
  "highchartsData" => {"series" => [{"data" => {"y" => "$ep.data.val"}}]}
})
# => #<Result valid?=true, errors=[]>

JSON Schema files

The schema files are bundled with the gem and can also be used standalone:

VS Code integration

Add to your .vscode/settings.json to get autocompletion and validation for .trevl.yml files:

{
  "yaml.schemas": {
    "./node_modules/trevl/lib/trevl/schema/document.json": "*.trevl.yml"
  }
}

Or reference the schema directly from the TREVL gem path.

What gets validated

Required fields

Every component must have id and type. Additional requirements depend on the type:

Type enum

type: chart | score | table | text | filter

Computed fields

computed:
- name: fieldName     # required
  code: 'expression'  # required
  arguments:          # optional
    arg: "$ref"

Chart types

highchartsData:
  chart:
    type: bar | column | line | area | pie | scatter | spline | ...

Filter operators

filters:
- member: cube.field
  operator: equals | notEquals | gt | gte | lt | lte | afterDate | beforeDate | set | notSet | contains | notContains

For AI agents

The JSON Schema is designed to be useful for LLMs:

1. Self-correction — generate TREVL, validate, fix errors, repeat
2. Schema-as-prompt — include the schema in system prompts for precise constraints
3. Structured errors — error messages tell you exactly what’s wrong and where

# AI agent workflow
yaml = agent.generate_trevl(prompt)
result = Trevl.validate(yaml)
until result.valid?
  yaml = agent.fix_trevl(yaml, errors: result.errors)
  result = Trevl.validate(yaml)
end
Trevl.render(yaml)