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

# Introduction to Duro's Config System

## Evolution of Duro's Configuration

Duro started as an "out of the box" PLM solution that worked well for hardware teams transitioning from spreadsheets. However, as organizations scaled and required deeper customization, we recognized the need for a more flexible approach. Instead of maintaining hard-coded rules, we developed a powerful configuration system that puts control in our users' hands.

## The YAML-Based Configuration

Our "YAML all the things" philosophy enables extensive customization while maintaining Duro's core value of simplicity. Using YAML's human-readable format, you can configure:

* Category definitions and their attributes
* Data validation rules
* Custom revision and status workflows
* Configurable part numbering schemes
* Change order validation and approval flows
* Change order stage notifications (`notifyList`)

```yaml
# Example: a complete category registry with one category and one attribute
version: '3.0'
schema_type: categories_scheme
attributes:
  - name: Length
    type: string
    pattern: "^\\d+(\\.\\d+)?\\s*(mm|m)$"
attributeGroups: []
categories:
  - name: Cable Assembly
    code: '920'
    type: ASSEMBLY
    defaults:
      - $ref: '#/attributes/Length'
categoryGroups: []
```

## Why YAML?

We chose YAML for its:

* **Readability**: Clean, intuitive syntax that's easy to understand
* **Accessibility**: Approachable for both technical and non-technical users
* **Flexibility**: Supports complex configurations without overwhelming complexity
* **Industry adoption**: Widely used in tools like GitHub Actions and Kubernetes

Our configuration system draws inspiration from proven approaches like [GitHub Actions](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions), [Render.com Blueprints](https://render.com/docs/blueprint-spec), and [JSON Schema](https://json-schema.org/), combining their best aspects into a cohesive configuration definition system for your product data.

## Library Configurations

Each library has three configurations, one of each type:

| Config type  | What it defines                                              | Reference                                                                                      |
| ------------ | ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| `CATEGORIES` | Categories, attributes, attribute groups and category groups | [Category Registry](https://docs.durohub.com/library-configuration/registry.md)                |
| `REVISION`   | Lifecycle statuses and the revision format for each          | [Revision Scheme](https://docs.durohub.com/library-configuration/revisions.md)                 |
| `ID`         | How component part numbers (CPNs) are generated              | [CPN Schema Reference](https://docs.durohub.com/library-configuration/cpn-schema-reference.md) |

Change order templates are configured separately — see [Change Order Workflows](https://docs.durohub.com/library-configuration/change-order-workflows.md).

## Applying a Configuration

You can edit a library's configurations in the Duro web app under Library settings, or through the API. Both API mutations below require the `library.categories.manage` permission (see [RBAC](https://docs.durohub.com/advanced-topics/rbac.md)) and apply to the library named in the `x-library` header. Using the EU or GovCloud region? Use your region's host — see [Endpoints](https://docs.durohub.com/readme.md#endpoints).

### Upload your own YAML

`config.updateLibrary` validates a YAML (or JSON) document and saves it as the library's configuration of `configType`, replacing the current one.

```graphql
mutation SaveRegistry($yaml: String!) {
  config {
    updateLibrary(
      input: { configType: CATEGORIES, yamlConfig: $yaml, acknowledgeWarnings: false }
    ) {
      success
      configSaved
      message
      errors
      warnings {
        type
        name
        reason
        affectedCount
      }
      restoredYamlConfig
    }
  }
}
```

* When the document is invalid, `success` is `false` and `errors` lists every problem. Nothing is saved.
* Some problems are warnings rather than errors, such as two category names that are singular and plural forms of the same word. They block the save (`success: false`, listed in `warnings`) until you send the document again with `acknowledgeWarnings: true`.
* Set `validateOnly: true` to run every check without saving. Warnings are reported instead of blocking, and `configSaved` is `false`.

The mutation reports problems in the response rather than as GraphQL errors, so always check `success`.

### Apply a preset

`config.updateLibraryPresets` applies one or more of Duro's shipped configurations:

```graphql
mutation ApplyPresets {
  config {
    updateLibraryPresets(input: { presets: [REVISION_STANDARD, ID_SEMI_INTELLIGENT] }) {
      success
      message
      results {
        preset
        success
        message
      }
    }
  }
}
```

| Preset                | Config type  | Description                                                       |
| --------------------- | ------------ | ----------------------------------------------------------------- |
| `CATEGORIES_DEFAULT`  | `CATEGORIES` | Duro's default category registry.                                 |
| `REVISION_SIMPLE`     | `REVISION`   | Single-segment revisions.                                         |
| `REVISION_STANDARD`   | `REVISION`   | `A.1` style revisions.                                            |
| `REVISION_COMPLEX`    | `REVISION`   | `A1.0` style revisions with a documentation segment.              |
| `ID_SEMI_INTELLIGENT` | `ID`         | Category code plus a 5-digit sequence per category (`410-00001`). |
| `ID_NON_INTELLIGENT`  | `ID`         | A plain 6-digit sequence (`100001`).                              |

A `CATEGORIES` or `REVISION` preset replaces the library's current configuration of that type. An `ID` preset only applies to a library that has no CPN scheme yet; otherwise its result has `success: false`. Each preset reports its own result in `results`. `configPresets(configType: REVISION)` lists the presets for a config type.

### Read a configuration

`configs(filter: { type: REVISION })` returns the library's configurations; its `yaml` field is the saved document in the form `updateLibrary` accepts back.

```graphql
query ReadRevisionScheme {
  configs(filter: { type: REVISION }) {
    id
    type
    updatedAt
    yaml
  }
}
```

## Getting Started

If you're new to YAML, we recommend these resources:

* [YAML Syntax Overview](https://yaml.org/spec/1.2.2/)
* [Learn YAML in 10 minutes](https://learnxinyminutes.com/docs/yaml/)
* [YAML Tutorial by CloudBees](https://www.cloudbees.com/blog/yaml-tutorial-everything-you-need-get-started)

The following sections will guide you through configuring various aspects of your Duro environment, starting with the Category Registry.


---

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