> 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/cpn-schema-reference.md).

# CPN Schema Reference

## Overview

This document is a complete reference for the CPN (Component Part Number) Schema YAML specification. The schema defines the structure and constraints for CPN generation schemes in Duro. A library has one CPN scheme, saved as its `ID` configuration (see [Applying a configuration](https://docs.durohub.com/library-configuration/introduction.md#applying-a-configuration)). For what a scheme produces when you create, copy or vary a component, see [CPN Behavior Rules](https://docs.durohub.com/library-configuration/cpn-behavior.md).

## Schema Information

* **Schema Version**: 1.0
* **JSON Schema**: [`schemas/cpn.json`](https://github.com/duronext/developer/tree/main/schemas/cpn.json) (draft-07, `http://json-schema.org/draft-07/schema#`)
* **Type**: Object

{% hint style="info" %}
Point your editor at `schemas/cpn.json` (for example with a `# yaml-language-server: $schema=...` comment) to get completion and validation while you write a scheme. Duro checks every scheme against the same rules when you save it.
{% endhint %}

## Root Level Properties

A scheme has five root properties, and all five are required.

| Property      | Type   | Required | Description                                                                                             |
| ------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------- |
| `version`     | string | Yes      | Version of the CPN schema. Must match pattern `^\d+\.\d+$`, for example `'1.0'`                         |
| `schema_type` | string | Yes      | `cpn_generation_scheme`. `cpn_generation_scheme_custom` is also accepted and behaves the same.          |
| `elements`    | array  | Yes      | Array of element definitions (declared first — this is the structural backbone)                         |
| `settings`    | object | Yes      | Global settings, including `element_mappings` that bind elements to system inputs. May be empty (`{}`). |
| `examples`    | array  | Yes      | At least one example CPN that follows the scheme                                                        |

### Recommended Authoring Order

The default schemes shipped with Duro (and the order that is easiest for a human to read) declare keys in this order:

```yaml
version: '1.0'
schema_type: cpn_generation_scheme
elements:
  - name: category
    type: list
    required: true
    values: '${{ duro.categories }}'
  - name: separator
    type: constant
    required: true
    value: '-'
  - name: sequence
    type: numeric_counter
    required: true
    attachedTo: [category]
    format:
      min_value: 1
      max_value: 99999
settings:
  element_mappings:
    category: category
  allow_override: false
  allow_freeform: false
examples:
  - '410-00001'
```

You define the `elements` first because they describe *what* the CPN looks like. You then describe *how it behaves* under `settings`, including which element maps to the system's category input.

## CPN Uniqueness

Every CPN in a library is unique, and uniqueness is **case-insensitive**: `ABC-001` and `abc-001` are the same CPN, and the second one is rejected. A CPN is never reused once it has been assigned, even if the component that held it is deleted.

## Settings Object

The `settings` object contains global configuration for CPN generation.

```yaml
# Structure (property types, not literal values)
settings:
  element_mappings:            # Required when an element resolves from system data (e.g. categories)
    category: <element_name>
    variant: <element_name>    # Optional, only used when a variant element is present
  allow_override: boolean      # Default: false
  allow_freeform: boolean      # Default: false. true requires allow_override: true
  override_elements: [string]  # Default: null. Used by the Duro web app only
  freeform_validation:         # Optional. Requires allow_override: true and allow_freeform: true
    pattern: string
    max_length: integer        # 1-50
    description: string
```

| Property              | Type    | Required | Default | Description                                                                                                                                                                                                      |
| --------------------- | ------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `element_mappings`    | object  | Cond.    | —       | Binds scheme element names to system inputs. Required when a list element draws its values from `${{ duro.categories }}`.                                                                                        |
| `allow_override`      | boolean | No       | `false` | Whether a caller may supply its own **counter** values. If `false`, every counter is assigned by Duro. Choosing a value for a list (such as a category or a variant) is never an override and is always allowed. |
| `allow_freeform`      | boolean | No       | `false` | Whether a caller may supply the whole CPN as free text that does not follow the scheme. `true` is only valid together with `allow_override: true`; any other combination is rejected when you save the scheme.   |
| `override_elements`   | array   | No       | `null`  | Element names the Duro web app offers for override. See "Element-Level Override Control" below.                                                                                                                  |
| `freeform_validation` | object  | No       | —       | Validation for freeform CPNs. Including it without both `allow_override: true` and `allow_freeform: true` is a validation error. Defaults to alphanumeric/hyphen/underscore with a 50-character limit.           |

### Element Mappings

`element_mappings` is the bridge between your scheme and the values Duro provides at generation time. When the generator receives a `categoryId`, it looks up which scheme element should receive that value.

```yaml
settings:
  element_mappings:
    category: category   # Bind the "category" input to the element named "category"
    variant: variant     # Optional — bind variant inputs to a variant element
```

| Key        | Required | Description                                                                                                                                         |
| ---------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category` | Cond.    | The `name` of the top-level `list` element that represents the part category. Required when the element draws values from `${{ duro.categories }}`. |
| `variant`  | No       | The `name` of the element that represents the variant. Only set when your scheme has a variant element.                                             |

The key (`category` / `variant`) is the **system input**; the value is the **element `name`** declared in the `elements` array. Each value is a single element name (a string, not a list). The two do not need to match — for example, if your category list element is named `prefix`, you would write `category: prefix`.

When `category` is mapped, the component's category drives that element: supply the `categoryId` and Duro fills in the category's code. Supplying a different value for the mapped element than the category you passed fails with `CATEGORY_ELEMENT_CONFLICT`.

{% hint style="info" %}
Without `element_mappings.category`, a category-driven list element is just an ordinary required list: creating a component with only a `categoryId` fails with `REQUIRED_ELEMENT_MISSING`. This is the single most common reason a custom scheme rejects valid input.
{% endhint %}

### Freeform Validation Object

When `allow_freeform` is `true`, you can optionally specify custom validation rules:

| Property      | Type    | Required | Description                                                                                     |
| ------------- | ------- | -------- | ----------------------------------------------------------------------------------------------- |
| `pattern`     | string  | No       | Regex pattern that freeform CPNs must match. If not specified, uses default `^[a-zA-Z0-9\-_]+$` |
| `max_length`  | integer | No       | Maximum length for freeform CPNs, from 1 to 50. Defaults to 50.                                 |
| `description` | string  | No       | Human-readable description of the format requirements shown to users                            |

#### Freeform Validation Examples

**Basic freeform with default validation:**

```yaml
settings:
  allow_override: true
  allow_freeform: true
  # Uses default pattern ^[a-zA-Z0-9\-_]+$ with 50 character limit
```

**Custom pattern for company naming convention:**

```yaml
settings:
  allow_override: true
  allow_freeform: true
  freeform_validation:
    pattern: "^[A-Z]{2,4}-\\d{4,6}$"
    max_length: 20
    description: "Format: 2-4 letters, hyphen, 4-6 digits"
```

### Element-Level Override Control

An **override** is a counter value the caller supplies instead of letting Duro assign one. Overrides need `allow_override: true`; without it, supplying a counter value fails with `INVALID_SETTINGS_COMBINATION`. Supplying a freeform CPN without `allow_freeform: true` fails with `INVALID_FREEFORM_IDENTIFIER`. See [Validating CPN Overrides](https://docs.durohub.com/core-concepts/components.md#validating-cpn-overrides) for how to pass element values and freeform CPNs through the API.

`override_elements` lists the elements the Duro web app offers for override when `allow_override` is `true`. It does not restrict the API: when `allow_override` is `true`, a caller can supply a value for any counter.

| `override_elements`        | Behavior in the Duro web app                                           |
| -------------------------- | ---------------------------------------------------------------------- |
| `null` (default)           | All elements are offered for override when `allow_override` is `true`. |
| `["element1", "element2"]` | Only the listed elements are offered for override.                     |

```yaml
settings:
  allow_override: true
  allow_freeform: false
  override_elements: ["sequence"]   # The web app offers only "sequence" for override
```

### Behavior Matrix

| `allow_override` | `allow_freeform` | Behavior                                                                                                                                                                      |
| ---------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `false`          | `false`          | Counters are always assigned by Duro. Callers still choose list values, such as a category or a variant.                                                                      |
| `false`          | `true`           | Invalid — rejected when you save the scheme.                                                                                                                                  |
| `true`           | `false`          | Callers may also supply counter values. The resulting CPN must still conform to the scheme.                                                                                   |
| `true`           | `true`           | Callers may also supply the whole CPN as free text, validated against `freeform_validation`. A freeform value that happens to match the scheme is stored as a structured CPN. |

## Elements

The `elements` array contains definitions for each component of the CPN. Each element must be one of:

* `list` — selects a value from a predefined list or system reference
* `constant` — inserts a fixed value such as a delimiter or prefix
* `numeric_counter` — generates sequential numeric values within a range
* `hex_counter` — generates sequential hexadecimal values within a range
* `alpha_counter` — generates sequential uppercase alphabetic values within a range
* `group` — bundles multiple elements into a single logical unit

### Common Element Properties

All elements include these base properties:

| Property     | Type    | Required | Description                                                                                                                                                                                                                                           |
| ------------ | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`       | string  | Yes      | Element type identifier.                                                                                                                                                                                                                              |
| `name`       | string  | Yes      | Unique name for the element. Used for cross-references such as `attachedTo` and `element_mappings`.                                                                                                                                                   |
| `required`   | boolean | Cond.    | Whether the element must appear in every generated CPN. Mandatory on top-level `list`, counter and `group` elements (the scheme is rejected without it). Optional on `constant` elements and on elements inside a group, where it defaults to `true`. |
| `attachedTo` | array   | No       | Counters only. Names of one or more elements the counter is **scoped to**.                                                                                                                                                                            |

#### About `attachedTo`

`attachedTo` scopes a counter: the counter keeps an independent sequence for each combination of values of the elements it is attached to. For example, a sequence counter attached to `category` tracks an independent sequence per category. Multiple attachments are supported (e.g. `['prefix', 'sequence']`), and a counter can attach to a group by the group's name. `attachedTo` has an effect on counters only; list and group elements ignore it.

```yaml
- type: numeric_counter
  name: sequence
  required: true
  attachedTo: ['category']
  format:
    min_value: 1
    max_value: 99999
```

### List Element

A `list` element selects from a predefined set of values, an object array with metadata, or a system-provided template reference.

```yaml
# Structure (property types, not literal values)
- type: list
  name: string
  required: boolean
  values: (string[] | object[] | template_string)
```

| Property | Type            | Required | Description                             |
| -------- | --------------- | -------- | --------------------------------------- |
| `values` | array \| string | Yes      | Array of values or a template reference |

Values must be one of:

1. Array of strings
2. Array of objects with `id`, `name`, and optional `description`
3. Template reference in the form `${{ duro.categories }}` (see [Template References](#template-references))

**What appears in the CPN.** For object values, the CPN shows the item's `id`. For `${{ duro.categories }}`, it shows the category's `code`. For string values, it shows the string itself.

**How a supplied value is matched.** A value supplied for a list element is matched case-insensitively against each item's `code`, `id`, category UUID, `name` and plain string value, in that order. Supplying a value that matches no item fails.

{% hint style="warning" %}
The schema also accepts `use` and `validation.pattern` on a list element. Neither has any effect: the rendered value is always chosen as described above, and `validation.pattern` is not checked when a CPN is generated. Constrain a list by the values you put in it.
{% endhint %}

#### List Element Examples

```yaml
# Pull values from the system's categories
- type: list
  name: category
  required: true
  values: '${{ duro.categories }}'
```

```yaml
# Inline string values
- type: list
  name: prefix
  required: true
  values:
    - "410"
    - "591"
    - "423"
```

```yaml
# Object values with metadata. The CPN shows the id.
- type: list
  name: family
  required: true
  values:
    - id: "410"
      name: Screws
      description: Mechanical fasteners
    - id: "591"
      name: Resistors
      description: Electronic components
```

{% hint style="info" %}
When a list element uses `${{ duro.categories }}`, you must declare `settings.element_mappings.category` so the generator can resolve the inbound `categoryId`.
{% endhint %}

### Constant Element

Constants are fixed strings injected into every generated CPN. Use them for delimiters (`-`, `.`) or static prefixes/suffixes.

```yaml
# Structure (property types, not literal values)
- type: constant
  name: string
  required: boolean
  value: string
```

| Property | Type   | Required | Description        |
| -------- | ------ | -------- | ------------------ |
| `value`  | string | Yes      | The constant value |

```yaml
- type: constant
  name: separator
  required: true
  value: "-"
```

### Numeric Counter

A `numeric_counter` generates sequential integers within a range. It is always **fixed length**, determined by the number of digits in `format.max_value`. Leading zeros are prepended automatically.

```yaml
# Structure (property types, not literal values)
- type: numeric_counter
  name: string
  required: boolean
  attachedTo: string[]
  format:
    min_value: integer       # Must be ≥ 0
    max_value: integer
```

```yaml
- type: numeric_counter
  name: sequence
  required: true
  attachedTo: ['category']
  format:
    min_value: 1
    max_value: 99999
```

The example above generates a 5-digit sequence (`00001` through `99999`), tracked independently per category:

* `410-00001`, `410-00002`, `410-00003`
* `591-00001` (independent sequence for category `591`)

Counters **gap-fill**: each new CPN gets the lowest unused value in its scope, not the highest value plus one. If `410-00002` was never used (for example, because a caller supplied `410-00003` as an override), the next generated CPN in category `410` is `410-00002`. Values supplied as overrides are never handed out again.

### Hex Counter

A `hex_counter` generates sequential hexadecimal values within a range. Fixed length, zero-padded.

```yaml
# Structure (property types, not literal values)
- type: hex_counter
  name: string
  required: boolean
  attachedTo: string[]
  format:
    min_value: string        # Pattern: ^[0-9A-F]+$
    max_value: string        # Pattern: ^[0-9A-F]+$
```

```yaml
- type: hex_counter
  name: sequence
  required: true
  attachedTo: ['category']
  format:
    min_value: "0"
    max_value: "FF"
```

Generates `00`, `01`, … `FE`, `FF`.

### Alpha Counter

An `alpha_counter` generates sequential uppercase alphabetic values within a range. It counts the way spreadsheet columns do: `A` … `Z`, then `AA`, `AB` … `ZZ`, then `AAA`. Alpha counters are **not padded**, so their width varies with the value.

```yaml
# Structure (property types, not literal values)
- type: alpha_counter
  name: string
  required: boolean
  attachedTo: string[]
  format:
    min_value: string        # Pattern: ^[A-Z]+$
    max_value: string        # Pattern: ^[A-Z]+$
```

```yaml
- type: alpha_counter
  name: variant
  required: true
  attachedTo: ['base_cpn']
  format:
    min_value: "A"
    max_value: "Z"
```

Generates `A`, `B`, `C`, …, `Z`. With `min_value: "A"` / `max_value: "ZZ"`, it generates `A` … `Z` and then `AA` … `ZZ`. To keep a fixed two-letter width, use `min_value: "AA"` / `max_value: "ZZ"`.

### Group Element

Groups bundle multiple elements into a single logical unit. Use them to make several elements optional together (an optional suffix), or to give a counter outside the group one thing to attach to: a counter whose `attachedTo` names the group is scoped to the group's complete value.

```yaml
# Structure (property types, not literal values)
- type: group
  name: string
  required: boolean
  reusable: boolean          # Optional, default false
  elements: array
```

| Property   | Type    | Required | Description                                                                                    |
| ---------- | ------- | -------- | ---------------------------------------------------------------------------------------------- |
| `elements` | array   | Yes      | Array of nested element definitions (at least one).                                            |
| `reusable` | boolean | No       | When `true`, group instances are tracked and reused. Defaults to `false`. See the rules below. |

Group elements can contain `list`, `constant`, `numeric_counter`, `hex_counter` and `alpha_counter` elements. **Groups cannot contain groups.** A group may be optional (`required: false`) even when its inner elements are required: when the group is present, all of its elements are.

**Reusable groups.** A group with `reusable: true` must contain exactly one counter, and that counter's `attachedTo` must list every non-constant, non-counter element in the group — and nothing outside it. A scheme that breaks either rule is rejected when you save it. CPNs from a scheme with a reusable group cannot be parsed back into elements from a CPN string (for example, a freeform value is not recognized as structured).

#### Group Example — Optional Variant Suffix

```yaml
- type: group
  name: variant_group
  required: false
  elements:
    - type: constant
      name: separator
      value: "."
    - type: list
      name: variant
      values: ["A", "B", "C"]
```

Produces CPNs such as `123-4567` (no suffix) or `123-4567.A`.

#### Group Example — Base CPN with Variant

```yaml
elements:
  - type: group
    name: base_cpn
    required: true
    elements:
      - type: list
        name: prefix
        values:
          - id: "100"
            name: "Mechanical"
          - id: "200"
            name: "Electrical"
      - type: constant
        name: delimiter_1
        value: "-"
      - type: numeric_counter
        name: sequence
        attachedTo: ['prefix']
        format:
          min_value: 1
          max_value: 99999

  - type: constant
    name: delimiter_2
    required: true
    value: "-"

  - type: alpha_counter
    name: variant
    required: true
    attachedTo: ['base_cpn']
    format:
      min_value: "A"
      max_value: "Z"
```

Produces `100-00001-A`, `100-00001-B`, and so on. `variant` is a counter attached to the `base_cpn` group, so variant letters are counted separately for each complete base number rather than for `prefix` and `sequence` separately.

## Examples Array

The `examples` array must contain at least one example CPN that follows the defined scheme. Duro does not check the examples against the elements, so keep them accurate by hand.

```yaml
examples:
  - "410-00001"
  - "591-00042"
```

## Template References

Template references pull dynamic value lists from the system:

```yaml
# Structure (property types, not literal values)
values: "${{ namespace.field }}"
```

Template references must match the pattern `^\$\{\{\s*[\w\.]+\s*\}\}$`. The only supported reference is `${{ duro.categories }}`, which expands to the library's categories. Each category provides its `code` (what appears in the CPN), `name`, `description` and UUID. Any other reference is not resolved, and the list can never match a value. When a list element uses `${{ duro.categories }}`, remember to set `settings.element_mappings.category`.

{% hint style="info" %}
Quote template references in YAML (`values: '${{ duro.categories }}'`). Unquoted, some YAML parsers read the braces as a mapping.
{% endhint %}

## Complete Schema Examples

### Example 1: Basic Semi-Intelligent Scheme

This is the default semi-intelligent scheme shipped with Duro (preset `ID_SEMI_INTELLIGENT`). Categories come from the system; the sequence is tracked per category.

```yaml
version: '1.0'
schema_type: cpn_generation_scheme
elements:
  - name: category
    type: list
    values: '${{ duro.categories }}'
    required: true
  - name: category_counter_separator
    type: constant
    required: true
    value: '-'
  - name: sequence
    type: numeric_counter
    required: true
    format:
      min_value: 1
      max_value: 99999
    attachedTo:
      - category
settings:
  element_mappings:
    category: category
  allow_freeform: false
  allow_override: false
examples:
  - '410-00001'
  - '591-00042'
  - '423-01234'
```

### Example 2: Non-Intelligent (Pure Sequence)

A flat numeric scheme with no categories and therefore no `element_mappings` (preset `ID_NON_INTELLIGENT`).

```yaml
version: '1.0'
schema_type: cpn_generation_scheme
elements:
  - name: sequence
    type: numeric_counter
    required: true
    format:
      min_value: 100001
      max_value: 999999
settings:
  allow_freeform: false
  allow_override: false
examples:
  - '100001'
  - '100042'
  - '101234'
```

### Example 3: Category, Sequence, and Variant

A scheme with a variant element and freeform CPNs allowed. Because the variant is a system input, `element_mappings.variant` is declared.

```yaml
version: '1.0'
schema_type: cpn_generation_scheme

elements:
  - type: list
    name: category
    required: true
    values:
      - id: "410"
        name: Screws
        description: Mechanical fasteners

  - type: constant
    name: separator
    required: true
    value: "-"

  - type: numeric_counter
    name: sequence
    required: true
    attachedTo: [category]
    format:
      min_value: 1
      max_value: 9999

  - type: constant
    name: variant_separator
    required: true
    value: "-"

  - type: list
    name: variant
    required: true
    values: ["A", "B", "C"]

settings:
  element_mappings:
    category: category
    variant: variant
  allow_override: true
  allow_freeform: true
  freeform_validation:
    pattern: "^[A-Z]{2,4}-\\d{4,6}$"
    max_length: 20
    description: "Format: 2-4 letters, hyphen, 4-6 digits"

examples:
  - "410-0001-A"
  - "410-0001-B"
```

## Validation Rules

When you save a scheme, Duro rejects it if any of these rules is broken:

1. `version`, `schema_type`, `settings`, `elements` and `examples` are all present.
2. `version` matches `^\d+\.\d+$`.
3. `schema_type` is `cpn_generation_scheme` or `cpn_generation_scheme_custom`.
4. Every element has a `type` and a `name`. Top-level `list`, counter and `group` elements also have `required`.
5. Lists have `values`, constants have `value`, counters have `format.min_value` and `format.max_value`, and groups have at least one element.
6. `min_value` is ≥ 0 for numeric counters. Hex counter values match `^[0-9A-F]+$`. Alpha counter values match `^[A-Z]+$`.
7. Template references match `^\$\{\{\s*[\w\.]+\s*\}\}$`.
8. Groups do not contain groups.
9. `allow_freeform: true` requires `allow_override: true`.
10. `freeform_validation` requires both `allow_override: true` and `allow_freeform: true`, and its `max_length` is between 1 and 50.
11. A reusable group contains exactly one counter, whose `attachedTo` lists every non-constant, non-counter element in the group and nothing else.
12. At least one example CPN is provided.

These are not checked when you save, but a scheme that breaks them will not generate the CPNs you expect:

* Give every element a unique `name`.
* Keep each counter's `min_value` ≤ `max_value`.
* Declare `element_mappings.category` whenever a list uses `${{ duro.categories }}`.

## Best Practices

* **Structure**
  * Declare `elements` before `settings` so the structural shape of the CPN reads top-down.
  * Place required elements before optional ones.
  * Group related elements together with `group`.
* **Mappings**
  * Always declare `settings.element_mappings.category` for category-driven schemes. Without it, generation will fail at runtime even though the scheme is otherwise valid.
* **Validation**
  * Constrain list elements by their `values`. A `validation.pattern` on a list is accepted but not enforced, so it documents intent only.
  * Size counter ranges generously for future growth.
* **Documentation**
  * Include descriptions on list values when the `id` is opaque.
  * Provide diverse examples covering edge cases.


---

# 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/cpn-schema-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.
