Add x-sap-ai-hint extension#41
Open
Fannon wants to merge 7 commits into
Open
Conversation
Fannon
commented
May 12, 2026
| } | ||
| }, | ||
| { | ||
| "paths": [ |
Member
Author
There was a problem hiding this comment.
Intended to have both: Different casing in OpenAPI 2 vs 3
zwedoc
reviewed
May 28, 2026
| - **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
Member
Author
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
zwedoc
reviewed
May 29, 2026
Co-authored-by: Juan Aguado <juan.aguado.calvo@gmail.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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