Description (Semantic Module)

← Back to Modules Reference

The Description semantic module is designed for long-form plaintext properties, such as product descriptions, project overviews, author biographies, or notes.

Unlike concise title or summary fields, Description properties typically hold paragraphs of text. Tagging a property with Description ensures that multi-line inputs are properly handled, leading and trailing whitespace is automatically trimmed, and empty submissions are converted to clean null values.

---

Technical Specifications

Attribute	Specification
Scope	Property (Applied to a text property)
Data Type	String
Intended Content	Multi-line plaintext paragraphs, bio sections, and item overviews
Whitespace Handling	Automatically trimmed on Create and Update
Empty Input Handling	Blank strings ("") convert to null

---

Key Capabilities

1. Long-Form Text Formatting

Provides an ideal home for multi-sentence product descriptions, terms of service excerpts, or operational notes that do not require rich markup formatting.

2. Automatic Whitespace Sanitization

Strips accidental whitespace from the start and end of multi-paragraph inputs without altering intentional paragraph line breaks inside the body.

3. Difference Between Description and Summary

• Use Description for comprehensive, detailed explanations and full-length body copy.
• Use Summary for brief, plain-text excerpts, SEO meta descriptions, and subtitle teasers where strict HTML blocking and length boundaries are required.
• Use Markdown or HTML if your content requires rich formatting, hyperlinks, bold text, or lists.

---

API Lifecycle Examples

1. Creating a Product Description

A client submits a multi-line product overview:

POST /products
Content-Type: application/json

{
  "name": "Ergonomic Office Chair",
  "description": "Engineered for all-day comfort with lumbar support, breathable mesh, and adjustable armrests."
}

Server Response (201 Created):

{
  "data": {
    "id": "prod_440",
    "name": "Ergonomic Office Chair",
    "description": "Engineered for all-day comfort with lumbar support, breathable mesh, and adjustable armrests."
  }
}

---

2. Validation Failure (Invalid Type)

If a client submits a non-string value (such as a structured object):

{
  "description": { "text": "Invalid payload format" }
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Property 'description' must be a string."
}

---

Validation Rules & Modeling Guidelines

• Applicable Property Types: Apply to a String property in the Domain Modeler.
• Length Capacity: Standard string properties default to 255 characters. For long-form descriptions spanning multiple paragraphs, increase the Maximum Length in the property panel or leave it unconstrained for unlimited text storage.