Add x-sap-ai-hint extension#41
Conversation
| } | ||
| }, | ||
| { | ||
| "paths": [ |
There was a problem hiding this comment.
Intended to have both: Different casing in OpenAPI 2 vs 3
| - **Complementary** — when a `description` exists for human readers, use `x-sap-ai-hint` to add AI-specific context that would clutter or be out of place in the human-facing description: routing guidance, preconditions, side effects, related operations, or disambiguation against similar elements. | ||
| - **Standalone** — when no `description` is present (common for internal or machine-generated APIs), `x-sap-ai-hint` can serve as the sole description, written entirely for AI consumption rather than end-user documentation. | ||
|
|
||
| In both cases, the content should be optimized for an AI agent that needs to decide *whether* and *how* to use the element — not for a developer reading reference docs. |
There was a problem hiding this comment.
should we explicitly allow support for markdown content? If we plan to concentrate guidance on a single extension field it would be beneficial to allow such format to enable rich structures
There was a problem hiding this comment.
Good idea, we can explicitly call out that this MAY or SHOULD be markdown. In the end, it will be text in LLM context, but we know that LLMs understand markdown well - so it's a good recommendation
There was a problem hiding this comment.
MAY is enough IMO, SHOULD is kind of a light enforcement already.
Shall the length of a hint be reasonably limited?
As a reminder, we already have a limit for description fields to 4000 characters. We should keep in mind the token consumption.
Co-authored-by: Juan Aguado <juan.aguado.calvo@gmail.com>
| "x-sap-ai-hint": { | ||
| "type": "string", | ||
| "description": "Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotated element. Markdown is recommended but plain text is accepted. Intentionally kept separate from human-readable description fields so that end-user-facing documentation and AI-targeted guidance can evolve independently." | ||
| } |
There was a problem hiding this comment.
It would be better to have 1 definition of the custom field x-sap-ai-hint and collect all targets under paths`. It will simplify the maintenance.
| - **Complementary** — when a `description` exists for human readers, use `x-sap-ai-hint` to add AI-specific context that would clutter or be out of place in the human-facing description: routing guidance, preconditions, side effects, related operations, or disambiguation against similar elements. | ||
| - **Standalone** — when no `description` is present (common for internal or machine-generated APIs), `x-sap-ai-hint` can serve as the sole description, written entirely for AI consumption rather than end-user documentation. | ||
|
|
||
| In both cases, the content should be optimized for an AI agent that needs to decide *whether* and *how* to use the element — not for a developer reading reference docs. |
There was a problem hiding this comment.
MAY is enough IMO, SHOULD is kind of a light enforcement already.
Shall the length of a hint be reasonably limited?
As a reminder, we already have a limit for description fields to 4000 characters. We should keep in mind the token consumption.
3 participants
Added
x-sap-ai-hintextension for Info Object, Tag Object, Operation Object, Parameter Object, and Schema Object.descriptionfields so that end-user-facing documentation and AI-targeted guidance can evolve independently.Also adding CHANGELOG.md and retroactively the changes