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

# Category Registry

## Overview

The category registry is the library configuration that organizes and validates your product data. It defines:

* **Attributes** — the fields a component can carry, such as `Length` or `Voltage`, with their type, unit and constraints
* **Attribute groups** — named sets of attributes you can attach to several categories at once
* **Categories** — the kinds of component in your library, each with a code, a type and the attributes it shows
* **Category groups** — headings that organize categories, such as Mechanical or Electrical

This registry serves as the foundation for maintaining clean, well-structured product data that can scale with your organization. Part numbering is configured separately, in the library's CPN scheme — see the [CPN Schema Reference](https://docs.durohub.com/library-configuration/cpn-schema-reference.md).

A library has one registry, saved as its `CATEGORIES` configuration. New libraries can start from Duro's default registry (the `CATEGORIES_DEFAULT` preset, about 120 categories) or upload their own. See [Applying a configuration](https://docs.durohub.com/library-configuration/introduction.md#applying-a-configuration).

## Schema

The registry is a YAML (or JSON) document with six required root keys, and no others:

| Key               | Type   | Description                                                                         |
| ----------------- | ------ | ----------------------------------------------------------------------------------- |
| `version`         | string | Version of the document, matching `^\d+\.\d+$`. Duro's default registry is `'3.0'`. |
| `schema_type`     | string | Always `categories_scheme`.                                                         |
| `attributes`      | array  | Attribute definitions.                                                              |
| `attributeGroups` | array  | Attribute group definitions. May be empty (`[]`).                                   |
| `categories`      | array  | Category definitions.                                                               |
| `categoryGroups`  | array  | Category group definitions. May be empty (`[]`).                                    |

A minimal, complete registry:

```yaml
version: '3.0'
schema_type: categories_scheme
attributes:
  - name: Length
    type: number
    unit: mm
    measurement_type_key: length
    min: 0
attributeGroups: []
categories:
  - name: Cable Assembly
    code: '920'
    type: ASSEMBLY
    defaults:
      - $ref: '#/attributes/Length'
categoryGroups: []
```

### Define Attributes

Attributes are defined once, in the top-level `attributes` array, and referenced from attribute groups and categories. Attribute names must be unique across the registry, ignoring case.

```yaml
attributes:
  - name: Voltage
    type: string
    pattern: "^\\d+(\\.\\d+)?\\s*V$"
    description: "A number followed by V (e.g., 5V, 3.3V)"

  - name: PPAP Level
    type: number
    min: 1
    max: 5
    description: "Production Part Approval Process level (1-5)"

  - name: Material
    type: list
    options: [Plastic, Metal, Glass, Ceramic, Wood, Composite]
    description: "One of the allowed materials"

  - name: Conductors
    type: number
    measurement_type_key: count
    min: 1
    max: 100
    description: "Number of conductors (1-100)"
```

| Property               | Required | Description                                                                                                                                                                                                                                                        |
| ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`                 | Yes      | Unique name, used in `$ref`s and shown on the component page.                                                                                                                                                                                                      |
| `type`                 | Yes      | One of the [attribute types](#attribute-types).                                                                                                                                                                                                                    |
| `unit`                 | No       | Unit the value is stored in, such as `mm` or `V`.                                                                                                                                                                                                                  |
| `measurement_type_key` | No       | Links the attribute to a measurement type (such as `length`, `mass`, `currency` or `count`) so values entered in other units are converted. Query `measurementTypeQuery { all { key name units } }` for the full list. With `count`, values must be whole numbers. |
| `min`, `max`           | No       | Lowest and highest allowed value of a `number` attribute. When the attribute has a measurement type, a value entered in another unit is converted before it is compared.                                                                                           |
| `options`              | No       | Allowed values of a `list` attribute.                                                                                                                                                                                                                              |
| `pattern`              | No       | Regular expression the value must match. Applies to `string`, `url`, `email`, `phone` and `color` attributes.                                                                                                                                                      |
| `requiresUniqueValue`  | No       | When `true`, no two components in the library may have the same value for this attribute. Defaults to `false`.                                                                                                                                                     |
| `description`          | No       | Explanation shown with the attribute.                                                                                                                                                                                                                              |
| `icon`, `color`        | No       | Display icon and color (`#RRGGBB` or `#RRGGBBAA`).                                                                                                                                                                                                                 |

Values that break a constraint are rejected when a component is created or updated, and the error names the attribute.

{% hint style="info" %}
Attributes contributed by an integration (for example Onshape or NetSuite fields) are added by enabling the integration, not by declaring them in YAML. `id`, `source`, `sourceKey` and `integrationId` are reserved: an attribute or attribute group that sets any of them is rejected.
{% endhint %}

### Attribute Types

| Type                       | Holds                                                                        |
| -------------------------- | ---------------------------------------------------------------------------- |
| `string`                   | Text. Constrain it with `pattern`.                                           |
| `number`                   | A number. Constrain it with `min`, `max`, `unit` and `measurement_type_key`. |
| `boolean`                  | `true` or `false`.                                                           |
| `date`, `time`, `datetime` | An ISO 8601 date, time or date-time.                                         |
| `list`                     | One of the values in `options`.                                              |
| `color`                    | A color.                                                                     |
| `email`                    | An email address.                                                            |
| `url`                      | A URL.                                                                       |
| `phone`                    | A phone number.                                                              |
| `item_link`                | A link to another component (its UUID).                                      |

### Define Attribute Groups

An attribute group is a named set of attributes. Attach a group to a category to give it every attribute in the group.

```yaml
attributeGroups:
  - name: Dimensions
    icon: cube-outline
    attributes:
      - $ref: '#/attributes/Length'
      - $ref: '#/attributes/Width'
      - $ref: '#/attributes/Height'
```

| Property                       | Required | Description                                         |
| ------------------------------ | -------- | --------------------------------------------------- |
| `name`                         | Yes      | Unique group name. `System Attributes` is reserved. |
| `attributes`                   | Yes      | `$ref`s to entries in `attributes`.                 |
| `description`, `icon`, `color` | No       | Display metadata.                                   |

### Define Categories

```yaml
categories:
  - name: Cable Assembly
    code: '920'
    type: ASSEMBLY
    icon: cable-data
    description: Cables with connectors fitted
    categoryGroup:
      $ref: '#/categoryGroups/Assembly'
    attributeGroups:
      - $ref: '#/attributeGroups/Dimensions'
    defaults:
      - $ref: '#/attributes/Conductors'
      - $ref: '#/attributes/Material'
```

| Property                       | Required | Description                                                                                                                                                                |
| ------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`                         | Yes      | Unique category name.                                                                                                                                                      |
| `code`                         | Yes      | Unique category code (string or number), ignoring case. Quote numeric codes (`'920'`) to keep leading zeros. A category-driven CPN scheme uses the code as the CPN prefix. |
| `type`                         | Yes      | `ASSEMBLY`, `PART` or `DOCUMENT`. See [Category Types](#category-types).                                                                                                   |
| `categoryGroup`                | No       | `$ref` to one entry in `categoryGroups`.                                                                                                                                   |
| `attributeGroups`              | No       | `$ref`s to entries in `attributeGroups`.                                                                                                                                   |
| `defaults`                     | No       | `$ref`s to individual entries in `attributes`.                                                                                                                             |
| `description`, `icon`, `color` | No       | Display metadata.                                                                                                                                                          |

### Category Types

Every category has one of three types:

| Type       | Use for                                     |
| ---------- | ------------------------------------------- |
| `ASSEMBLY` | Items with a bill of materials.             |
| `PART`     | Individual parts, mechanical or electrical. |
| `DOCUMENT` | Documentation items.                        |

To separate mechanical, electrical or software categories, put them in [category groups](#define-category-groups) rather than giving them different types.

### Define Category Groups

```yaml
categoryGroups:
  - name: Mechanical
    icon: cog
    description: Mechanical categories
  - name: Electrical
    icon: flash
    description: Electrical categories
  - name: Assembly
    icon: view-grid-plus
    description: Assembly categories
```

| Property                       | Required | Description        |
| ------------------------------ | -------- | ------------------ |
| `name`                         | Yes      | Unique group name. |
| `description`, `icon`, `color` | No       | Display metadata.  |

A category joins a group through its own `categoryGroup` reference, and belongs to at most one group.

### References

Entries point at each other with `$ref`. There are three forms, each naming an entry by its `name`:

| Reference                          | Used in                                                 |
| ---------------------------------- | ------------------------------------------------------- |
| `$ref: '#/attributes/<name>'`      | `attributeGroups[].attributes`, `categories[].defaults` |
| `$ref: '#/attributeGroups/<name>'` | `categories[].attributeGroups`                          |
| `$ref: '#/categoryGroups/<name>'`  | `categories[].categoryGroup`                            |

A reference must name an entry defined in the same document. References to other files or libraries, and wildcards, are not supported.

```yaml
categories:
  - name: Bolt
    code: '411'
    type: PART
    categoryGroup:
      $ref: '#/categoryGroups/Mechanical'
    attributeGroups:
      - $ref: '#/attributeGroups/Threaded Fastener'
    defaults:
      - $ref: '#/attributes/Material'
```

### Assign Attributes to Groups and Category Defaults

Attribute groups (`attributeGroups[].attributes`) and per-category default attributes (`categories[].defaults`) let you control which attributes appear on a component page and how they are grouped. When you save a category configuration, Duro validates these assignments before persisting them.

{% hint style="warning" %}
**System attributes cannot be placed in attribute groups or category defaults.** A system attribute referenced in a user-defined `attributeGroups[].attributes` list or in `categories[].defaults` is rejected, and the configuration save fails validation. System attributes are already rendered in a fixed location on the component page, so assigning them to a group or default would place the same attribute in two places — which is not allowed for any attribute. The attribute group name `System Attributes` is reserved for them.
{% endhint %}

{% hint style="info" %}
**Unresolved attribute references fail validation.** If an entry in `attributeGroups[].attributes` or `categories[].defaults` references an attribute that cannot be resolved, the save is rejected with a validation error. Any previously saved defaults are left intact.
{% endhint %}

## Saving the Registry

Duro checks a registry in this order when you save it (see [Applying a configuration](https://docs.durohub.com/library-configuration/introduction.md#applying-a-configuration) for the mutation):

1. **Errors** block the save and are returned in `errors`: a document that doesn't match the schema, an unresolved `$ref`, two categories with the same name or code (ignoring case), two attributes, attribute groups or category groups with the same name (ignoring case), a system attribute in a group or a category's defaults, or an attribute named like a system or integration attribute.
2. **Name warnings** block the save until you acknowledge them: two names that are singular and plural forms of the same word (`Bracket` and `Brackets`), or that look very similar. The response has `success: false` and the list in `warnings`. Send the same document again with `acknowledgeWarnings: true` to save it.
3. **Items in use are kept.** If the new registry drops a category or attribute that components still use, Duro keeps it, saves the rest, and returns a warning for each kept item with `affectedCount` (the number of components using it). `restoredYamlConfig` holds the document as saved, with the kept items put back.

After a save, Duro applies the registry to the library's categories and attributes in the background. `configSyncStatus(type: CATEGORIES) { isSynced }` reports when that has finished.

## Reading the Configuration via the API

Read the saved registry with the `configs` query. Using the EU or GovCloud region? Use your region's host — see [Endpoints](https://docs.durohub.com/readme.md#endpoints).

```graphql
query CategoryRegistry {
  configs(filter: { type: CATEGORIES }) {
    id
    isSynced
    yaml
    config {
      ... on CategoriesConfig {
        version
        categories {
          name
          code
          type
          defaults
          attributeGroups
        }
        attributes {
          name
          type
          unit
          min
          max
          options
          pattern
        }
        attributeGroups {
          name
          attributes
        }
      }
    }
  }
}
```

* `yaml` is the registry exactly as you saved it, in the form `config.updateLibrary` accepts back. Edit it and save it to change the registry.
* `config` is the registry as Duro uses it: your content plus the system and integration attributes, which carry a `source` field. If you save this form back, Duro strips the system and integration content before validating.

{% hint style="info" %}
`CategoriesConfig.attributeGroups` always resolves to a list. When no attribute groups are defined it returns an empty list (`[]`), never `null`, so you can iterate over it directly without a null check. The schema still declares the field as nullable, so generated client types mark it optional.
{% endhint %}


---

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