> 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/revisions.md).

# Revision Scheme

## Overview

The revision scheme configuration defines the lifecycle statuses a library's components can be in, and the format of the revision value for each status. It lets you:

* Define custom statuses (name, color, description) and map each one to one of Duro's five lifecycle stages
* Give each status its own revision format: a required `major` segment and optional `minor` and `documentation` segments
* Choose the type, range, default value, padding and delimiter of each segment
* Exclude confusing characters with a blacklist

A library has one revision scheme, saved as its `REVISION` configuration. You can start from one of Duro's presets or upload your own (see [Applying a configuration](https://docs.durohub.com/library-configuration/introduction.md#applying-a-configuration)).

## Schema

### Basic Structure

A revision scheme has four required root keys: `version`, `schema_type`, `defaults` and `schemes`.

```yaml
version: '1.0'
schema_type: revision_scheme_config_custom

defaults:
  empty_value: '-'
  blacklist: [I, O, Q, S, X, Z]
  min_int_value: 1
  max_int_value: 999
  min_letter_value: 'A'
  max_letter_value: 'ZZ'

schemes:
  design:
    - name: Design
      color: '#4491DD'
      maps_to: DESIGN
      segments:
        major:
          type: LETTER
          default_value: 'A'
          delimiter: '.'
        minor:
          type: INTEGER
          min_int_value: 1
          max_int_value: 999
          default_value: '1'
      examples: ['A.1', 'A.2', 'B.1']
  development: []
  production: []
  maintenance: []
  obsolete: []
```

| Key           | Required | Description                                                                                                                                                                               |
| ------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `version`     | Yes      | Version of the document, matching `^\d+\.\d+$` (for example `'1.0'`).                                                                                                                     |
| `schema_type` | Yes      | `revision_scheme_config_custom` for a scheme you write yourself. The presets use `revision_scheme_config_simple`, `revision_scheme_config_standard` and `revision_scheme_config_complex`. |
| `defaults`    | Yes      | Library-wide defaults for segment ranges, the empty value and the blacklist. May be empty (`{}`).                                                                                         |
| `schemes`     | Yes      | The statuses, grouped by lifecycle stage.                                                                                                                                                 |

### Defaults

`defaults` holds values every segment falls back to when it doesn't set its own.

| Key                | Type      | Description                                                                                                                                                                                                |
| ------------------ | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `empty_value`      | string    | The revision shown when a component has no revision value. Duro's presets use `'-'`.                                                                                                                       |
| `blacklist`        | string\[] | Characters no revision value may contain. See [Character Blacklist](#character-blacklist).                                                                                                                 |
| `min_int_value`    | integer   | Lowest value of an integer segment.                                                                                                                                                                        |
| `max_int_value`    | integer   | Highest value of an integer segment. Defaults to 999.                                                                                                                                                      |
| `min_letter_value` | string    | Lowest value of a letter segment.                                                                                                                                                                          |
| `max_letter_value` | string    | Highest value of a letter segment.                                                                                                                                                                         |
| `segment`          | object    | Per-segment defaults under `major`, `minor` and `documentation`. Each accepts `type`, `min_int_value`, `max_int_value`, `max_digits`, `min_letter_value`, `max_letter_value`, `delimiter` and `blacklist`. |

### Lifecycle Stages and Statuses

`schemes` groups your statuses under Duro's five lifecycle stages. The stage keys are `design`, `development`, `production`, `maintenance` and `obsolete`, and they always come in that order: it is the order of the lifecycle, and the order Duro shows statuses in. Each key holds a list of statuses; an empty list (`[]`) means the stage has no statuses of its own.

Each status has these properties, and no others:

| Property      | Required | Description                                                                                                                                                                                   |
| ------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | Yes      | Display name of the status, such as `Prototype`.                                                                                                                                              |
| `maps_to`     | Yes      | The lifecycle stage: `DESIGN`, `DEVELOPMENT`, `PRODUCTION`, `MAINTENANCE` or `OBSOLETE`. It must match the stage key the status is listed under (`maps_to: DEVELOPMENT` under `development`). |
| `segments`    | Yes      | The revision format for this status. `major` is required; `minor` and `documentation` are optional.                                                                                           |
| `color`       | No       | Display color, such as `'#DF9428'`.                                                                                                                                                           |
| `description` | No       | A description of the status.                                                                                                                                                                  |
| `examples`    | No       | Example revision values for this status. Duro does not check them, so keep them accurate by hand.                                                                                             |

Saving the scheme makes the library's statuses match it, in the order they are listed. Within a stage you can list several statuses, for example `Alpha` and `Beta` both mapped to `DEVELOPMENT`.

{% hint style="info" %}
How a component moves between statuses is not part of this configuration. Duro works out the revision for a new status from the component's last released revision; the scheme only sets the format each status uses. To gate status changes, use [change order validations](https://docs.durohub.com/library-configuration/change-order-validations.md).
{% endhint %}

### Segments

A revision value is made of up to three segments, in this order: `major`, `minor` and `documentation`.

| Property           | Applies to          | Description                                                                                                                                         |
| ------------------ | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `type`             | all                 | `LETTER`, `INTEGER` or `EITHER` (uppercase).                                                                                                        |
| `min_letter_value` | `LETTER`, `EITHER`  | Lowest letter value, such as `'A'`.                                                                                                                 |
| `max_letter_value` | `LETTER`, `EITHER`  | Highest letter value, such as `'ZZ'`.                                                                                                               |
| `min_int_value`    | `INTEGER`, `EITHER` | Lowest integer value.                                                                                                                               |
| `max_int_value`    | `INTEGER`, `EITHER` | Highest integer value.                                                                                                                              |
| `max_digits`       | `INTEGER`, `EITHER` | Zero-pads integer values to this many digits (or to the number of digits in `max_int_value`, if that is more). Without it, integers are not padded. |
| `default_value`    | all                 | The value the segment starts at when a component enters the status.                                                                                 |
| `delimiter`        | all                 | The character placed **after** this segment, before the next one.                                                                                   |
| `blacklist`        | all                 | Characters this segment may not contain. Replaces the global blacklist for the segment.                                                             |

#### Segment Types

**`LETTER`** — a letter value between `min_letter_value` and `max_letter_value`:

```yaml
major:
  type: LETTER
  min_letter_value: 'A'
  max_letter_value: 'ZZ'
  default_value: 'A'
```

**`INTEGER`** — a whole number between `min_int_value` and `max_int_value`:

```yaml
minor:
  type: INTEGER
  min_int_value: 1
  max_int_value: 99
  max_digits: 2       # 01, 02 … 99
  default_value: '1'
```

**`EITHER`** — a letter or an integer. Set both ranges:

```yaml
major:
  type: EITHER
  min_int_value: 1
  max_int_value: 999
  min_letter_value: 'A'
  max_letter_value: 'ZZZ'
  default_value: '1'
```

#### Delimiters

A delimiter belongs to the segment it follows. Put `delimiter: '.'` on `major` to get `A.1`; put it on `minor` instead, with no delimiter on `major`, to get `A1.0` (major `A`, minor `1`, documentation `0`). When a segment has no delimiter, the next segment follows it directly, so give adjacent undelimited segments different types (a letter followed by an integer) so the value can be split where letters change to digits.

```yaml
segments:
  major:
    type: LETTER
    default_value: 'A'          # no delimiter: minor follows directly
  minor:
    type: INTEGER
    default_value: '1'
    delimiter: '.'              # '.' between minor and documentation
  documentation:
    type: INTEGER
    min_int_value: 0
    default_value: '0'
```

This produces `A1.0`, `A1.1`, `B2.0`.

### Character Blacklist

List characters to exclude from revision values under `defaults` (for the whole scheme) or on a single segment (which replaces the global list for that segment). Every Duro preset blacklists `I`, `O`, `Q`, `S`, `X` and `Z`.

```yaml
defaults:
  blacklist:
    - I  # Avoid confusion with 1
    - O  # Avoid confusion with 0
    - Q  # Avoid confusion with 0
    - S  # Avoid confusion with 5
    - X
    - Z
```

A revision value containing a blacklisted character is rejected. A scheme whose `default_value` contains a blacklisted character is rejected when you save it.

## Presets

Duro ships three revision presets. Apply one with `updateLibraryPresets` (see [Applying a configuration](https://docs.durohub.com/library-configuration/introduction.md#applying-a-configuration)); applying a revision preset replaces the library's current revision scheme. All three define the statuses Design, Prototype, Production and Obsolete, and no maintenance statuses.

| Preset              | `schema_type`                     | Format                                                                                                                                         |
| ------------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `REVISION_SIMPLE`   | `revision_scheme_config_simple`   | One segment. Design and Obsolete take a number or letters (`1`, `A`), Prototype takes numbers (`1`, `2`), Production takes letters (`A`, `B`). |
| `REVISION_STANDARD` | `revision_scheme_config_standard` | Letter major, `.`, integer minor: `A.1`, `A.2`, `B.1`.                                                                                         |
| `REVISION_COMPLEX`  | `revision_scheme_config_complex`  | Letter major, integer minor, `.`, integer documentation: `A1.0`, `A1.1`, `B2.0`.                                                               |

Here is the standard preset in full:

```yaml
version: '1.0'
schema_type: revision_scheme_config_standard
defaults:
  empty_value: '-'
  blacklist: [I, O, Q, S, X, Z]
  max_int_value: 999
  min_int_value: 1
  max_letter_value: 'ZZ'
  min_letter_value: 'A'
schemes:
  design:
    - name: Design
      color: '#4491DD'
      maps_to: DESIGN
      segments:
        major:
          type: LETTER
          min_letter_value: 'A'
          max_letter_value: 'ZZ'
          default_value: 'A'
          delimiter: .
        minor:
          type: INTEGER
          min_int_value: 1
          max_int_value: 999
          default_value: '1'
  development:
    - name: Prototype
      color: '#DF9428'
      maps_to: DEVELOPMENT
      segments:
        major:
          type: LETTER
          min_letter_value: 'A'
          max_letter_value: 'ZZ'
          default_value: 'A'
          delimiter: .
        minor:
          type: INTEGER
          min_int_value: 1
          max_int_value: 999
          default_value: '1'
  production:
    - name: Production
      color: '#49c641'
      maps_to: PRODUCTION
      segments:
        major:
          type: LETTER
          min_letter_value: 'A'
          max_letter_value: 'ZZ'
          default_value: 'A'
          delimiter: .
        minor:
          type: INTEGER
          min_int_value: 1
          max_int_value: 999
          default_value: '1'
  maintenance: []
  obsolete:
    - name: Obsolete
      color: '#888888'
      maps_to: OBSOLETE
      segments:
        major:
          type: LETTER
          min_letter_value: 'A'
          max_letter_value: 'ZZ'
          default_value: 'A'
          delimiter: .
        minor:
          type: INTEGER
          min_int_value: 1
          max_int_value: 999
          default_value: '1'
```

## Common Patterns

### Numeric Prototypes, Lettered Production

Prototype revisions count `1`, `2`, `3`; production revisions are letters.

```yaml
version: '1.0'
schema_type: revision_scheme_config_custom
defaults:
  empty_value: '-'
  blacklist: [I, O, Q, S, X, Z]
schemes:
  design:
    - name: Design
      maps_to: DESIGN
      segments:
        major: { type: INTEGER, min_int_value: 1, max_int_value: 999, default_value: '1' }
  development:
    - name: Prototype
      maps_to: DEVELOPMENT
      segments:
        major: { type: INTEGER, min_int_value: 1, max_int_value: 999, default_value: '1' }
  production:
    - name: Production
      maps_to: PRODUCTION
      segments:
        major: { type: LETTER, min_letter_value: 'A', max_letter_value: 'ZZ', default_value: 'A' }
  maintenance: []
  obsolete:
    - name: Obsolete
      maps_to: OBSOLETE
      segments:
        major:
          type: EITHER
          min_int_value: 1
          max_int_value: 999
          min_letter_value: 'A'
          max_letter_value: 'ZZ'
          default_value: 'A'
```

### Two Development Statuses

Several statuses can share a lifecycle stage. Here `Alpha` and `Beta` are both development statuses, and `Beta` revisions are zero-padded to two digits.

```yaml
schemes:
  development:
    - name: Alpha
      color: '#DF9428'
      maps_to: DEVELOPMENT
      segments:
        major: { type: INTEGER, min_int_value: 1, max_int_value: 99, default_value: '1' }
      examples: ['1', '2', '3']
    - name: Beta
      color: '#E8B04A'
      maps_to: DEVELOPMENT
      segments:
        major: { type: INTEGER, min_int_value: 1, max_int_value: 99, max_digits: 2, default_value: '01' }
      examples: ['01', '02', '10']
```

## Checking a Revision Value

To check whether a revision value is valid for a status, find the status's `id` and pass it to `revision.isValidRevisionValue`. Using the EU or GovCloud region? Use your region's host — see [Endpoints](https://docs.durohub.com/readme.md#endpoints).

```graphql
query StatusesAndCheck($statusId: String!) {
  customStatuses(filter: { isArchived: false }) {
    id
    name
    mapsTo
  }
  revision {
    isValidRevisionValue(input: { statusId: $statusId, revisionValue: "B.2" }) {
      isValid
      errorMessage
    }
  }
}
```

## Best Practices

1. **Revision Format**
   * Keep formats simple and intuitive
   * Use consistent delimiters
   * Consider future scaling needs when you set ranges
2. **Lifecycle Stages**
   * List every status under the stage its `maps_to` names
   * Limit revision format changes between stages
3. **Validation**
   * Blacklist confusing characters
   * Set appropriate value ranges
   * Keep each `default_value` inside its segment's range and free of blacklisted characters
4. **Documentation**
   * Include examples for each status
   * Document special cases in the status `description`


---

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