> For the complete documentation index, see [llms.txt](https://docs.durohub.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.durohub.com/library-configuration/authoring-custom-validations.md).

# 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 }`.

```javascript
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.

```javascript
item.attributes['Manufacturer']     // "Acme Co" or null
item.attributes['Mass']             // { value: "25", unit: "g" } or null
item.attributes['Cost']             // { value: 42.50, unit: "USD" } or null
item.attributes['Support Phone']    // "+1-555-0123" or null
```

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.

```javascript
item.category.attributes.forEach(attr => {
  console.info(`${attr.name} (${attr.type}): ${item.attributes[attr.name]}`);
});
```

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

```javascript
exports.validate = async function(data) {
  const missing = data.items.filter(item => !item.attributes['Manufacturer']);

  if (missing.length > 0) {
    const names = missing.map(item => item.name).join(', ');
    return {
      valid: false,
      message: `${missing.length} component(s) missing Manufacturer: ${names}`
    };
  }

  return { valid: true, message: 'All components have 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

```javascript
exports.validate = async function(data) {
  const problems = [];

  for (const item of data.items) {
    const cost = item.attributes['Cost'];
    if (cost && cost.value > 10000) {
      problems.push(`${item.name} has cost $${cost.value} (exceeds $10,000)`);
    }
  }

  if (problems.length > 0) {
    return { valid: false, message: problems.join('; ') };
  }
  return { valid: true, message: 'All costs within threshold' };
};
```

### Checking Category-Specific Rules

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

```javascript
exports.validate = async function(data) {
  for (const item of data.items) {
    if (item.category.name === 'Capacitor' && !item.attributes['Capacitance']) {
      return {
        valid: false,
        message: `Capacitor "${item.name}" is missing the Capacitance attribute`
      };
    }
  }
  return { valid: true, message: 'Category-specific checks passed' };
};
```

### Validating Approval Stages

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

```javascript
exports.validate = async function(data) {
  for (const stage of data.change_order.stages || []) {
    if (!stage.reviewers || stage.reviewers.length < 2) {
      return {
        valid: false,
        message: `Stage "${stage.name}" needs at least 2 reviewers`
      };
    }
  }
  return { valid: true, message: 'All stages have sufficient reviewers' };
};
```

### Enforcing Naming Conventions

```javascript
exports.validate = async function(data) {
  const pattern = /^ECO-\d{4}-\d{2,3}$/;
  if (!pattern.test(data.change_order.name)) {
    return {
      valid: false,
      message: `Name "${data.change_order.name}" must match pattern ECO-YYYY-NNN`
    };
  }
  return { valid: true, message: 'Name format is valid' };
};
```

### Working with Measured Values

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

```javascript
exports.validate = async function(data) {
  for (const item of data.items) {
    const mass = item.attributes['Mass'];
    if (mass && parseFloat(mass.value) > 1000) {
      console.warn(`${item.name} exceeds 1kg: ${mass.value}${mass.unit}`);
      return {
        valid: false,
        message: `${item.name} mass is ${mass.value}${mass.unit} — exceeds 1kg limit`
      };
    }
  }
  return { valid: true, message: 'All components within mass limits' };
};
```

## 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.

```javascript
console.info(`Checking ${data.items.length} components`);
console.info(`Change order: ${data.change_order.name}`);

for (const item of data.items) {
  console.log(`Processing ${item.name} (${item.category.name})`);
}
```

Logs are accessible via the GraphQL API on each validation result's `logs` field — see [Change Order Validations](https://docs.durohub.com/library-configuration/change-order-validations.md) 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

```
[display text](protocol:type/id)
```

### Supported Link Types

| 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:

```javascript
function componentLink(item) {
  const display = item.name || item.eid || item.itemId;
  return `[${display}](item:component/${item.itemId})`;
}

// In your validation:
console.error(`${componentLink(item)} is missing a description`);
```

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.

{% hint style="info" %}
If you manage validations through the [library-validations-template](https://github.com/duronext/library-validations-template), the mode is set in `validations.yaml` via the `onFailure` field.
{% endhint %}

## Execution Environment

{% hint style="info" %}
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.
{% endhint %}

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

```graphql
mutation CreateValidation($input: CreateValidationRuleInput!) {
  validations {
    create(input: $input) {
      id
      name
    }
  }
}
```

Variables:

```json
{
  "input": {
    "name": "Block: Missing Manufacturer",
    "description": "Rejects change orders where any component is missing a Manufacturer attribute",
    "code": "exports.validate = async function(data) {\n  const missing = data.items.filter(item => !item.attributes['Manufacturer']);\n  if (missing.length > 0) {\n    return { valid: false, message: missing.map(i => i.name).join(', ') + ' missing Manufacturer' };\n  }\n  return { valid: true, message: 'All components have a manufacturer' };\n};",
    "type": "custom",
    "onFailure": "ERROR",
    "isActive": true,
    "version": "1.0.0"
  }
}
```

| 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

```graphql
mutation UpdateValidation($id: ID!, $input: UpdateValidationRuleInput!) {
  validations {
    update(id: $id, input: $input) {
      id
      name
      version
    }
  }
}
```

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

### Listing Validation Rules

```graphql
query ListValidations {
  validations {
    list {
      edges {
        node {
          id
          name
          description
          code
          onFailure
          isActive
          version
        }
      }
    }
  }
}
```

### Testing a Validation Rule

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

```graphql
mutation TestValidation($id: ID!, $changeOrderId: ID!) {
  validations {
    test(id: $id, changeOrderId: $changeOrderId) {
      state
      errorMessage
      logs {
        all {
          message
          type
        }
      }
    }
  }
}
```

### Deleting a Validation Rule

```graphql
mutation DeleteValidation($id: ID!) {
  validations {
    delete(id: $id)
  }
}
```

{% hint style="warning" %}
Deletion is permanent. If you want to temporarily disable a rule, update `isActive` to `false` instead.
{% endhint %}

## Source-Controlled Validations

For teams that want to manage validations in version control, Duro provides the [library-validations-template](https://github.com/duronext/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."

```javascript
// Helpful
`3 components missing Manufacturer: CAP-001, RES-042, IC-100`

// Not helpful
`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.

```javascript
// Defensive
const manufacturer = item.attributes['Manufacturer'];
if (manufacturer && manufacturer.toLowerCase() === 'acme co') { ... }

// Fragile — throws if attribute is null
if (item.attributes['Manufacturer'].toLowerCase() === 'acme co') { ... }
```

**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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.durohub.com/library-configuration/authoring-custom-validations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
