# Category Registry

## Overview

The category & specs registry is a powerful configuration system that helps you organize and validate your product data. It enables you to:

* Define component categories with standardized attributes and specifications
* Import pre-built category templates from Duro's standard library
* Create custom validation rules and constraints for your parts data
* Establish consistent part numbering schemes across your library
* Enforce data quality standards through automated validation

This registry serves as the foundation for maintaining clean, well-structured product data that can scale with your organization.

## Schema

The category & specs registry is defined in a YAML file that is used to define the relationships between your part specifications and their constraints (ie. validation rules).

As a Library Registry Maintainer, you'll have the ability to define, override, and extend the structure of your library parts, and author custom validations on the specification values directly or in relation to other specifications.

### Import Default Category Sets

Import pre-defined category sets from Duro to leverage existing definitions.

```yaml
uses:
  - duro/mechanical-categories@v1
  - duro/electrical-categories@v1.0.1
```

### Exclude Specific Categories

Selectively exclude specific categories from imported sets that aren't relevant to your library.

```yaml
excludes:
  - "Basic Electrical Component"  # Excludes category with name "Basic Electrical Component"
  - "Capacitance"                # Excludes category with name "Capacitance"
```

### Define Common Specifications

Create reusable specifications that can be referenced across multiple categories. Common specs are organized in a hierarchical structure:

```yaml
commonSpecs:
  dimensions:
    standard_length:
      name: "Length"
      type: "string"
      validation:
        pattern: "^\\d+(\\.\\d+)?\\s*(mm|cm|m|in)$"
        description: "Must be a number followed by a valid unit"

    standard_width:
      name: "Width"
      type: "string"
      validation:
        pattern: "^\\d+(\\.\\d+)?\\s*(mm|cm|m|in)$"
        description: "Must be a number followed by a valid unit"
```

### Define Custom Categories

Create new categories with specific attributes and specifications.

```yaml
categories:
  - code: "920"
    type: ASSEMBLY
    name: Cable Assembly
    shortName: CABLE
    unitOfMeasure: EACH
    specs:
      - $ref: "#/commonSpecs/dimensions/standard_length"
        required: "*"

      - name: Conductors
        type: integer
        required: "*"
        validation:
          minimum: 1
          maximum: 100
          description: "Number of conductors (1-100)"
```

### Define Category Type Specifications

Apply common specifications across all categories of a specific type. This helps maintain consistency and reduces repetition in your category definitions.

```yaml
categoryTypeSpecs:
  ASSEMBLY:
    - $ref: "#/commonSpecs/dimensions/*"  # Reference all dimension specs
      required: "Prototype"
    - $ref: "#/commonSpecs/physical/weight"
      required: Production
      severity: Warning
  ELECTRICAL:
    - $ref: "#/commonSpecs/electrical/*"  # Reference all electrical specs
    - $ref: "#/commonSpecs/quality/iso_certification"
      required: Production
```

You can:

* Reference entire specification groups using wildcards (`/*`)
* Reference individual specifications
* Set default required stages and severity levels
* Apply specifications across all categories of a specific type

This is particularly useful when:

* You want to enforce standard specifications across category types
* You need to maintain consistent validation rules
* You want to reduce repetition in your category definitions

### Implement Validation Rules

Define validation rules for specifications using different data types and formats.

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

  - name: PPAPLevel
    type: integer
    validation:
      minimum: 1
      maximum: 5
      description: "Production Part Approval Process level (1-5)"

  - name: Material
    type: string
    validation:
      enum: [Plastic, Metal, Glass, Ceramic, Wood, Composite]
      description: "Must be one of the specified materials"
```

### Specify Lifecycle Requirements

Define when specifications are required based on the item's lifecycle stage.

```yaml
specs:
  - name: NetsuiteItemId
    type: string
    required: "Production"
    validation:
      pattern: "^NS-\\d{8}$"
      description: "Must be NS- followed by 8 digits"

  - name: IONProcessTemplate
    type: string
    required: "Design"
    severity: "Warning"
    validation:
      pattern: "^TPL-[A-Z0-9]{8}$"
```

### Extend Existing Categories

Extend pre-defined categories with additional specifications or modifications.

```yaml
categories:
  - extends: duro/mechanical-categories/bearing@v1.0.0
    name: Custom Bearing # change the name for this category
    specs:
      - name: Surface Treatment
        type: string
        required: Production
        validation:
          enum: [Chrome, Nickel, Phosphate, None]
```

### Reference Common Specifications

Reuse common specifications across different categories using references.

```yaml
specs:
  - $ref: "#/commonSpecs/dimensions/standard_length"
    required: "*"
  - $ref: "#/commonSpecs/electrical/operating_temp_max"
    required: "Design"
```

### Import External Specifications

Use specifications defined in external libraries.

```yaml
specs:
  - $ref: "duro/electrical-categories/specs/voltage/input_voltage"
    required: Design
```

### Import Entire Specification Sets

Import all specifications from a set using the wildcard (\*) operator. This is useful when you need to include an entire group of related specifications.

```yaml
specs:
  # Imports all dimension specifications from Duro's mechanical specs
  - $ref: "duro/mechanical-categories/specs/dimensions/*"
    required: Prototype
    # This will include Height, Width, Length, Thickness, etc. as defined in the Duro specs
    # Each imported spec will maintain its validation rules while inheriting the required status
```

The wildcard import is particularly powerful when:

* You need all specifications from a logical grouping
* You want to maintain consistency with a standard specification set
* You want to reduce repetitive references to individual specifications

### Define Warning-Level Requirements

Specify requirements that trigger warnings rather than errors when not met.

```yaml
specs:
  - name: ERPCostCenter
    type: string
    required: "In Review"
    severity: "Warning"
    validation:
      pattern: "^CC-[A-Z]{2}-\\d{4}$"
```

### Create Integration Points

Define specifications for integration with external systems.

```yaml
specs:
  - name: JiraECO
    type: string
    validation:
      pattern: "^ECO-\\d{4}$"
      description: "Jira ECO number"

  - name: SAPMaterialNumber
    type: string
    validation:
      pattern: "^\\d{9}$"
      description: "Must be exactly 9 digits"
```

### Define Quality Control Requirements

Specify quality-related specifications and their validation rules.

```yaml
specs:
  - name: QualityInspectionFreq
    type: string
    required: "Production"
    validation:
      enum: [PerBatch, PerShift, Daily, Weekly, Monthly]
      description: "Frequency of quality inspections"

  - name: ISOCertification
    type: string
    required: "In Review"
    severity: "Warning"
    validation:
      pattern: "^ISO\\d{4,5}:\\d{4}$"
      description: "ISO certification number and year"
```

### Available Category Types

Define the type of category being created. The type affects validation rules and available specifications.

```yaml
categories:
  - code: "920"
    # Available types:
    type: MECHANICAL    # For mechanical parts and assemblies
    # OR
    type: ELECTRICAL    # For electrical components
    # OR
    type: ASSEMBLY      # For combined assemblies
    # OR
    type: DOCUMENT      # For documentation
    # OR
    type: SOFTWARE      # For software components
```

### Validation Types Reference

Define specifications using different validation types and formats.

#### String Validation

```yaml
commonSpecs:
  validation:
    # Pattern-based string validation
    - name: PartNumber
      type: string
      validation:
        pattern: "^[A-Z]{2}-\\d{6}$"
        description: "Must be 2 capital letters followed by 6 digits"

    # Enum-based string validation
    - name: Material
      type: string
      validation:
        enum: [Plastic, Metal, Glass, Ceramic]
        description: "Must be one of the allowed materials"

    # Unit-based measurements
    - name: Length
      type: string
      validation:
        pattern: "^\\d+(\\.\\d+)?\\s*(mm|cm|m|in)$"
        description: "Number with valid unit (e.g., 10mm, 2.5cm)"
```

#### Integer Validation

```yaml
commonSpecs:
  validation:
    # Range-based integer validation
    - name: Quantity
      type: integer
      validation:
        minimum: 1
        maximum: 1000
        description: "Must be between 1 and 1000"

    # Simple integer validation
    - name: PinCount
      type: integer
      validation:
        minimum: 1
        description: "Must be at least 1"
```

#### Paired Field Validation

```yaml
commonSpecs:
  dimensions:
    - name: Height
      type: paired
      components:
        value:
          name: "Height Value"
          type: integer
          validation:
            minimum: 0
            maximum: 999999
            description: "Numeric value for height"
        unit:
          name: "Height Unit"
          type: string
          validation:
            enum: ["mm", "cm", "m", "in"]
            description: "Unit for height measurement"
      display: "{value}{unit}"
```

#### Conditional Validation

```yaml
commonSpecs:
  conditional:
    # Example 1: Range-based conditional validation
    - name: ColorRange
      type: conditional
      components:
        color:
          name: "Color"
          type: string
          validation:
            enum: ["red", "blue", "green"]
            description: "Color selection"
        range:
          name: "Range Value"
          type: integer
          validation:
            description: "Range value"
            conditions:
              - when: "color == 'red'"
                minimum: 1
                maximum: 20
              - when: "color == 'blue'"
                minimum: 21
                maximum: 40
              - when: "color == 'green'"
                minimum: 41
                maximum: 50

    # Example 2: Enum-based conditional validation
    - name: Food Dye Color
      type: conditional
      display: "{baseColor} {number}"
      components:
        baseColor:
          name: "Base Color"
          type: string
          validation:
            enum: [Red, Yellow, Blue, Green]
            description: "Base color of the food dye"
        number:
          name: "Dye Number"
          type: integer
          validation:
            description: "FDA approved dye number for the selected color"
            conditions:
              - when: "baseColor == 'Red'"
                enum: [3, 40]
              - when: "baseColor == 'Yellow'"
                enum: [5, 6]
              - when: "baseColor == 'Blue'"
                enum: [1, 2]
              - when: "baseColor == 'Green'"
                enum: [3]
```

The conditional validation supports two types of validation rules:

1. **Range-based conditions**: Define minimum and maximum values based on another field's value
2. **Enum-based conditions**: Define specific allowed values based on another field's value

You can also specify a display format using the `display` property, which determines how the combined values should be presented. For example, `"{baseColor} {number}"` will show values like "Red 40" or "Yellow 5".

## Version Format Reference

When referencing external categories or specifications, you can use different version formats:

```yaml
uses:
  # Full semantic version
  - duro/mechanical-categories@v1.0.0

  # Minor version only (equivalent to latest patch)
  - duro/electrical-categories@v1.0

  # Major version only (equivalent to latest minor.patch)
  - duro/software-categories@v1
```

**Note:** Using shorter versions will automatically use the latest compatible version within that scope.