-
Notifications
You must be signed in to change notification settings - Fork 7
Add AI vocabulary with AI.hint as first property. #169
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Fannon
wants to merge
8
commits into
main
Choose a base branch
from
add-ai-hint-extension
base: main
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
+125
−11
Open
Changes from all commits
Commits
Show all changes
8 commits
Select commit
Hold shift + click to select a range
7cdd584
Add AI vocabulary with AI.hint as first property.
Fannon ff27127
Add changelog entry
Fannon cafa6c4
Mention x-sap-ai-hint relation
Fannon ad708b2
Merge branch 'main' into add-ai-hint-extension
Fannon f2d64a5
Expand @AI.hint documentation with best practices and examples
Fannon e9da11e
Merge branch 'main' into add-ai-hint-extension
pavelkornev 48087ec
Merge branch 'main' into add-ai-hint-extension
pavelkornev 3298dcd
Rename @AI.hint to @Consumption.AIHint across CSN Interop spec
vyshnavigadamsetti File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -16,6 +16,7 @@ node_modules/ | |
| .cache | ||
| .docusaurus/ | ||
| tmp/ | ||
| .DS_Store | ||
|
|
||
| # Build | ||
| dist/ | ||
|
|
||
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
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,64 @@ | ||
| ## Introduction | ||
|
|
||
| The `@Consumption.AIHint` annotation provides AI-specific guidance targeted for AI consumers, such as large language models (LLMs) processing or reasoning over the data model. | ||
|
|
||
| This allows model owners to provide AI-specific context separately from human-readable descriptions (e.g., [`@EndUserText`](./end-user-text)), enabling richer and more accurate AI consumption of the data model without polluting end-user-facing labels or documentation. | ||
|
|
||
| ## Annotations Overview | ||
|
|
||
| | Annotation | Targets | Description | | ||
| | ----------------------- | --------------------- | -------------------------------------------------------------------------------- | | ||
| | `@Consumption.AIHint` | Entity, Type, Service | Free-text hint for AI consumers on how to use or interpret the annotated element | | ||
|
|
||
| ## `@Consumption.AIHint` | ||
|
|
||
| **Targets:** Entity, Type, Service (and their elements/properties, since a Type target implies its elements) | ||
|
|
||
| `@Consumption.AIHint` is a string annotation that provides guidance for AI consumers (e.g., LLMs or AI agents) on how to use or interpret the annotated element. It is intentionally kept separate from human-readable descriptions (e.g., `@EndUserText`) so that end-user-facing documentation and AI-targeted guidance can evolve independently. | ||
|
|
||
| The annotation value is intended for AI consumption only and MUST NOT be displayed to end users. It MUST be filtered when publishing metadata externally (e.g., to the SAP API Business Hub public catalog). | ||
|
|
||
| For JSON-based metadata formats, the corresponding property is [`x-sap-ai-hint`](https://github.tools.sap/CPA/sap-json-schema-specification/blob/main/extension-attributes/x-sap-ai-hint.md). | ||
|
|
||
| ### Usage | ||
|
|
||
| ```cds | ||
| entity SalesOrder : managed { | ||
| @Consumption.AIHint: 'Use this entity to retrieve sales order header data. Filter by CustomerID and CreatedAt for typical lookups. For line items, use the SalesOrderItem entity.' | ||
| key ID : UUID; | ||
| CustomerID : String(10); | ||
| @Consumption.AIHint: 'ISO 4217 three-letter currency code (e.g. USD, EUR). Never a symbol.' | ||
| TransactionCurrency : String(5); | ||
| @Consumption.AIHint: 'Integer status code: 1=Open, 2=InProcess, 3=Completed, 4=Cancelled. Do not infer status from other fields.' | ||
| LifecycleStatus : Integer; | ||
| } | ||
|
|
||
| service SalesService { | ||
| @Consumption.AIHint: 'Exposes sales order read and write operations. Use GET operations for lookups and reporting. Creating or modifying orders requires the SalesOrder.Write scope.' | ||
| entity SalesOrders as projection on SalesOrder; | ||
| } | ||
| ``` | ||
|
|
||
| ### Best practices | ||
|
|
||
| Unlike human-readable descriptions, `@Consumption.AIHint` can be explicit about data semantics and usage context that would clutter `@EndUserText` annotations. Focus on what an AI agent needs to decide _whether_ and _how_ to use the entity, type, or service. | ||
|
|
||
| Some useful things to include, depending on the target: | ||
|
|
||
| - **Entity/Type level** | ||
| - **Business context** — what business concept or domain object this entity represents | ||
| - **When to use vs. similar entities** — if multiple entities cover overlapping domains, state which is authoritative and under what conditions | ||
| - **Disambiguation** — when an entity or property name is misleading or overlaps with something similar | ||
| - **Format and value constraints** — coding standards (ISO, internal enums, picklists), what values are valid, how to interpret coded fields | ||
| - **Navigation and relationships** — how to traverse to related entities for common lookup patterns | ||
|
|
||
| - **Service level** | ||
| - **Scope and capabilities** — what business activities the service covers and which operations are available | ||
| - **Authorization** — required scopes or roles needed to read vs. write | ||
| - **When NOT to use** — if another service is preferred for a specific use case, state this explicitly to help agents route correctly | ||
|
|
||
| Structure `@Consumption.AIHint` values using **lightweight, semantically structured Markdown**: | ||
|
|
||
| - **Use consistent labels** — e.g., **Format:**, **When NOT to use:** — so AI systems can extract meaning beyond visual formatting. | ||
| - **Keep content atomic** — one idea per bullet or line; avoid long prose paragraphs. | ||
| - **Lightweight Markdown only** — bullets, bold labels, `inline code` for field names and identifiers. Avoid tables and deep nesting. |
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,34 @@ | ||
| $schema: "http://json-schema.org/draft-07/schema#" | ||
| $id: "https://sap.github.io/csn-interop-specification/spec-v1/ai.schema.json#" | ||
| title: Consumption.AIHint Document | ||
| description: This is the interface description of @Consumption.AIHint. | ||
| type: object | ||
| definitions: | ||
| "@Consumption.AIHint": | ||
| type: string | ||
| description: |- | ||
| Provides a hint for AI consumers (e.g., LLMs) on how to use or interpret the annotation target. | ||
|
|
||
| This allows keeping human-readable descriptions (e.g., `@EndUserText`) separate from | ||
| descriptions and hints targeted specifically for AI consumers. | ||
| examples: | ||
| - "Use this entity to look up current inventory levels by product and warehouse." | ||
| - "This field contains the ISO 4217 currency code, not a currency symbol." | ||
| x-extension-targets: | ||
| - Entity | ||
| - Type | ||
| - Service | ||
|
|
||
| examples: | ||
| - { | ||
| "csnInteropEffective": "1.2", | ||
| "$version": "2.0", | ||
| "definitions": | ||
| { | ||
| "SalesOrder": | ||
| { | ||
| "kind": "entity", | ||
| "@Consumption.AIHint": "Use this entity to retrieve sales order header data. Filter by CustomerID and CreatedAt for typical lookups.", | ||
| }, | ||
| }, | ||
| } | ||
Oops, something went wrong.
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.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just dropping a few additional thoughts on AI-related “hints” that could be useful to consider:
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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?