Describing Objects for AI Agents and API Consumers
Liferay DXP 2026.Q4+
You can add a localized description to an object definition, an object field, an object relationship, and a standalone object action. Liferay DXP generates a REST API for each published object, along with an OpenAPI document that describes the API’s fields and operations. Liferay DXP writes each description into that document.
The MCP server builds its tool descriptions from those documents, so AI agents and API consumers receive your description along with the object’s field names. Add a description when an object, field, relationship, or action needs more context than its name provides.
Adding a Description
You can describe an object definition, a field, a relationship, or a standalone action. Each one has a Description field:
| Element | Where the Description Field Is |
|---|---|
| Object definition | The Details tab |
| Field | The field’s side panel, which opens when you click the field on the Fields tab |
| Relationship | The relationship’s form, which opens when you click the relationship on the Relationships tab |
| Standalone action | The action’s Basic Info tab, which opens when you click the action on the Actions tab |
You can also add descriptions for object definitions, fields, and relationships in the Model Builder.
You can’t add a description while creating a field or relationship. The Description field appears once it’s saved.
On a one-to-many relationship, the child object’s relationship field shows the relationship’s description, and its own Description field is disabled. To change the description, edit the relationship. A many-to-many relationship from an object to itself appears twice on the Relationships tab and shares one description, which you edit on the first entry.
Each language keeps its own description. To add one in another language, click the language flag on the Description field, choose the language, enter the description, and click Save.
The OpenAPI document uses the en_US description. If there isn’t one, it uses the description in the object definition’s default language. If neither exists, the element has no description. The requesting user’s language never applies.
Where Descriptions Appear in the OpenAPI Document
To view an object’s OpenAPI document, open the API Explorer at [server]:[port]/o/api (for example, localhost:8080/o/api). Click REST Applications and select the object’s API, which uses the c/[pluralobjectlabel] naming pattern (for example, c/tickets).
Liferay DXP places each description in the object’s OpenAPI document according to the element it describes.
| Description On | Appears in the OpenAPI Document As |
|---|---|
| Object definition | The description of the object’s schema under components.schemas |
| Field | The description of the field’s property in the object’s schema |
| Relationship | The description of the schema property named after the relationship |
| Standalone action | The description of the action’s PUT operations under paths, by ID and by external reference code |
A relationship’s description appears in the documents of both related objects. On a one-to-many relationship, it also appears on the child object’s relationship field property. This property’s name starts with r_, such as r_[relationship name]_c_[parent object name]Id.
What Cannot Carry a Description
Nine framework metadata fields take no description: createDate, creator, displayDate, expirationDate, externalReferenceCode, id, modifiedDate, reviewDate, and status. The UI hides their Description field, and the API ignores a description sent for one of them.
Additionally, an unmodifiable system object’s definition and system fields take no description in the UI. A custom field or relationship you add to the object carries its description into the owning application’s OpenAPI document. A system action’s Description field is disabled.
Modifiable system objects take descriptions the same way custom objects do.
Managing Descriptions Through the Object Admin API
Descriptions are part of the object definition JSON, so exporting and importing an object definition preserves them.
The Object Admin API returns and accepts descriptions as language maps. The map is in the description property of ObjectDefinition, ObjectField, ObjectRelationship, and ObjectAction. For example, this body in a PATCH request to http://localhost:8080/o/object-admin/v1.0/object-definitions/[objectDefinitionId] sets the definition’s en_US description:
{
"description": {
"en_US": "Claims raised against a warranty."
}
}
For ObjectAction, a plain string description isn’t accepted. You must send a language map.
For an action, a PUT request that omits description preserves the stored description. A PUT request that sends an empty map keeps it too. To clear an action’s description in one language, send that language with an empty string, such as {"en_US": ""}. When an action has no description, the API returns an empty object for its description.