SKU (Semantic Module)

← Back to Modules Reference

The SKU (Stock Keeping Unit) semantic module standardizes how product, part, and inventory identifiers are formatted, validated, and generated across your system.

Rather than relying on manual data entry or ad-hoc formatting scripts, tagging a property with SKU automatically enforces consistent uppercase casing, prepends organizational prefixes (e.g., PROD-), blocks placeholder names (like TEST or SAMPLE), enforces database uniqueness, and can even automatically generate SKUs from product titles when new records are created.

Technical Specifications

Attribute	Specification
Scope	`Property` (Applied to a text or string property)
Data Type	`String`
Default Case	`uppercase` (Converts all inputs to uppercase)
Validation Standard	Strict alphanumeric with hyphens and underscores
Uniqueness	Enforced by default (`enforceUniqueness: true`)
Auto-Generation	Supported (Generates random unique codes or derives from source properties)

Key Capabilities

1. Automatic Prefix Enforcement (`prefix`)

Many businesses organize catalogs by category or department prefixes (such as PROD-, PART-, or SKU-):

If a prefix is configured, the Serverless Engine checks incoming values.
If a client enters 10045, the engine automatically prepends the prefix to produce PROD-10045.
If the client already included the prefix (e.g. prod-10045), the engine avoids duplicating it.

2. Case Normalization (`caseMode`)

To prevent warehouse scanning mistakes or duplicate items resulting from mixed casing:

uppercase (Default): Automatically converts inputs to uppercase (e.g., nike-air-max $\rightarrow$ NIKE-AIR-MAX).
lowercase: Converts all inputs to lowercase.
preserve: Leaves the author’s casing unchanged.

3. Validation Modes (`strict`, `lenient`, `custom`)

You can control the exact character set permitted for your inventory codes:

strict (Default): Permits only letters (A-Z), numbers (0-9), hyphens (-), and underscores (_). Rejects spaces and special symbols.
lenient: Allows additional separator characters (such as periods .).
custom: Allows you to provide a custom regular expression pattern (via customPattern) to match existing corporate barcoding standards.

4. Reserved Values Blocklist (`validateReservedWords`)

To prevent accidental test data or placeholder entries from polluting production inventory:

By default, the engine blocks common dummy values such as ADMIN, TEST, NULL, DEFAULT, SAMPLE, and DEMO.
Custom reserved values can be specified in the configuration.

5. Automated SKU Generation (`autoGenerate`)

When creating new catalog items, you can allow the system to generate SKUs automatically if omitted in the POST payload:

Derived from Another Property: Set autoGenerateSource to another property key (such as name or title). Creating a product with name "Blue Cotton T-Shirt" automatically generates a clean slug SKU like PROD-BLUE-COTTON-T-SHIRT.
Random Unique Identifier: If no source property is specified, the system generates a secure 12-character unique alphanumeric identifier.

Configuration Options

When configuring the SKU semantic in the Domain Modeler, you can customize the following parameters:

Option	Type	Default	Description
`validationMode`	`'strict'` \| `'lenient'` \| `'custom'`	`'strict'`	Validation rules governing permitted characters.
`customPattern`	`string`	`undefined`	Custom regex pattern used when validationMode is `'custom'`.
`caseMode`	`'uppercase'` \| `'lowercase'` \| `'preserve'`	`'uppercase'`	Automated casing transformation applied to values.
`prefix`	`string`	`undefined`	Prefix automatically prepended to the SKU if missing.
`enforceUniqueness`	`boolean`	`true`	Enforces global uniqueness across all records of this entity.
`autoGenerate`	`boolean`	`false`	Automatically generates a SKU on `Create` if omitted by the client.
`autoGenerateSource`	`string`	`undefined`	Entity property key (e.g. `'name'`) used to derive the auto-generated SKU.
`validateReservedWords`	`boolean`	`true`	Checks candidate SKUs against a blocklist of reserved values.
`reservedValues`	`string[]`	`['ADMIN', 'TEST', 'SAMPLE', ...]`	List of disallowed placeholder words.

API Lifecycle Examples

1. Automatic Formatting & Prefixing

Assume prefix: "PROD-" and caseMode: "uppercase" are configured. A client sends a raw SKU in lowercase without a prefix:

POST /products
Content-Type: application/json

{
  "name": "Wireless Mouse",
  "sku": "wm-black-01"
}

Server Response (201 Created): The SKU is automatically transformed into uppercase with the prefix attached:

{
  "data": {
    "id": "prod_550",
    "name": "Wireless Mouse",
    "sku": "PROD-WM-BLACK-01"
  }
}

2. Auto-Generation on Create

With autoGenerate: true, autoGenerateSource: "name", and prefix: "ITEM-", a client omits the SKU entirely:

POST /products
Content-Type: application/json

{
  "name": "Noise Cancelling Headphones"
}

Server Response (201 Created):

{
  "data": {
    "id": "prod_551",
    "name": "Noise Cancelling Headphones",
    "sku": "ITEM-NOISE-CANCELLING-HEADPHONES"
  }
}

3. Validation Failure (Reserved Value)

A user tries to enter a placeholder value:

{
  "name": "Test Product",
  "sku": "SAMPLE"
}

Server Response (422 Unprocessable Entity):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 422,
  "code": "E_VALIDATION_ERROR",
  "detail": "SKU cannot use reserved value: SAMPLE"
}

Validation Rules & Modeling Guidelines

String Properties Only: The SKU semantic module can only be applied to a String or Text property.
Property Length Constraints: String properties default to a Maximum Length of 255 characters in the Domain Modeler, which provides plenty of space for long prefixed SKUs. If you customize the Maximum Length constraint, ensure it can accommodate your prefix plus expected code lengths.
Uniqueness Safeguards: Because SKUs typically identify physical stock items, enforceUniqueness: true prevents multiple products from sharing the same identifier.