TOON AI Protocol Adapter Plugin for SAP CAP
Token-Oriented Object Notation (TOON) protocol adapter for SAP Cloud Application Programming Model (CAP)
Overview
The TOON AI Protocol Adapter Plugin extends SAP Cloud Application Programming Model (CAP) with support for the TOON (Token-Oriented Object Notation) format. This plugin provides automatic conversion between JSON and TOON format, optimizing data exchange for AI applications by typically reducing token counts while maintaining data integrity.
Key Features
- 🚀 Two Protocol Variants: REST-based (
toon) and OData-based (toon-odata) adapters
- 🔄 Bidirectional Conversion: Automatic JSON ↔ TOON format conversion
- 📊 Token Count Optimization: Built-in token statistics and smart content-type selection
- 🔧 Configurable Processing: Flexible request/response processing controls
- 📈 Performance Monitoring: Real-time token count comparison and logging
- 🔌 Plugin Architecture: Easy integration with existing CAP applications
Installation
npm install @geertjanklaps/cds-toon-ai-protocol-adapter
Dependencies
- @sap/cds: >=9 (peer dependency)
- @toon-format/toon: ^2.1.0
- tokenx: ^1.3.0
Quick Start
1. Basic Service Configuration
Define a CAP service with TOON protocol support:
// srv/my-service.cds
@protocol: ['toon']
service MyTOONService {
}
2. Alternative: OData + TOON Protocol
For OData compatibility with TOON optimization:
// srv/my-service.cds
@protocol: ['toon-odata']
service MyTOONODataService {
}
Protocol Endpoints
The plugin automatically creates endpoints for your services:
REST Protocol (@protocol: ['toon'])
- Base URL:
http://localhost:4004/toon/
- Service Path:
/toon/{service-name}/{function-or-action}
- Example:
GET /toon/my-toon-service/getData
OData Protocol (@protocol: ['toon-odata'])
- Base URL:
http://localhost:4004/toon-odata/
- Service Path:
/toon-odata/{service-name}/{function-or-action}
- Example:
GET /toon-odata/my-toon-odata-service/getData
Configuration
Configure the plugin behavior in your package.json:
{
"cds": {
"toonAdapter": {
"requestProcessingEnabled": false,
"responseProcessingEnabled": true,
"logTokenStatistics": true,
"autoDetermineResponseContentType": true
}
}
}
Configuration Parameters
| Parameter | Type | Default | Description |
|---|
requestProcessingEnabled | boolean | false | Enable automatic conversion of incoming TOON requests to JSON |
responseProcessingEnabled | boolean | true | Enable automatic conversion of JSON responses to TOON format |
logTokenStatistics | boolean | true | Log token count comparisons between JSON and TOON formats |
autoDetermineResponseContentType | boolean | true | Automatically choose between JSON/TOON based on token efficiency |
Usage Examples
Making Requests
JSON Request (Standard)
GET /toon-odata/catalog/Books?$select=createdAt,createdBy,modifiedAt,modifiedBy,ID,title,author_ID,genre_ID,stock,price,currency_code
Content-Type: application/json
Response Formats
JSON Response (auto-selected when more efficient)
{
"@odata.context": "$metadata#Books",
"value": [
{
"createdAt": "2026-01-25T18:27:05.907Z",
"createdBy": "anonymous",
"modifiedAt": "2026-01-25T18:27:05.907Z",
"modifiedBy": "anonymous",
"ID": 201,
"title": "Wuthering Heights",
"author_ID": 101,
"genre_ID": 11,
"stock": 12,
"price": 11.11,
"currency_code": "GBP"
},
{
"createdAt": "2026-01-25T18:27:05.907Z",
"createdBy": "anonymous",
"modifiedAt": "2026-01-25T18:27:05.907Z",
"modifiedBy": "anonymous",
"ID": 207,
"title": "Jane Eyre",
"author_ID": 107,
"genre_ID": 11,
"stock": 11,
"price": 12.34,
"currency_code": "GBP"
},
{
"createdAt": "2026-01-25T18:27:05.907Z",
"createdBy": "anonymous",
"modifiedAt": "2026-01-25T18:27:05.907Z",
"modifiedBy": "anonymous",
"ID": 251,
"title": "The Raven",
"author_ID": 150,
"genre_ID": 16,
"stock": 333,
"price": 13.13,
"currency_code": "USD"
},
{
"createdAt": "2026-01-25T18:27:05.907Z",
"createdBy": "anonymous",
"modifiedAt": "2026-01-25T18:27:05.907Z",
"modifiedBy": "anonymous",
"ID": 252,
"title": "Eleonora",
"author_ID": 150,
"genre_ID": 16,
"stock": 555,
"price": 14,
"currency_code": "USD"
},
{
"createdAt": "2026-01-25T18:27:05.907Z",
"createdBy": "anonymous",
"modifiedAt": "2026-01-25T18:27:05.907Z",
"modifiedBy": "anonymous",
"ID": 271,
"title": "Catweazle",
"author_ID": 170,
"genre_ID": 13,
"stock": 22,
"price": 150,
"currency_code": "JPY"
}
]
}
TOON Response (default when responseProcessingEnabled: true)
[5]{createdAt,createdBy,modifiedAt,modifiedBy,ID,title,author_ID,genre_ID,stock,price,currency_code}:
"2026-01-25T18:27:05.907Z",anonymous,"2026-01-25T18:27:05.907Z",anonymous,201,Wuthering Heights,101,11,12,11.11,GBP
"2026-01-25T18:27:05.907Z",anonymous,"2026-01-25T18:27:05.907Z",anonymous,207,Jane Eyre,107,11,11,12.34,GBP
"2026-01-25T18:27:05.907Z",anonymous,"2026-01-25T18:27:05.907Z",anonymous,251,The Raven,150,16,333,13.13,USD
"2026-01-25T18:27:05.907Z",anonymous,"2026-01-25T18:27:05.907Z",anonymous,252,Eleonora,150,16,555,14,USD
"2026-01-25T18:27:05.907Z",anonymous,"2026-01-25T18:27:05.907Z",anonymous,271,Catweazle,170,13,22,150,JPY
Token Count Optimization
The plugin provides intelligent token count optimization:
Automatic Content Type Selection
When autoDetermineResponseContentType is enabled:
- JSON: Used when JSON format has fewer tokens
- TOON: Used when TOON format has fewer tokens (typical case)
Token Statistics Logging
When logTokenStatistics is enabled, the plugin logs:
[toon] - Token count - JSON: 150, TOON: 95, Difference: 55 (36.7%)
Advanced Configuration
Custom Protocol Registration
The plugin automatically registers protocols, but you can customize them:
// cds-plugin.js
const cds = require("@sap/cds");
cds.protocol.toon = {
path: "/custom-toon",
impl: "@geertjanklaps/cds-toon-ai-protocol-adapter",
};
Environment-Specific Settings
{
"cds": {
"profiles": {
"production": {
"toonAdapter": {
"logTokenStatistics": false,
"autoDetermineResponseContentType": true
}
},
"development": {
"toonAdapter": {
"logTokenStatistics": true,
"autoDetermineResponseContentType": false
}
}
}
}
}
Testing Your Implementation
Use the provided test files as reference:
### OData GET request
GET http://localhost:4004/odata/v4/catalog/Books?$select=createdAt,createdBy,modifiedAt,modifiedBy,ID,title,author_ID,genre_ID,stock,price,currency_code
Content-Type: application/json; charset=utf-8
Authorization: Basic alice:
### TOON OData GET Request
GET http://localhost:4004/toon-odata/catalog/Books?$select=createdAt,createdBy,modifiedAt,modifiedBy,ID,title,author_ID,genre_ID,stock,price,currency_code
Content-Type: application/json; charset=utf-8
Authorization: Basic alice:
When to Use
Ideal Use Cases
- AI/LLM Integration: Optimize token usage for AI model communication
- Large Data Payloads: Reduce bandwidth and token costs for complex responses
- Real-time Applications: Minimize payload size for faster transmission
- Cost Optimization: Reduce AI API costs through token count reduction
Performance Benefits
- Token Reduction: Typically 20-50% fewer tokens compared to JSON
- Bandwidth Optimization: Smaller payload sizes
- AI Cost Reduction: Lower token consumption in AI model interactions
API Reference
Adapters
TOONAdapter
Extends SAP CAP's REST adapter with TOON protocol support.
TOONODataAdapter
Extends SAP CAP's OData adapter with TOON protocol support.
Troubleshooting
Common Issues
-
Plugin Not Loading
- Ensure plugin is in dependencies, not devDependencies
- Check CDS version compatibility (>=9 required)
-
TOON Endpoints Not Available
- Verify service has
@protocol annotation
- Check service registration in CDS
-
Token Statistics Not Showing
- Enable
logTokenStatistics: true in configuration
- Check log level configuration
Debug Logging
Enable debug logging:
DEBUG=toon cds watch
Contributing
Contributions are welcome! Please submit pull requests to the GitHub repository.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support
Related Projects
- @toon-format/toon: Core TOON format implementation
- @sap/cds: SAP Cloud Application Programming Model
- tokenx: Token counting utilities
