For the complete documentation index, see llms.txt. This page is also available as Markdown.

Authoring Custom Validations

Custom validations are JavaScript functions that run during change order validation. They receive the full change order context — items, attributes, approval stages, custom fields — and return a pass/fail result with a message. You write the logic; Duro handles execution in a secure sandbox.

How It Works

When a change order is validated, Duro sends each custom validation rule to an isolated execution environment. Your code receives a data object containing the change order and its items, runs your logic, and returns a result. Duro waits up to 30 seconds for the result; a rule that takes longer is recorded as a FAIL with Failed to execute validation: timeout of 30000ms exceeded.

Every active custom rule in the library runs on every change order in that library.

The basic contract is simple: export a validate function that accepts the data payload and returns { valid, message }.

exports.validate = async function(data) {
  // data.change_order — the change order metadata
  // data.items — the components in the change order

  // Your logic here...

  return {
    valid: true,      // or false
    message: 'Human-readable result'
  };
};

The Validation Payload

Your validation function receives a single data argument with two top-level properties:

  • data.change_order — the change order metadata, approval stages, custom fields

  • data.items — the components in the change order, with full attribute data

Change Order Fields

Field
Type
Description

id

string

UUID of the change order

name

string

Change order name/title

description

string

Description text (can be null)

status

string

draft, open, resolved, or closed

resolution

string

pending, approved, rejected, or withdrawn

libraryId

string

UUID of the change order's library

isValid

boolean

The change order's current validation verdict

createdAt / updatedAt

string

Timestamps

createdBy

object

{ id, name, primaryEmail } of the creator

updatedBy

object

{ id, name, primaryEmail } of the last editor

contents

array

Custom form fields: id, name, label, type, values, listOptions, multipleSelect, isRequired, placeholder, description, groupName, order. Omitted when the change order has no custom fields

stages

array

Approval stages: id, name, order, decisionState, decisionMethod, decisionMinimumCount, minReviewers, reviewers, notifyList. Omitted when the change order has no stages

The payload does not include the change order's type (coType). Each contents entry also carries min, max and pattern keys, which are always empty because template field validations are not stored.

Item Fields

Each entry in data.items combines the change order item data with its component information:

Field
Type
Description

id

string

Change order item UUID

itemId

string

Component UUID

itemVersion

number

Component version recorded on the change order item

name

string

Component name

eid

string

Component's external identifier

description

string

Component description

type

string

Category type, such as PART or ASSEMBLY

categoryId

string

Category UUID

category

object

{ id, name, attributes } — category info with attribute definitions

statusId

string

Status UUID

status

object

{ id, name, mapsTo, color } — the component's current status

version

number

Component version number

revisionValue

string

The component's current revision (e.g., "A", "B")

revisionType

string

The component's revision scheme

state

string

RELEASED or MODIFIED

releasedAt / createdAt / updatedAt

string

Timestamps

attributes

object

Human-readable attribute values keyed by name

attributeValues

object

Raw attribute values keyed by UUID (legacy)

status and revisionValue are the component's live values. The payload does not include the status or revision the change order proposes.

Component Attributes

Each item carries attribute data in two forms.

item.attributes — Human-readable, keyed by name. This is what you'll use most of the time.

All attributes assigned to the item's category appear in this map. Unset attributes are null — so you can distinguish "not set" from "attribute doesn't exist on this category."

item.category.attributes — Attribute definitions for the category. Useful when you need to know what attributes exist, their types, or iterate programmatically.

Each definition includes: id, name, type, source, sourceKey, unit.

item.attributeValues — Raw storage format with UUID keys. Kept for backward compatibility. You shouldn't need this unless you're working with attribute IDs directly.

Value Shapes

Attribute Type

Example item.attributes['Name']

STRING, URL, EMAIL, PHONE, DATE, BOOLEAN

"Acme Co" (unwrapped primitive)

NUMBER (simple)

42 (unwrapped number)

NUMBER (measured -- mass, length)

{ value: "25", unit: "g" }

NUMBER (currency)

{ value: 42.50, unit: "USD" }

LIST

"Each" (unwrapped string)

ITEM_LINK

"3f2a…" (the linked component's UUID)

Unset, or a value that could not be converted

null

Writing Your First Validation

Create a .js file that exports a validate function returning an object with valid (boolean) and message (string). The function may be async or synchronous; its result is awaited either way.

  • valid is converted to a boolean, so any truthy value passes.

  • Returning a bare true or false is accepted, with an empty message.

  • Any other return value is recorded as a failure: Validation returned unexpected type: <type>.

  • An error thrown inside validate is recorded as a failure: Exception: <error message>.

Example: Block Components Missing a Manufacturer

That's the whole file. No imports, no boilerplate, no class wiring. Duro loads it, calls exports.validate, and records the result.

Common Patterns

Checking Attribute Values

Checking Category-Specific Rules

Use item.category.name to apply rules only to certain component types:

Validating Approval Stages

The data.change_order.stages array gives you full visibility into the approval workflow:

Enforcing Naming Conventions

Working with Measured Values

Measured attributes (mass, length, etc.) return { value, unit } rather than a bare number. Parse accordingly:

Logging

All console methods are captured and visible in the validation results:

  • console.info() — informational messages about execution

  • console.log() — general-purpose logging

  • console.warn() — warnings about potential issues

  • console.error() — error details

Use logging liberally. It costs nothing and makes debugging much easier when a validation fails unexpectedly.

Logs are accessible via the GraphQL API on each validation result's logs field — see Change Order Validations for the query structure.

Linking to Entities

Duro supports a markdown-inspired syntax for creating clickable links in validation messages and logs. When you reference a component or change order, wrap it in a link so users can click straight through to it in the Duro UI.

Syntax

Entity
Syntax
Example

Component

[text](item:component/id)

[CAP-001](item:component/abc-123)

Assembly

[text](item:assembly/id)

[Main Board](item:assembly/xyz-789)

Change Order

[text](co:changeorder/id)

[ECO-2024-001](co:changeorder/co-123)

PCBA

[text](item:pcba/id)

[Power Board](item:pcba/pcb-321)

User

[text](user:profile/id)

[Jane Smith](user:profile/user-456)

Helper Function

A small helper keeps link construction consistent:

Links degrade gracefully — if the UI can't parse them, users still see the display text.

Error vs Warning Mode

The onFailure setting controls what happens when your validation returns { valid: false }:

Mode
Behavior

error

Blocks the change order from proceeding (hard stop)

warning

Alerts reviewers but does not block progress

This is a configuration setting, not something you control in JavaScript. Your code is identical either way — you return { valid: false, message } and the platform decides whether to block or warn based on the mode.

If you manage validations through the library-validations-template, the mode is set in validations.yaml via the onFailure field.

Execution Environment

Validations run in an isolated JavaScript sandbox with a 32 MB memory limit. The sandbox sets no execution time limit of its own; Duro stops waiting for a result after 30 seconds. All console output is captured.

The sandbox provides a global fetch(url, options) that makes HTTP requests to any URL. The response has ok, status, statusText, headers, and async json() and text() methods. Each request is logged as Fetch request to: <url>, and a failed request throws Fetch failed: <message>.

Your code cannot:

  • Read or write files

  • Import modules, including Node.js built-ins (require is not available)

  • Access environment variables or process

console, fetch and exports are predefined globals. Declaring any of them yourself at the top level (for example const fetch = …) fails to compile.

Managing Validations via the API

You can create, update, list, and test custom validation rules through the GraphQL API. Like every library-scoped call, send x-library naming your API key's library; create and list also accept an optional library argument.

Creating a Validation Rule

Variables:

Field
Type
Description

name

string

Display name for the validation rule

description

string

What the rule checks

code

string

The JavaScript source code

type

string

"custom" (the default). A rule with any other type never runs

onFailure

string

"ERROR" (blocks) or "WARNING" (non-blocking)

isActive

boolean

Whether the rule runs during validation. Defaults to true

version

string

Semantic version for tracking changes. Defaults to "1.0.0"

Updating a Validation Rule

You can update any combination of name, code, description, onFailure, isActive, and version. Only type cannot be changed after creation.

Listing Validation Rules

Testing a Validation Rule

Run one rule against an existing change order without recording a validation run:

Deleting a Validation Rule

Source-Controlled Validations

For teams that want to manage validations in version control, Duro provides the library-validations-template — a public GitHub repository to copy for your library. It gives you:

  • A validations.yaml file defining each rule's name, description, version, active state, and failure mode

  • A validations/ directory for your JavaScript files

  • A sync script that pushes your local definitions to the Duro API via the mutations above

  • A GitHub Actions workflow that syncs automatically on push to main

Copy it into a new private repository in your own GitHub organization: clone it and push to an empty private repository rather than forking, because a fork of a public repository stays public and would publish your rules' code. Add your API key as a GitHub secret (DURO_LIBRARY_API_KEY) and make sure Actions are enabled for the repository; from then on, every push to main syncs your validation rules to your Duro library. The sync is additive — it creates new rules, updates changed ones, and deactivates rules removed from the config (it never deletes).

This approach lets you review validation changes in pull requests, track history in git, and deploy consistently across libraries. The repository also includes a CLAUDE.md file that enables AI-assisted validation authoring — describe what you want in natural language and Claude Code generates the JavaScript and YAML config.

Best Practices

Keep validations focused. One validation, one concern. A rule that checks manufacturer data and also enforces naming conventions should be two separate validations. Smaller validations are easier to debug, toggle, and explain to users.

Provide clear messages. Your message is the first thing a user sees when something fails. Tell them what's wrong and which components are affected — not just "validation failed."

Use component links. When referencing specific components in messages or logs, use the [name](item:component/id) syntax so users can click through to the problem.

Handle null and undefined gracefully. Attributes can be null (unset), items can have missing fields, and the stages array can be empty. Defensive checks prevent runtime errors that surface as cryptic failures.

Log diagnostic info. Drop console.info calls at the start of your validation to record how many items you're checking, which categories are present, and any thresholds you're using. When something goes wrong, the logs tell the story.

Return a message on success too. A passing message like "All 12 components have a manufacturer" gives users confidence that the check actually ran and inspected their data.

Last updated

Was this helpful?