Add AI vocabulary with AI.hint as first property.#169
Conversation
|
| description: This is the interface description of @AI. | ||
| type: object | ||
| definitions: | ||
| "@AI.hint": |
There was a problem hiding this comment.
One thing that I usually tend to focus on is to clarify the scope and purpose of any extension. In this case, if the objective is to guide AI consumers "on how to use or interpret the annotation target", I would suggest to use @AI.instructions or `@Ai.usageHints" so users clearly understand the purpose of it by just looking at the extension name.
Again, I do like the propose one, just my two cents.
| title: AI Document | ||
| description: This is the interface description of @AI. | ||
| type: object | ||
| definitions: |
There was a problem hiding this comment.
Just dropping a few additional thoughts on AI-related “hints” that could be useful to consider:
- @AI.intent → short “when to use” (task framing)
- @AI.recoveryHints → runtime guidance for expected error scenarios (e.g., when → do )
- @AI.preconditions → required states / data
- @AI.postconditions → what changes in the system
- @AI.sideEffects → explicit side effects (external actions, observable state changes beyond outcome..)
- @AI.idempotency → behavior + retry semantics (safe, conditional, unsafe, etc.)
I prefer starting light, but could help make the overall model a bit more expressive and useful for agents.
There was a problem hiding this comment.
Good ideas / suggestions! The first two would fit well into the @ai. scope, the other ones feel like they're more general, so I would expect them more like in an @API.* scope?
frankejoe
left a comment
frankejoe
left a comment
There was a problem hiding this comment.
I also prefer to start small with a single annotation in which we can add all kinds of stuff. Guess we will be able to distinguish with the string field the different use cases similar to what you do for claude skills where you also just define a single markdown file.
What information I could imagine would be helpful:
- Usage hints: analytics, search, ...
- Example values: A few sample values for key columns
- Synonym mappings: revenue / sales / ...
- Safety rules: Always limit to top 100
- Pairs of natural language and resulting sql
But as said - I guess we can add all these into the AI.hint
Adds annotations overview table, usage examples at entity/property and service level, best practices section adapted for CDS context (entity semantics, navigation, service authorization — not operation-level pre/post-conditions), and cross-reference to x-sap-ai-hint for JSON-based formats.
5 participants
Added
@AIannotation vocabulary for AI consumption hints@AI.hint: Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret an Entity, Type, or Service — kept separate from human-readable@EndUserTextdescriptionsWe'll have to create related annotations for other formats, e.g.
x-sap-ai-hintfor JSON Schema based standards like OpenAPI