@Consumption

BETA This annotation is beta and should be reviewed for completion and correctness.

Introduction

Via those Annotations the specific behavior is defined which is related to the consumption of CDS content via domain-specific frameworks. This metadata makes no assumptions on the concrete consumption technology/infrastructure but is applicable across multiple consumption technologies (Analytics, OData, …).

`@Consumption.aiHint`

Targets: Entity, Type, Service (and their elements/properties)

@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.

Usage

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.

Schema Definitions

This is an extension vocabulary for CSN Interop Effective Document.
The interface is available as JSON Schema: consumption.schema.json.

Annotations Overview

Annotation	Scope	Description
@Consumption.valueHelpDefinition	Entity, Type	The property defines how value helps for this element shall be constructed. It allows to associate a (set of) View/Entity that provides the "Value Help" for the annotated field or parameter. This is achieved by either referencing the target view/entity of a modelled association or by directly establishing a relationship to view/entity that shall act as a value help provider.
@Consumption.hidden	Type	The annotated element shall be ignored by consumers.
@Consumption.aiHint	Entity, Type, Service	Provides a free-text hint for AI consumers (e.g., LLMs or AI agents) on how to use or interpret the annotated element. This allows keeping human-readable descriptions (e.g., `@EndUserText`) separate from guidance targeted specifically at AI consumers. The annotation value MUST NOT be displayed to end users and MUST be filtered when publishing metadata externally (e.g., to the SAP API Business Hub public catalog).

@Consumption.valueHelpDefinition

The property defines how value helps for this element shall be constructed.

It allows to associate a (set of) View/Entity that provides the "Value Help" for the annotated field or parameter. This is achieved by either referencing the target view/entity of a modelled association or by directly establishing a relationship to view/entity that shall act as a value help provider.

Scope: Entity, Type
Extending: EntityDefinition, BooleanType, StringType, LargeStringType, IntegerType, Int16Type, Integer64Type, UInt8Type, DecimalType, DoubleType, DateType, TimeType, DateTimeType, TimestampType, UUIDType, BinaryType, LargeBinaryType, AssociationType, CompositionType, CustomType, TypeDefinition, BooleanTypeDefinition, StringTypeDefinition, LargeStringTypeDefinition, IntegerTypeDefinition, Int16TypeDefinition, Integer64TypeDefinition, UInt8TypeDefinition, DecimalTypeDefinition, DoubleTypeDefinition, DateTypeDefinition, TimeTypeDefinition, DateTimeTypeDefinition, TimestampTypeDefinition, UUIDTypeDefinition, BinaryTypeDefinition, LargeBinaryTypeDefinition, AssociationTypeDefinition, CompositionTypeDefinition
Type: Array<Consumption Value Help Definition>

@Consumption.hidden

The annotated element shall be ignored by consumers.

Scope: Type
Extending: BooleanType, StringType, LargeStringType, IntegerType, Int16Type, Integer64Type, UInt8Type, DecimalType, DoubleType, DateType, TimeType, DateTimeType, TimestampType, UUIDType, BinaryType, LargeBinaryType, AssociationType, CompositionType, CustomType, TypeDefinition, BooleanTypeDefinition, StringTypeDefinition, LargeStringTypeDefinition, IntegerTypeDefinition, Int16TypeDefinition, Integer64TypeDefinition, UInt8TypeDefinition, DecimalTypeDefinition, DoubleTypeDefinition, DateTypeDefinition, TimeTypeDefinition, DateTimeTypeDefinition, TimestampTypeDefinition, UUIDTypeDefinition, BinaryTypeDefinition, LargeBinaryTypeDefinition, AssociationTypeDefinition, CompositionTypeDefinition
Type: boolean
Default Value: true

Consumption Value Help Definition

Type: Object(entity, additionalBinding, association, distinctValues)

Property	Type	Description
entity OPTIONAL	Consumption Value Help Definition	Value help defining view or entity.
additionalBinding OPTIONAL	Array<Additional Binding>	Additional bindings for filtering the value help result list.
association OPTIONAL	Element Reference	Reference to the modelled association (in local entity) for which the target view represents the value help providing view or entity for the annotated local field. The on-condition of the association may only contain bindings of the source and target fields that use an equal operator. All these bindings are automatically considered by the value help for both filter and result mappings. Mutually exclusive to the usage of `valueHelpDefinition.entity`.
distinctValues OPTIONAL	boolean	Specifies whether the value help result list shall only contain distinct values for the annotated field or parameter. If set to true all mappings will be used for filtering, but only the value for the field/parameter which the value help was requested for will be returned by the value help. Default Value: `true`

Example Values:

{
  "entity": {
    "name": "I_ControllingAreaStdVH",
    "element": "ControllingArea"
  }
}

{
  "entity": {
    "name": "I_CostCenterStdVH",
    "element": "CostCenter"
  },
  "additionalBinding": [
    {
      "localElement": "ControllingArea",
      "element": "ControllingArea"
    }
  ]
}

{
  "association": {
    "=": "to_Airline"
  }
}

Consumption Value Help Definition

Value help defining view or entity.

Type: Object(name, element)

Property	Type	Description
name OPTIONAL	string	Name of the value help providing view or entity
element OPTIONAL	string	Name of the field of the value help view or entity, which the annotated local field or parameter is bound to. Mutually exclusive to the usage of `valueHelpDefinition.association`.

Additional Binding

Allows to define additional bindings (besides the ones defined by valueHelpDefinition.association or valueHelpDefinition.entity) for filtering the value help result list and/or returning values from the selected value help record.

Type: Object(localElement, element, usage)

Property	Type	Description
localElement OPTIONAL	string	Field of the current view/entity; mutually exclusive to the usage of `localParameter`.
element OPTIONAL	string	Name of the field of the value help view or entity, which the annotated local field or parameter is bound to.
usage OPTIONAL	@Consumption.ConsumptionValueHelpDefinition.AdditionalBinding.Usage	The binding may either specify an additional filter-criterion on the value help list (`#FILTER`), or an additional result mapping for the selected value help record (`#RESULT`) or a combination thereof (`#FILTER_AND_RESULT`). If not specified explicitly the usage is `#FILTER_AND_RESULT`. If distinctValues is set to true, additional bindings must specify the usage as `#FILTER`.

@Consumption.ConsumptionValueHelpDefinition.AdditionalBinding.Usage

The binding may either specify an additional filter-criterion on the value help list (#FILTER), or an additional result mapping for the selected value help record (#RESULT) or a combination thereof (#FILTER_AND_RESULT). If not specified explicitly the usage is #FILTER_AND_RESULT. If distinctValues is set to true, additional bindings must specify the usage as #FILTER.

Type: Object(#)

Property	Type	Description
# MANDATORY	string	Provide the value in `{ "#": "<value>" }` enum notation. Default Value: `FILTER_AND_RESULT` Allowed Values: `"FILTER"` `"RESULT"` `"FILTER_AND_RESULT"`

Example Values:

{
  "#": "FILTER_AND_RESULT"
}

@Consumption.aiHint

Provides a free-text hint for AI consumers (e.g., LLMs or AI agents) on how to use or interpret the annotated element.

This allows keeping human-readable descriptions (e.g., @EndUserText) separate from guidance targeted specifically at AI consumers.

The annotation value MUST NOT be displayed to end users and MUST be filtered when publishing metadata externally (e.g., to the SAP API Business Hub public catalog).

Scope: Entity, Type, Service
Extending: EntityDefinition, BooleanType, StringType, LargeStringType, IntegerType, Int16Type, Integer64Type, UInt8Type, DecimalType, DoubleType, DateType, TimeType, DateTimeType, TimestampType, UUIDType, BinaryType, LargeBinaryType, AssociationType, CompositionType, CustomType, TypeDefinition, BooleanTypeDefinition, StringTypeDefinition, LargeStringTypeDefinition, IntegerTypeDefinition, Int16TypeDefinition, Integer64TypeDefinition, UInt8TypeDefinition, DecimalTypeDefinition, DoubleTypeDefinition, DateTypeDefinition, TimeTypeDefinition, DateTimeTypeDefinition, TimestampTypeDefinition, UUIDTypeDefinition, BinaryTypeDefinition, LargeBinaryTypeDefinition, AssociationTypeDefinition, CompositionTypeDefinition, ServiceDefinition
Type: string

Example Values:

"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."

Introduction​

@Consumption.aiHint​

Usage​

Best practices​

Schema Definitions​

Annotations Overview​

@Consumption.valueHelpDefinition​

@Consumption.hidden​

Consumption Value Help Definition​

Example Values:​

Consumption Value Help Definition​

Additional Binding​

@Consumption.ConsumptionValueHelpDefinition.AdditionalBinding.Usage​

Example Values:​

@Consumption.aiHint​

Example Values:​

Introduction

`@Consumption.aiHint`

Usage

Best practices

Schema Definitions

Annotations Overview

@Consumption.valueHelpDefinition

@Consumption.hidden

Consumption Value Help Definition

Example Values:

Consumption Value Help Definition

Additional Binding

@Consumption.ConsumptionValueHelpDefinition.AdditionalBinding.Usage

Example Values:

@Consumption.aiHint

Example Values: