> 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/change-order-workflow-reference.md).

# Change Order Workflow Reference

## Overview

This document provides a complete reference for the Change Order Workflow Template YAML specification. The schema defines the structure and constraints for change order approval workflows in the Duro PLM system.

## Schema Information

The template format is **versioned**, and each format version is published as its own JSON Schema. A template is not versioned itself — it *declares* which schema version it conforms to through its root `version` field, and the API validates it against that version.

| `version` | Schema                                                                         | What it covers                                                                                                                                                                                                                                                                            |
| --------- | ------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"1.0"`   | [`schema-1.0.json`](https://durohub.com/configs/change-orders/schema-1.0.json) | The base format: `description`, `schema_type`, `details`, `validations`, `stages`. `co_types` and `default_co_type` are **not** part of this schema and are rejected.                                                                                                                     |
| `"1.1"`   | [`schema-1.1.json`](https://durohub.com/configs/change-orders/schema-1.1.json) | Everything in 1.0 plus [change order types](#change-order-types): `co_types` (**required**) and `default_co_type` (optional).                                                                                                                                                             |
| `"1.2"`   | [`schema-1.2.json`](https://durohub.com/configs/change-orders/schema-1.2.json) | Everything in 1.1 plus [required approvers](#required-approvers): a `reviewers.users` entry may be a `{ id, isRequiredToApprove }` object. 1.2 is also the first **enforced** version: templates declaring it are validated against the schema at upload. **Use this for new templates.** |

* **Version manifest**: [`https://durohub.com/configs/change-orders/versions.json`](https://durohub.com/configs/change-orders/versions.json)
* **Type**: Object
* **Schema type**: `change_order_scheme`

The schemas are generated from the same declaration the API validates against, so what they accept is what `createTemplate` / `updateTemplate` accept. `notifyList.users` is an array of **UUID strings** in every version; `reviewers.users` is too, except that from `1.2` an entry may also be a reviewer object — see [Reviewers Object](#reviewers-object). The built-in [`default.yaml`](https://durohub.com/configs/change-orders/default.yaml) and [`double.yaml`](https://durohub.com/configs/change-orders/double.yaml) templates declare `version: '1.2'` and point their editor directive at `schema-1.2.json`.

{% hint style="warning" %}
The older, unversioned [`schema.json`](https://durohub.com/configs/change-orders/schema.json) predates schema versioning and is hand-maintained. It does not include `co_types`, and it describes `reviewers.users` / `notifyList.users` entries as `{ id | email, isRequired? }` objects, a shape the API does not accept. Validate against the versioned schemas above and treat `schema.json` as legacy.
{% endhint %}

### Schema versions and the manifest

Each `version` value has its own JSON Schema, and `versions.json` describes how Duro treats every version it knows about. The manifest distinguishes three sets:

| Set          | Meaning                                                                                                                                                                                                                                                                            |
| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Declared** | Versions that have a published `schema-<version>.json`. This is the full list of versions the contract describes.                                                                                                                                                                  |
| **Accepted** | Versions the API will store. A template whose `version` is not accepted is rejected at upload.                                                                                                                                                                                     |
| **Enforced** | Versions whose templates are validated against their JSON Schema when created or updated. A template in an accepted-but-unenforced version is stored as long as its participants and change order type keys pass the checks described under [Validation Rules](#validation-rules). |

Today the manifest reads:

```json
{
  "declared": ["1.0", "1.1", "1.2"],
  "accepted": ["1.0", "1.1", "1.2"],
  "enforced": ["1.2"]
}
```

{% hint style="info" %}
**Only `1.2` is structurally validated.** A `1.2` template with a wrong field type, a missing required property, or a malformed reviewer entry is rejected at upload with [`TEMPLATE_CONFIG_INVALID`](https://docs.durohub.com/advanced-topics/error-handling.md#template_config_invalid), which names the config path and the reason. `1.0` and `1.1` templates are **not** checked against their schema, so the same mistakes are stored and surface later, when a change order is created from the template. Validate those against the published schema yourself before uploading, or move them to `1.2`.
{% endhint %}

Moving a template **up** to `1.2` is allowed on update. Moving an enforced (`1.2`) template back to `1.0` or `1.1` is rejected with `CANNOT_DOWNGRADE_SCHEMA_VERSION`, because it would switch structural validation off for that template.

Two contract details apply to every version:

* **Unknown keys are allowed.** The schemas do not forbid properties they do not define, so a template may carry extra keys (for annotations or tooling) without becoming invalid. Duro ignores keys it does not recognize.
* **A key the format defines is rejected at a version where it is not valid.** `co_types` and `default_co_type` exist only from `1.1`, so `schema-1.0.json` names them just to reject them, and the API rejects them in a `1.0` template with `CO_TYPES_UNSUPPORTED_IN_SCHEMA_VERSION`.

### JSON Schema Validation

The JSON Schema provides automated validation for your workflow templates. When editing YAML files, you can use this schema to:

* **Validate your templates** before deployment to catch errors early
* **Get auto-completion** in editors that support YAML Language Server
* **Check structure before upload**: Duro applies the schema itself only to `1.2` templates, so for `1.0` and `1.1` templates your editor is the only structural check

To use the schema in your YAML files, add this comment at the top, pointing at the schema that matches the `version` you declare:

```yaml
# yaml-language-server: $schema=https://durohub.com/configs/change-orders/schema-1.2.json
version: '1.2'
```

For an older template, point at `schema-1.1.json` or `schema-1.0.json` instead. Many editors (VS Code, IntelliJ, etc.) will then provide real-time validation and helpful suggestions as you write your workflow templates. The web template editor validates against the same schema for any version listed as enforced in `versions.json`, so editor and API agree on what is rejected.

## Root Level Properties

| Property          | Type   | Required    | Description                                                                                                                                                                                                                                                                        |
| ----------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`         | string | Yes         | The [schema version](#schema-information) this template conforms to: `"1.0"`, `"1.1"` or `"1.2"`, quoted. Must be a string — an unquoted numeric version is rejected. A template with no `version` is stored as a legacy `1.0` template: `ECO` only, and no structural validation. |
| `description`     | string | Yes         | Human-readable description (max 500 chars)                                                                                                                                                                                                                                         |
| `schema_type`     | string | Yes         | Must be `"change_order_scheme"`                                                                                                                                                                                                                                                    |
| `details`         | object | Yes         | Custom field definitions                                                                                                                                                                                                                                                           |
| `validations`     | array  | No          | Reserved. Accepted and ignored; see [Validations Array](#validations-array)                                                                                                                                                                                                        |
| `stages`          | object | Yes         | Workflow stage configuration                                                                                                                                                                                                                                                       |
| `co_types`        | array  | Yes (v1.1+) | Change order types this template allows. **Required** from `schema-1.1.json` on; not part of `schema-1.0.json`. See [Change Order Types](#change-order-types).                                                                                                                     |
| `default_co_type` | string | No (v1.1+)  | The type applied when a change order is created from this template without an explicit `coType`. Defaults to `ECO`; must be a member of `co_types`. Not part of `schema-1.0.json`.                                                                                                 |

### Example Root Structure

```yaml
version: "1.2"
description: "Engineering change order workflow with dual approval"
schema_type: "change_order_scheme"
co_types: [ECO]
details:           # custom fields; see Details Object
  info:
    groups:
      - name: Details
        fields:
          - name: reason
            type: longtext
            label: Reason for Change
stages:            # review stages and resolution behavior; see Stages Object
  open:
    - name: Engineering Review
      types: [Majority]
      default: Majority
```

## Change Order Types

The `co_types` and `default_co_type` properties (schema version `1.1` and later) add two root-level fields that declare which [change order types](https://docs.durohub.com/core-concepts/change-orders.md#change-order-types) a template allows and which one it applies by default.

```yaml
version: "1.2"
description: "Engineering change workflow supporting ECO, ECR, and documentation updates"
schema_type: "change_order_scheme"

co_types: [ECO, ECR, DCO]
default_co_type: ECO

details:
  info:
    groups:
      - name: Details
        fields:
          - name: reason
            type: longtext
            label: Reason for Change
stages:
  open:
    - name: Engineering Review
      types: [Majority]
      default: Majority
```

| Property          | Type              | Required    | Description                                                                                                                                                                                                                     |
| ----------------- | ----------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `co_types`        | array of `CoType` | Yes (v1.1+) | The types a user may choose from when creating a change order from this template. Must be non-empty. Duplicates are removed. Listed under `required` in `schema-1.1.json` and `schema-1.2.json`; absent from `schema-1.0.json`. |
| `default_co_type` | `CoType`          | No (v1.1+)  | The type used when the creator does not pass an explicit `coType`. Defaults to `ECO`. Must be one of `co_types`. Absent from `schema-1.0.json`.                                                                                 |

### `CoType` values

| Value | Meaning                                                           |
| ----- | ----------------------------------------------------------------- |
| `ECO` | Engineering Change Order                                          |
| `MCO` | Manufacturing Change Order                                        |
| `DCO` | Documentation Change Order — **revision-frozen** (see note below) |
| `ECR` | Engineering Change Request                                        |
| `MCR` | Manufacturing Change Request                                      |
| `DCR` | Documentation Change Request                                      |
| `ECN` | Engineering Change Notice                                         |
| `MCN` | Manufacturing Change Notice                                       |
| `DCN` | Documentation Change Notice                                       |

{% hint style="info" %}
Only `DCO` alters behavior: change orders of type `DCO` never bump component revisions and cannot change a component's status or revision. A built-in [DCO baseline validation](https://docs.durohub.com/library-configuration/change-order-validations.md#dco-baseline-freeze) enforces this by freezing each DCO item against its last-released baseline — the change order is blocked at submit, and its release is aborted at close, if the item's live status or revision has drifted or the item has no releasable baseline. All other types are classification metadata. See [Change Orders → Change Order Types](https://docs.durohub.com/core-concepts/change-orders.md#change-order-types).
{% endhint %}

### Rules and validation

* `co_types` and `default_co_type` are only recognized when `version` is `"1.1"` or later. Including them under `"1.0"` (or an unset version) is rejected (`CO_TYPES_UNSUPPORTED_IN_SCHEMA_VERSION`). `schema-1.0.json` does not define either property.
* When `version` is `"1.1"` or later, `co_types` is **required** and must contain at least one value (`CO_TYPES_REQUIRED_IN_SCHEMA_VERSION` / `CO_TYPES_EMPTY`). `schema-1.1.json` and `schema-1.2.json` list `co_types` under `required`, so an editor pointed at either flags the omission before upload.
* `default_co_type` must be a member of `co_types` (`DEFAULT_CO_TYPE_NOT_ALLOWED`), and is rejected without `co_types` (`DEFAULT_CO_TYPE_REQUIRES_CO_TYPES`). If omitted when a template is created, it defaults to `ECO` — so a new template that omits `default_co_type` must include `ECO` in `co_types`.
* On update, an omitted `default_co_type` keeps the template's current default. An update whose `co_types` no longer contains that default is rejected (`DEFAULT_CO_TYPE_EXCLUDED_BY_UPDATE`); set `default_co_type` in the same update.
* Every entry in `co_types` and `default_co_type` must be a valid `CoType` value (`INVALID_CO_TYPE`).
* `version` must be authored as a **quoted string**. An unquoted `version: 1.1` parses as a number and is rejected (`SCHEMA_VERSION_MUST_BE_STRING`). A `version` Duro does not accept is rejected (`UNSUPPORTED_SCHEMA_VERSION`).
* A `1.2` template that does not match `schema-1.2.json` is rejected (`TEMPLATE_CONFIG_INVALID`). On update, a template with `co_types` cannot move back to `1.0`, and a `1.2` template cannot move to `1.0` or `1.1` (`CANNOT_DOWNGRADE_SCHEMA_VERSION`).

These codes are raised at **template upload**. The related **create-time** error — raised when a change order is created with a `coType` outside a template's `co_types` — is [`CO_TYPE_NOT_ALLOWED`](https://docs.durohub.com/advanced-topics/error-handling.md#co_type_not_allowed).

### Legacy (`1.0`) templates

A template without `co_types` (any `1.0` template) is treated as allowing only `ECO`, with `ECO` as the default. When queried through the GraphQL API, such a template returns `null` for both `coTypes` and `defaultCoType` — do not round-trip those nulls back into a `1.0` config on update. To offer additional types, migrate the template to `version: "1.2"` and add a `co_types` array.

{% hint style="info" %}
The built-in default templates shipped with every library ([`default.yaml`](https://durohub.com/configs/change-orders/default.yaml) and [`double.yaml`](https://durohub.com/configs/change-orders/double.yaml)) are authored at `version: "1.2"`, reference `schema-1.2.json` in their `yaml-language-server` directive, and declare `co_types: [ECO]` and `default_co_type: ECO`. They are ECO-only out of the box; add other `CoType` values to `co_types` to allow them. Libraries created before these templates moved to `1.2` keep the version their templates were created with.

These templates do **not** define a `change_type` content field in `details.info.groups`. Change order type is set entirely through `co_types` / `default_co_type`; the legacy `change_type` enum that earlier templates used for this purpose has been removed. `default.yaml` now ships a *Reason for Change* field, and `double.yaml` an *Impact Analysis* group. Content fields named `change_type` remain valid as ordinary custom fields for backward compatibility, but are no longer part of the built-in defaults.
{% endhint %}

## Details Object

The `details` object contains custom field definitions organized in groups.

### Structure

```yaml
details:
  info:
    groups:
      - name: string
        icon: string (optional)
        description: string (optional)
        fields: [ ]
```

### Group Properties

| Property      | Type   | Required | Description                                    |
| ------------- | ------ | -------- | ---------------------------------------------- |
| `name`        | string | Yes      | Display name (max 100 chars)                   |
| `icon`        | string | No       | Material Design Icon (format: `mdi-icon-name`) |
| `description` | string | No       | Group description (max 500 chars)              |
| `fields`      | array  | Yes      | Array of field definitions                     |

## Field Definitions

Each field in a group has the following properties:

| Property      | Type    | Required    | Description                                                                                                                                                                                                                                                        |
| ------------- | ------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `type`        | string  | Yes         | Field type (see Field Types section)                                                                                                                                                                                                                               |
| `name`        | string  | Yes         | Programmatic name (pattern: `^[a-zA-Z_][a-zA-Z0-9_]*$`). The schema does not list it as required, but a change order cannot be created from a template whose fields lack a `name`, so always set it                                                                |
| `label`       | string  | Yes         | Display label (max 100 chars)                                                                                                                                                                                                                                      |
| `description` | string  | No          | Help text (max 500 chars)                                                                                                                                                                                                                                          |
| `placeholder` | string  | No          | Placeholder text (max 200 chars)                                                                                                                                                                                                                                   |
| `required`    | boolean | No          | Marks the field as required in the web app's change order form. The API does not check it, so a change order can be created and submitted through the API with the field empty. This is the only flag that marks a field required; `validations.required` does not |
| `validations` | object  | No          | Accepted but not applied; see [Field Validation Object](#field-validation-object)                                                                                                                                                                                  |
| `default`     | string  | No          | Accepted but not applied: the field starts empty                                                                                                                                                                                                                   |
| `options`     | array   | Conditional | Required for list/enum types                                                                                                                                                                                                                                       |
| `multiSelect` | boolean | No          | Accept more than one option (`list` or `enum`). Omit it and the field is single-select                                                                                                                                                                             |

### Field Types

| Type       | Description                                                            | Additional Properties    |
| ---------- | ---------------------------------------------------------------------- | ------------------------ |
| `text`     | Single-line text input                                                 | -                        |
| `longtext` | Multi-line text area                                                   | -                        |
| `number`   | Numeric input. Values must be numbers (`CONTENT_VALUE_NOT_A_NUMBER`)   | -                        |
| `date`     | Date picker. Values must be valid dates (`CONTENT_INVALID_DATE`)       | -                        |
| `currency` | Currency amount. Values must be numbers (`CONTENT_VALUE_NOT_A_NUMBER`) | -                        |
| `enum`     | Dropdown; stored as a `list`                                           | `options`, `multiSelect` |
| `list`     | Single selection by default; multiple with `multiSelect: true`         | `options`, `multiSelect` |

For `list` and `enum` fields, a value must be one of the field's option values (`CONTENT_VALUE_NOT_AN_OPTION`), and only a `multiSelect` field accepts more than one value (`CONTENT_TOO_MANY_VALUES`). These checks apply whenever a field value is written.

### Field Validation Object

```yaml
validations:
  required: boolean
  min: integer
  max: integer
  pattern: string (regex)
```

| Property   | Type    | Applies To             | Description                                         |
| ---------- | ------- | ---------------------- | --------------------------------------------------- |
| `required` | boolean | All types              | Not applied. Use the field-level `required` instead |
| `min`      | integer | number, currency, text | Not applied                                         |
| `max`      | integer | number, currency, text | Not applied                                         |
| `pattern`  | string  | text                   | Not applied                                         |

{% hint style="warning" %}
The schema accepts a `validations` object on a field, but Duro does not apply any of it: `validations.required` does not mark a field required, and `min`, `max` and `pattern` are not checked anywhere. To mark a field required in the change order form, set `required: true` on the field itself:

```yaml
- name: project
  type: text
  label: Project
  required: true
```

To enforce a range or a format, write a [custom validation](https://docs.durohub.com/library-configuration/authoring-custom-validations.md).
{% endhint %}

### Options for List/Enum Fields

```yaml
options:
  - label: string
    value: string
    description: string (optional)
```

| Property      | Type   | Required | Description                                                                                  |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------- |
| `label`       | string | Yes      | Required by the schema (max 100 chars), but not shown                                        |
| `value`       | string | Yes      | Stored on the change order **and shown to users** (max 100 chars). Write it as readable text |
| `description` | string | No       | Accepted but not shown (max 500 chars)                                                       |

Only option values are kept when a change order is created from the template, so the dropdown and the saved change order show `value`. Set `label` to the same text as `value`.

## Validations Array

Reserved. Duro accepts this array and ignores it: template `validations` entries do not select or configure anything. Every active [validation rule](https://docs.durohub.com/library-configuration/change-order-validations.md) in the library runs on every change order, whichever template it uses.

```yaml
validations:
  - id: string
    severity: string
```

| Property   | Type   | Required | Description                           |
| ---------- | ------ | -------- | ------------------------------------- |
| `id`       | string | Yes      | Validation ID (pattern: `^\d+\.\d+$`) |
| `severity` | string | Yes      | One of: `error`, `warn`, `info`       |

## Stages Object

Defines the workflow stages and their behavior.

```yaml
stages:
  open: [ ]      # Required: active review stages (at least one)
  resolved: { }  # Optional: resolution behavior (resolutions)
  closed: { }    # Optional: who is emailed when the change order closes (notifyList)
```

### Open Stages Array

Array of sequential review stages. Each stage has:

| Property       | Type    | Required | Description                                                                                                                                                                         |
| -------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`         | string  | Yes      | Stage name (max 100 chars)                                                                                                                                                          |
| `types`        | array   | Yes      | Available approval types. Required by the schema; checked at upload only for `1.2` templates. In a `1.0` or `1.1` template a missing value falls back to `Unanimous`                |
| `default`      | string  | Yes      | Default approval type. Same per-version enforcement as `types`                                                                                                                      |
| `minReviewers` | integer | No       | The fewest reviewers the stage must have before the change order can be submitted, for every approval type. For `Minimum` it is also the starting approval threshold. Defaults to 1 |
| `reviewers`    | object  | No       | Pre-assigned reviewers (internal users)                                                                                                                                             |
| `notifyList`   | object  | No       | Pre-assigned stage notifiers (internal users and/or external emails)                                                                                                                |

#### Approval Types

Each stage must support one or more approval types:

| Type        | Description                                                                                                                                                                                     |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Unanimous` | Approved when all reviewers approve; rejected as soon as any reviewer rejects                                                                                                                   |
| `Majority`  | Approved when more than half approve; rejected when more than half reject                                                                                                                       |
| `Minimum`   | Approved when the stage's `decisionMinimumCount` reviewers approve; rejected when that many reject. `decisionMinimumCount` starts at `minReviewers`, and the change order's author may raise it |

A stage with [required approvers](#required-approvers) also needs every one of them to approve, whichever type is chosen.

{% hint style="info" %}
The values shown here are the schema as stored and as accepted by the GraphQL API: `reviewers.users` and `notifyList.users` must be **UUID strings**. To resolve names to UUIDs, query your organization's members — see [RBAC → Get Organization Members with Roles](https://docs.durohub.com/advanced-topics/rbac.md#get-organization-members-with-roles). The web template editor accepts **email addresses** for internal users and resolves them to UUIDs on save, so manual lookup is only needed when authoring YAML by hand.
{% endhint %}

#### Reviewers Object

Pre-assign reviewers to a stage. Reviewers are internal users, specified by UUID.

```yaml
reviewers:
  users:
    - 123e4567-e89b-12d3-a456-426614174001
    - 123e4567-e89b-12d3-a456-426614174002
```

| Property | Type  | Required | Description                                                                                                                                                 |
| -------- | ----- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users`  | array | No       | Internal user UUIDs (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`, lowercase). From `1.2`, an entry may instead be a [reviewer object](#reviewer-object). |

**Note**: Each entry must reference an existing user in the library's organization. External email addresses are not allowed here — use `notifyList.emails` instead. Duplicate IDs within a stage are automatically deduplicated.

**Reviewer object**

Available from `version: '1.2'`.

| Property              | Type    | Required | Description                                                                                                                   |
| --------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | string  | Yes      | The reviewer's user UUID                                                                                                      |
| `isRequiredToApprove` | boolean | No       | `true` makes this reviewer a [required approver](#required-approvers). Omitted or `false` is the same as a plain UUID string. |

```yaml
version: '1.2'
# ...
reviewers:
  users:
    - 123e4567-e89b-12d3-a456-426614174001          # an ordinary reviewer
    - id: 123e4567-e89b-12d3-a456-426614174002      # a required approver
      isRequiredToApprove: true
```

Below `1.2`, entries must be plain UUID strings, and an object entry is rejected as malformed (`TEMPLATE_PARTICIPANT_MALFORMED_CONFIG`). In every version the object takes an `id`, never an `email`; the `{ email }` and `isRequired` forms in the legacy `schema.json` are not accepted by the API. `notifyList.users` never accepts objects.

#### Required Approvers

From `1.2`, a reviewer marked `isRequiredToApprove: true` becomes a **required approver** on every change order created from the template. Each change order stage reviewer exposes this as `StageReviewer.isRequiredToApprove` in the GraphQL API.

* **The stage waits for them.** A stage is not approved until every required approver has approved, even when its approval type is already met (for example, a `Majority` reached without them).
* **Their rejection is final for the stage.** If a required approver rejects, the stage is rejected at once.
* **They cannot be removed.** Removing a required approver from a change order's stage is refused with [`CANNOT_REMOVE_REQUIRED_REVIEWER`](https://docs.durohub.com/advanced-topics/error-handling.md#cannot_remove_required_reviewer), in any change order status. When several reviewers are removed in one request, nothing is removed.
* **They must still resolve.** Ordinary reviewers who have left the organization are skipped when a change order is created. A required approver who can no longer be added to the library instead blocks creation (and switching a draft to the template) with [`REQUIRED_APPROVER_UNRESOLVABLE`](https://docs.durohub.com/advanced-topics/error-handling.md#required_approver_unresolvable) until someone updates the template.
* **Only templates can set them.** An inline `config` passed to `changeOrders.create` cannot contain reviewer objects; see [`INLINE_CONFIG_REVIEWER_OBJECTS_UNSUPPORTED`](https://docs.durohub.com/advanced-topics/error-handling.md#inline_config_reviewer_objects_unsupported).

If the same user appears in a stage more than once, they are added once, and they are required if any of their entries is marked `isRequiredToApprove: true`. Required approvers affect stage decisions only; they do not change who may submit the change order.

#### NotifyList Object

Pre-assign notifiers to a stage. Notifiers are added to the stage's notify list when the change order is created but do not participate in the approval process. A notify list can include internal users, external email addresses, or both. The same object under `stages.closed` lists people emailed when the change order closes; see [Stage Actions](#stage-actions-resolved-closed).

```yaml
notifyList:
  users:
    - 123e4567-e89b-12d3-a456-426614174003
  emails:
    - supplier@example.com
```

| Property | Type             | Required | Description                                                            |
| -------- | ---------------- | -------- | ---------------------------------------------------------------------- |
| `users`  | array of strings | No       | Internal user UUIDs (format: `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)   |
| `emails` | array of strings | No       | External recipient email addresses (for people without a Duro account) |

**Note**: Provide `users`, `emails`, or both. `users` follows the same UUID and organization-membership rules as `reviewers.users`, but entries are always plain UUID strings, never objects, in every version. `emails` is not checked against the organization; in a `1.2` template each entry must be a well-formed address, and in `1.0` and `1.1` templates the format is not checked.

### Stage Actions (resolved, closed)

`resolved` and `closed` sit under `stages`, next to `open`. At the root of the template they are ignored without an error.

```yaml
stages:
  open:
    - name: Engineering Review
      types: [Majority]
      default: Majority
  resolved:
    resolutions:
      onapproval: [AUTO_CLOSE]
      onrejection: [MANUAL_CLOSE]
      onwithdrawal: [MANUAL_CLOSE]
  closed:
    notifyList:
      users:
        - 123e4567-e89b-12d3-a456-426614174003
      emails:
        - quality-records@example.com
```

| Property               | Used | Behavior                                                                                                                                                                                            |
| ---------------------- | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `resolved.resolutions` | Yes  | For each outcome, the close behaviors the change order allows. The first entry is applied; an outcome you leave out uses `AUTO_CLOSE`.                                                              |
| `closed.notifyList`    | Yes  | People emailed when the change order closes, whatever the outcome, alongside its reviewers and notifiers. Users who are no longer members of the organization or library at close time are skipped. |
| `resolved.notifyList`  | No   | Accepted but not used; nobody listed is emailed.                                                                                                                                                    |
| `actions`              | No   | Accepted but not used.                                                                                                                                                                              |
| `closed.resolutions`   | No   | Only `resolved.resolutions` is read.                                                                                                                                                                |

#### Resolution Types

| Value          | Description                        |
| -------------- | ---------------------------------- |
| `AUTO_CLOSE`   | Automatically transition to closed |
| `MANUAL_CLOSE` | Require manual closure             |

## Complete Example

```yaml
version: "1.2"
description: "Medical device change control workflow"
schema_type: "change_order_scheme"

co_types: [ECO]
default_co_type: ECO

details:
  info:
    groups:
      - name: "Change Classification"
        icon: "mdi-medical-bag"
        fields:
          - name: "change_category"
            type: "enum"
            label: "Change Category"
            options:
              - label: "Design Change"
                value: "Design Change"
              - label: "Process Change"
                value: "Process Change"
            required: true

          - name: "risk_level"
            type: "list"
            label: "Risk Categories"
            multiSelect: true
            options:
              - label: "Patient Safety"
                value: "Patient Safety"
              - label: "Product Performance"
                value: "Product Performance"
              - label: "Regulatory Compliance"
                value: "Regulatory Compliance"

      - name: "Impact Assessment"
        icon: "mdi-chart-line"
        fields:
          - name: "validation_required"
            type: "enum"
            label: "Validation Required"
            options:
              - label: "Full Validation"
                value: "Full Validation"
              - label: "Partial Validation"
                value: "Partial Validation"
              - label: "No Validation"
                value: "No Validation"
            required: true

stages:
  open:
    - name: "Engineering Review"
      types: ["Unanimous"]
      default: "Unanimous"
      minReviewers: 2
      reviewers:
        users:
          - 123e4567-e89b-12d3-a456-426614174001
          - 123e4567-e89b-12d3-a456-426614174002
      notifyList:
        users:
          - 123e4567-e89b-12d3-a456-426614174003
        emails:
          - supplier@example.com

    - name: "Quality Review"
      types: ["Unanimous", "Majority"]
      default: "Unanimous"
      minReviewers: 1
      reviewers:
        users:
          - id: 123e4567-e89b-12d3-a456-426614174004
            isRequiredToApprove: true   # Quality must sign off
          - 123e4567-e89b-12d3-a456-426614174005

  resolved:
    resolutions:
      onapproval: ["AUTO_CLOSE"]
      onrejection: ["MANUAL_CLOSE"]
      onwithdrawal: ["MANUAL_CLOSE"]

  closed:
    notifyList:
      emails:
        - quality-records@example.com
```

The user IDs in this example are placeholders. Replace them with the IDs of members of your organization, or the upload is rejected with `TEMPLATE_PARTICIPANT_INVALID_USER_ID`.

## Validation Rules

The JSON Schema describes these structural rules. Duro enforces rules 1–5 at template upload only for versions listed as **enforced** in [`versions.json`](#schema-versions-and-the-manifest), which today is `1.2`. For a `1.0` or `1.1` template, treat rules 1–5 as what your editor or CI should check. Rules 6 and 7 are enforced by the API in every version.

1. **Field Properties**: Every field has a `type` and a `label`, and `list` / `enum` fields have `options`
2. **Pattern Matching**: Field names must match `^[a-zA-Z_][a-zA-Z0-9_]*$`
3. **Length Limits**:
   * Descriptions: 500 characters
   * Labels/Names: 100 characters
   * Placeholders: 200 characters
4. **Type Constraints**:
   * List/Enum fields must have at least one option
   * Only `list` and `enum` fields can use `multiSelect`
5. **Stage Requirements**:
   * At least one open stage is required
   * Each stage must have a name, types array, and default type
6. **Participant Constraints**:
   * `notifyList.users` must be an array of UUID strings
   * `reviewers.users` must be an array of UUID strings, or from `1.2` `{ id, isRequiredToApprove }` objects; `{ email }` objects and `isRequired` flags are rejected
   * Each user must exist in the system and belong to the library's organization
   * `notifyList.emails` accepts external email addresses and is not validated against the organization
   * Invalid participants are rejected at template upload
7. **Schema Version**:
   * `version` must be a quoted string and one of the accepted versions in `versions.json`; it selects which schema the template is validated against
   * Under `"1.0"`, `co_types` and `default_co_type` are rejected
   * From `"1.1"`, `co_types` is required and non-empty, and `default_co_type` must be one of its members
   * An enforced (`1.2`) template cannot be changed back to an unenforced version (`CANNOT_DOWNGRADE_SCHEMA_VERSION`)
   * Unknown keys are permitted in every version and ignored by Duro

A `1.2` template that breaks rules 1–5 is rejected with [`TEMPLATE_CONFIG_INVALID`](https://docs.durohub.com/advanced-topics/error-handling.md#template_config_invalid), whose message names the offending config path and the reason.

## Best Practices

1. **Use Semantic Names**: Choose descriptive names for fields and stages
2. **Provide Descriptions**: Help users understand field purposes
3. **Write Readable Option Values**: Users see each option's `value`, so write it as the text you want them to read
4. **Configure Notifications**: Ensure stakeholders are informed
5. **Test Workflows**: Validate all paths through your workflow
6. **Version Control**: Track changes to workflow templates
7. **Document Decisions**: Use the description field to explain workflow design choices


---

# 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/change-order-workflow-reference.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.
