CPN Schema Reference

Overview

This document provides a complete reference for the CPN (Component Part Number) Schema YAML specification. The schema defines the structure and constraints for CPN generation schemes in the Duro PLM system.

Schema Information

• Schema Version: 1.0

• JSON Schema: https://json-schema.org/draft-07/schema#

• Type: Object

Root Level Properties

Property	Type	Required	Description
version	string	Yes	Version of the CPN schema. Must match pattern ^\d+\.\d+$
schema_type	string	Yes	Must be "cpn_generation_scheme"
settings	object	Yes	Global settings for CPN generation
elements	array	Yes	Array of element definitions
examples	array	Yes	Array of example CPNs that follow the scheme

Settings Object

The settings object contains global configuration options for CPN generation.

settings:
  allow_override: boolean
  allow_freeform: boolean
  case_sensitive: boolean

Property	Type	Required	Description
allow_override	boolean	Yes	Whether manual CPN override is allowed
allow_freeform	boolean	Yes	Whether freeform CPNs are allowed
case_sensitive	boolean	Yes	Whether CPNs are case-sensitive

Elements

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

• List Element

• Constant Element

• Numeric Counter

• Hex Counter

• Group Element

Common Element Properties

All elements share these base properties:

Property	Type	Required	Description
type	string	Yes	Element type identifier
name	string	Yes	Unique name for the element
required	boolean	No	Whether the element is required

List Element

- type: "list"
  name: string
  required: boolean
  use: string
  values: (string[] | object[] | template_string)
    validation:
      pattern: string

Property	Type	Required	Description
values	array|string	Yes	Array of values or template reference
validation.pattern	string	No	Regex pattern for additional validation

Values can be one of:

• Array of strings

• Array of objects with id, name, and optional description

• Template reference in format ${{namespace.field}}

List Element Examples

- type: "list"
  name: "category"
  required: true
  use: "id"  # Optional: use when values have id/name pairs
  values:
    # Simple string array
    - "410"
    - "591"
    - "423"

    # OR object array with metadata
    - id: "410"
      name: "Screws"
      description: "Mechanical fasteners"
    - id: "591"
      name: "Resistors"
      description: "Electronic components"

    # OR reference to system values
    values: ${{ duro.categories }}

  validation:
    pattern: "^\\d{3}$"  # Optional regex pattern

Constant Element

- type: "constant"
  name: string
  required: boolean
  value: string

Property	Type	Required	Description
value	string	Yes	The constant value

Constant Element Example

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

Numeric Counter

- type: "numeric_counter"
  name: string
  required: boolean
  attachedTo: string[]
  format:
    min_value: integer
    max_value: integer

Property	Type	Required	Description
attachedTo	array	No	Names of elements this counter is attached to
format.min_value	integer	Yes	Minimum value (must be ≥ 0)
format.max_value	integer	Yes	Maximum value

Numeric Counter Example

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

Hex Counter

type: "hex_counter"
name: string
required: boolean
attachedTo: string[]
format:
  min_value: string
  max_value: string

Property	Type	Required	Description
attachedTo	array	No	Names of elements this counter is attached to
format.min_value	string	Yes	Minimum value in hex (pattern: ^[0-9A-F]+$)
format.max_value	string	Yes	Maximum value in hex (pattern: ^[0-9A-F]+$)

Hex Counter Example

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

Group Element

Combines multiple elements, useful for optional sections.

type: "group"
name: string
required: boolean
elements: array

Property	Type	Required	Description
elements	array	Yes	Array of nested element definitions

Group elements can contain any other element type, including:

• List elements

• Constant elements

• Free text elements (only available within groups)

• Numeric counters

• Hex counters

Group Element Example

- type: "group"
  name: "variant group"
  required: false
  elements:
    - type: "constant"
      name: "separator"
      value: "."
    - type: "free"
      name: "variant"
      validation:
        pattern: "^\\w{1,10}$"

Free Text Element (Group Only)

- type: "free"
  name: string
  validation:
    pattern: string
    max_length: integer

Property	Type	Required	Description
validation.pattern	string	Yes	Regex pattern for validation
validation.max_length	integer	Yes	Maximum length of the text

Examples Array

The examples array must contain at least one example CPN that follows the defined scheme.

examples:
  - "410-0001"
  - "ELEC-591-0042.variant"

Template References

Template references allow dynamic value lists to be pulled from the system:

values: "${{ namespace.field }}"

Template references must match the pattern: ^\$\{\{\s*[\w\.]+\s*\}\}$. Currently, the only supported namespace is duro. and the only supported fields are categories and families.

Complete Schema Example

$schema: "https://json-schema.org/draft-07/schema#"
version: "1.0"
schema_type: "cpn_generation_scheme"

name: "Duro Default Intelligent Part Number"
settings:
  allow_override: false
  allow_freeform: false
  case_sensitive: true
  elements:
    - type: list
      name: category
      required: true
      use: id
      values:
        - id: "410"
          name: Screws
          description: Mechanical fasteners
      validation:
        pattern: "^\\d{3}$"
    - type: constant
      name: separator
      required: true
      value: "-"
    - type: numeric_counter
      name: sequence
      required: true
      attachedTo: [category]
      format:
        min_value: 1
        max_value: 9999
  examples:
    - "410-0001"

Validation Rules

1. Version must match pattern ^\d+\.\d+$

2. Schema type must be exactly "cpn_generation_scheme"

3. All referenced element names must be unique within their scope

4. Counter ranges must be valid (min ≤ max) and min must be ≥ 0

5. Hex counter values must be valid hexadecimal strings

6. Template references must match the specified pattern

7. At least one example CPN must be provided

8. Group elements must contain at least one element

9. Free text elements can only appear within groups

10. All elements must be valid and referenced correctly

11. Groups can be optional even if they contain required elements

Best Practices

• Structure

  • Place required elements before optional ones

  • Group related elements together

  • Use consistent naming conventions

• Validation

  • Always include regex patterns for list values

  • Set appropriate counter ranges for your volume

  • Consider case sensitivity implications

• Documentation

  • Include descriptions for all list values

  • Provide diverse examples

  • Comment complex regex patterns

• Maintenance

  • Use template references for shared value sets

  • Keep counter ranges generous for future growth

  • Consider versioning implications