Summary (Semantic Module)

← Back to Modules Reference

The Summary semantic module is designed for brief, plain-text excerpts, card subtitles, social media teasers, and SEO meta descriptions.

Unlike full-length description fields, summaries frequently populate RSS feeds, preview cards, and search engine snippets where raw HTML or excessive length can break page layouts. Decorating a property with Summary enforces strict HTML blocking (preventing markup injection) and validates configured character boundaries.

Technical Specifications

Attribute	Specification
Scope	`Property` (Applied to a text property)
Data Type	`String`
HTML Sanitization	Disallowed (Strictly rejects all HTML, script, or markup tags)
Boundary Fencing	Validates configured `minimum` and `maximum` character constraints
Whitespace Handling	Automatically trimmed; whitespace-only strings convert to `null`

Key Capabilities

1. Strict Plaintext & XSS Fencing

Because summaries often feed into external web previews, search meta tags, or mobile notifications, they must never contain unrendered HTML. If an incoming payload contains any HTML tag (such as <p>, <b>, or <script>), the Serverless Engine rejects the request immediately with 400 Bad Request.

2. Character Length Boundary Validation

In the Domain Modeler, you can configure Minimum Length and Maximum Length rules for the property (for instance, restricting an SEO summary between 50 and 160 characters). The Summary semantic runner actively enforces these bounds during Create and Update operations.

3. Difference Between Summary and Description

Summary: Strictly plaintext, short excerpt (e.g. 1–2 sentences) with HTML blocking and boundary checks.
Description: General long-form body text without markup restrictions.

API Lifecycle Examples

1. Creating a Valid Plain-Text Summary

A client submits an article teaser:

POST /posts
Content-Type: application/json

{
  "title": "Getting Started with API Now",
  "summary": "Learn how to build, deploy, and scale robust serverless APIs in minutes without writing code."
}

Server Response (201 Created):

{
  "data": {
    "id": "post_101",
    "title": "Getting Started with API Now",
    "summary": "Learn how to build, deploy, and scale robust serverless APIs in minutes without writing code."
  }
}

2. Validation Failure (HTML Detected)

A client attempts to submit HTML formatting in the summary:

{
  "summary": "This summary has <b>bold tags</b> in it."
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Property 'summary' cannot contain HTML tags or markup."
}

3. Validation Failure (Exceeding Maximum Length)

If the property has a Maximum Length of 160 characters:

{
  "summary": "This summary is far too long for a concise excerpt. It continues on and on without providing a tight, focused synopsis of the underlying article content, easily exceeding the maximum length constraint."
}

Server Response (400 Bad Request):

{
  "type": "https://docs.apinow.app/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "code": "E_VALIDATION_ERROR",
  "detail": "Property 'summary' must not exceed 160 characters."
}

Validation Rules & Modeling Guidelines

Applicable Property Types: Apply to a String property in the Domain Modeler.
SEO Best Practices: Set the property’s Maximum Length constraint to 160 characters if you intend to use this field for search engine meta descriptions.