Use this guide when you need to implement or troubleshoot calculated fields and validation behavior for data sources.

This guide is based on the platform normalization and evaluation pipeline, including:

• docs/context/architecture/expressions-formulas-validation.md
• docs/context/architecture/post-readings-normalization.md

Know the main schema fields

At schema level, a metric can define fields such as:

• valueExpression
• formula
• reverseFormula
• reverseDenormalizeFormula
• validationFormula

These values travel with the schema and are included in normalization and downstream evaluation.

Understand the runtime flow

The high-level flow is:

1. A reading is posted through the public readings API.
2. The normalization path loads meter schema and metric metadata.
3. Values are normalized by data type and schema order.
4. Expression and formula metadata is attached to the meter configuration payload.
5. Validation rules run before insertion handoff.
6. Downstream evaluation uses the configured expressions and helper functions.

Use validation rules carefully

Validation formulas support checks such as:

• maxValue
• minValue
• minLength
• maxLength
• required
• allowedValues
• maxChangeFromPrevious

These rules are enforced during normalization, not only at UI level.

Plan for expression context

Evaluation context can include:

• current metric values
• previous and next metrics
• relative metrics
• helper functions such as metric lookup, date helpers, scaling helpers, and spreadsheet-like functions

If you depend on cross-metric or cross-device logic, confirm the required context is available before you write the formula.

Watch the common failure cases

Common reasons expressions fail in practice:

• field references do not match the actual schema
• validation rules do not fit the metric data type
• a formula assumes a value exists before normalization has produced it
• reverse formulas drift from the UI conversion logic
• maxChangeFromPrevious behavior depends on previous-reading retrieval and time range assumptions

Recommended implementation approach

1. Start with the simplest possible expression.
2. Validate the field type and schema order first.
3. Add validation only after the base calculation works.
4. Test against real readings, especially for previous-value checks.
5. Recheck behavior after any schema rename or metric reorder.

Read next

• Open Readings API for the ingestion entry points.
• Open Data Sources and Devices for broader device-related setup context.