PublicUniqueName (Semantic Module)

← Back to Modules Reference

The PublicUniqueName semantic module designates a string property as a public, human-readable identifier—commonly known as a slug or permalink.

Instead of exposing internal primary keys in user-facing URLs, decorating a property with PublicUniqueName enables clean, intuitive web addresses like https://example.com/articles/getting-started-with-api-now or https://example.com/products/wireless-noise-cancelling-headphones.

The API Now Serverless Engine automatically derives, normalizes, and sanitizes slugs from other properties (such as Title or Name), guarantees database-level uniqueness across multi-tenant schemas, and protects search engine optimization (SEO) rankings by preventing accidental URL breakage during record updates.

Technical Specifications

Attribute	Specification
Scope	`Property`
Data Type	`String`
Default Source Field	Property decorated with `Title`, falling back to `Name`
Default Separator	`'-'` (Hyphen)
Case Sensitivity	Case-insensitive by default (`caseSensitive: false`, lowercased)
Unicode Handling	ASCII-normalized by default (`allowUnicode: false`, transliterates accents)
Duplicate Policy	Unique by default (`allowDuplicates: false`, auto-appends `-1`, `-2`)
Database Constraint	Automatic `UNIQUE` index constraint generated on deployment

Key Capabilities

1. Automatic Slug Generation

When API consumers create a new record without supplying a slug, the engine automatically extracts the text from the configured sourceField (or auto-detected Title or Name property). If the primary source field is blank, the engine gracefully checks the configured fallbackField (such as a sku or code).

2. Intelligent Sanitization & Normalization

The engine standardizes text into web-safe URL segments:

Case Normalization: Converts all characters to lowercase by default ("My First Article" → "my-first-article").
Accent & Diacritic Stripping: Decomposes accents and transliterates international characters into English equivalents (e.g., "Café Crème" → "cafe-creme" and "München" → "munchen"), unless Unicode is explicitly enabled.
Special Character Removal: Strips invalid punctuation, symbols, and quotation marks.
Separator Consolidation: Replaces spaces, underscores, and consecutive separators with a single clean separator ("Hello --- World!" → "hello-world").
Trimming: Strips leading and trailing separators.

3. Collision Resolution & Deduplication

When multiple records share identical titles, the engine avoids database collisions without failing the client’s request:

If allowDuplicates is false (the default), the engine queries the tenant database table.
If "hello-world" already exists, the engine automatically increments a numeric suffix:
- First conflict: "hello-world-1"
- Second conflict: "hello-world-2"
- Subsequent conflicts: "hello-world-3", and so on.

4. SEO Preservation on Updates

A major risk with automated slugs is accidental URL mutation. If an editor corrects a typo in an article title six months after publication, changing the slug would break existing bookmarks, inbound backlinks, and search engine indexes:

When an existing record’s Title or Name is modified via PUT or PATCH, the engine does not regenerate the slug.
The slug remains stable and immutable unless the client explicitly supplies a new slug value in the update payload.
If a new slug is explicitly provided, the engine sanitizes it and deduplicates it against existing records (excluding the current record itself).

5. Manual Custom Overrides

API consumers and editorial teams can supply their own custom slugs during creation or updates (e.g., specifying "slug": "special-holiday-deals" instead of "black-friday-cyber-monday-special-holiday-deals"). The engine validates custom inputs against format rules and verifies uniqueness.

6. Clean RESTful Lookups

Because the deployment pipeline automatically creates a database UNIQUE index on properties annotated with PublicUniqueName, API endpoints can safely use the slug property for direct item lookups:

GET /api/v1/articles/getting-started-with-api-now

Configuration Options

When configuring the PublicUniqueName semantic in the Domain Modeler, you can customize the following properties:

Option	Type	Default	Description
`sourceField`	`string`	Field with `Title`/`Name`	Key or exposed name of the property to generate the slug from. Defaults to the first property annotated with `Title` (or `Name`).
`fallbackField`	`string`	`undefined`	Secondary property to use if the primary source field is empty (e.g., `sku` or `id`).
`separator`	`string`	`'-'`	Character used to separate words in the generated slug. Hyphens (`-`) are recommended for search engines.
`caseSensitive`	`boolean`	`false`	When `false`, forces all characters to lowercase. When `true`, preserves character casing.
`allowUnicode`	`boolean`	`false`	When `false`, strips diacritics and enforces ASCII-only characters. When `true`, retains international characters (e.g., `/produits/crème-brûlée`).
`allowDuplicates`	`boolean`	`false`	When `false`, guarantees global uniqueness across the tenant and appends numeric suffixes. When `true`, disables unique index creation.

API Lifecycle Examples

1. Automatic Generation on Create

The client sends a POST request with only a title:

POST /articles
Content-Type: application/json

{
  "title": "10 Tips for Effective API Design!"
}

Server Response (201 Created):

{
  "data": {
    "id": 42,
    "title": "10 Tips for Effective API Design!",
    "slug": "10-tips-for-effective-api-design"
  }
}

2. Conflict Resolution (Duplicate Titles)

Another author creates a post with the exact same title:

POST /articles
Content-Type: application/json

{
  "title": "10 Tips for Effective API Design!"
}

Server Response (201 Created):

{
  "data": {
    "id": 43,
    "title": "10 Tips for Effective API Design!",
    "slug": "10-tips-for-effective-api-design-1"
  }
}

3. Explicit Manual Slug Override

The client explicitly passes a tailored slug with surrounding spaces or formatting:

POST /articles
Content-Type: application/json

{
  "title": "The Comprehensive Guide to REST APIs in 2026",
  "slug": "  rest-guide-2026  "
}

Server Response (201 Created):

{
  "data": {
    "id": 44,
    "title": "The Comprehensive Guide to REST APIs in 2026",
    "slug": "rest-guide-2026"
  }
}

4. Stability on Record Update

An author updates the title of an existing post:

PUT /articles/42
Content-Type: application/json

{
  "title": "10 Tips for Modern & Effective API Design!"
}

Server Response (200 OK):

{
  "data": {
    "id": 42,
    "title": "10 Tips for Modern & Effective API Design!",
    "slug": "10-tips-for-effective-api-design"
  }
}

5. Validation Error (Missing Source & Slug)

If a client submits a create payload that omits the slug and also omits the required source property:

POST /articles
Content-Type: application/json

{
  "summary": "Article without a title or slug"
}

Server Response (422 Unprocessable Entity):

{
  "error": "Validation failed: The slug field 'slug' was omitted, and the source field 'title' (or fallback field) is also missing or empty.",
  "code": "E_VALIDATION_ERROR"
}

Best Practices for Domain Designers

Pair with Title or Name: When creating domain entities like BlogPost, Product, Category, or Project, ensure you define a property with the Title or Name semantic alongside your slug property.
Keep Defaults for Web SEO: Unless you have specialized internal numbering requirements, keep caseSensitive: false, separator: '-', and allowDuplicates: false. Search engines treat hyphens as standard word delimiters.
Use Fallbacks for E-commerce: For entities where titles might initially be blank (such as imported catalog drafts), configure a fallbackField pointing to a sku or barcode to ensure every item has a valid, deterministic public address.