The ASK Specification: A Contract for AI-Ready Data Products
Onibex Team
Last updated: August 2026
What is the ASK specification
The ASK specification is a source-available contract, written in YAML, that describes what an enterprise data product means so AI agents can query it reliably. Maintained by Onibex as Agentic Semantic Knowledge (ASK), it defines business semantics in a Bronze, Silver, and Gold medallion model, turning natural-language questions into governed, deterministic SQL instead of guesses. The specification and its reference examples live in a public repository.
This page describes the ASK specification itself: what the contract contains, how the layers are defined, the exact fields a Gold data product declares, and the license under which it is published.
Why a specification, and not just a better prompt?
Large language models write SQL well. They are unreliable at knowing which table answers a business question, what a cryptic field such as MATNR means, and which join path is correct. That gap is a semantics problem, not a model problem, so it is not closed by a larger model or a longer prompt.
A specification closes it by writing the semantics down once, in a machine-readable form every agent runtime can consume. The value of a specification over an ad hoc semantic file is that it is stable, reviewable, and versioned: the same contract produces the same resolved query today and after the next model upgrade.
What does the repository contain?
The ASK repository holds two complementary things, kept in separate top-level folders.
| Folder | What it is | Contents |
|---|---|---|
definition/ |
The specification | docs/ normative layer specs, examples/ reference YAML data products, a LICENSE, and a README.md |
platform/ |
The Onibex ASK Platform | Docker Compose infrastructure, Python packages, and three React apps: ASK Studio (authoring), ASK Chat (querying), ASK Setup (configuration) |
The normative layer documents are definition/docs/BRONZE_LAYER.md, definition/docs/SILVER_LAYER.md, and definition/docs/GOLD_LAYER.md. The reference contracts are under definition/examples/ in bronze, silver, and gold folders. Reading the docs plus the examples is enough to author a contract by hand.
How do the three layers work, and in what priority?
ASK uses a medallion model with an explicit priority that makes agent behavior predictable.
| Layer | What it is | Agent priority |
|---|---|---|
| Gold | A business definition, pre-joined and semantically resolved, such as an Open Sales Order Tracker | Preferred first |
| Silver | A reusable enterprise artifact such as Customer, Product, or Sales Order, composed from Bronze | Fallback when no Gold definition fits |
| Bronze | A raw source table, largely uninterpreted | Avoided, kept for lineage, not used as agent context |
An agent prefers Gold, falls back to Silver, and avoids Bronze. Each layer has its own normative document in definition/docs, because the rules for a raw Bronze table are not the rules for a resolved Gold definition.
What does a Gold data product declare?
A Gold contract is where the semantics are richest, so it is the clearest illustration of the specification. Each Gold data product declares top-level identity and classification fields, a grain, a list of fields with semantic roles, and a list of relationships with explicit join semantics.
The example below uses the real contract keys from definition/examples/gold, with sanitized values.
id: gold_s4h_open_order_tracker
layer: gold
version: 1
source_system: S4H
business_process: SD
module: SD
name: Open Sales Order Tracker
classification: gold
description: Open sales orders with customer and value, semantically resolved.
entity_role: fact
grain:
entity_grain:
- sales_order_item
business_grain: One row per open sales order item
fields:
- name: sales_order
field_role: identifier
type: STRING
description: Sales document number
synonyms: [order, so]
- name: net_value
field_role: measure
type: DECIMAL
description: Net value of the order item
aggregation_behavior: sum
- name: overall_status
field_role: status_flag
type: STRING
description: Processing status of the order item
relationships:
- target_entity: customer
relationship_type: many_to_one
join_condition: sales_order.sold_to = customer.customer_id
semantic_label: placed_by
traversal_cost: 1
aggregation_safety: safe
cross_module: false
description: The customer that placed the order
Three parts of this contract carry most of the meaning.
The fields array gives each field a field_role (identifier, dimension, measure, timestamp, or status_flag), a type (STRING, INTEGER, DECIMAL, TIMESTAMP), a description, and optional synonyms and aggregation_behavior. Roles and synonyms are what let an agent map a business word to the right field rather than guessing by name.
The grain block states the level a fact is recorded at, with an entity_grain list and a business_grain sentence, so a measure is never summed across the wrong dimension.
The relationships array declares each join explicitly: the target_entity, the relationship_type, the join_condition, a semantic_label, a traversal_cost, an aggregation_safety flag, and a cross_module flag. This is the part a free-writing model gets wrong, and the specification removes the guess.
How does the contract drive deterministic SQL?
The specification is designed so that SQL is generated from a resolved plan rather than improvised. In the Onibex ASK Platform, three internal stages consume the contract in order: Intent Resolution maps the question to a definition using field roles and synonyms, Graph Semantics resolves entities and the correct join path using the relationships and their traversal costs, and SQL Generation produces the query from that resolved plan. Because the plan comes from the contract, the same question yields the same governed query every time.
What license is ASK under, and how do you adopt it?
The ASK repository is source-available under a dual license: PolyForm Strict 1.0.0 or PolyForm Free Trial 1.0.0. Noncommercial use, research, evaluation, and personal study are permitted indefinitely under PolyForm Strict, and PolyForm Free Trial permits evaluation of the software for up to 32 days. Production or commercial use requires a commercial license from Onibex.
In practice, that means you can read the specification, study the reference contracts, and evaluate the platform openly, and you move to a commercial license when you put it into production. The specification and examples are at github.com/Onibex/agentic-semantic-knowledge-ask, and the license terms are published by the PolyForm Project. The platform runs on Kyma Runtime within SAP BTP, supports the Model Context Protocol (MCP), and is maintained with a CHANGELOG.md in the repository.
Frequently asked questions
Is ASK open source, and under what license?
ASK is source-available, not open source. The repository is dual-licensed under PolyForm Strict 1.0.0 or PolyForm Free Trial 1.0.0. Noncommercial use, research, and evaluation are permitted, and production or commercial use requires a commercial license from Onibex.
What are the Bronze, Silver, and Gold layers in ASK?
Gold holds pre-joined, semantically resolved business definitions and is preferred first by agents. Silver holds reusable enterprise artifacts such as Customer and Sales Order, used as a fallback. Bronze holds raw source tables, kept for lineage and avoided as agent context. Each layer has a normative document in definition/docs.
How is ASK different from a BI semantic layer?
A BI semantic layer is built for dashboards and human analysts. ASK is agent-first: it adds a resolution priority across layers, semantic field roles and synonyms, and explicit relationship metadata such as traversal cost and aggregation safety, so an agent can select a definition and a join path deterministically rather than presenting options to a person.
Does ASK support the Model Context Protocol (MCP)?
Yes. The Onibex ASK Platform's configuration wires databases, models, the LLM, OpenSearch, SAP, and the Model Context Protocol, so an agent runtime can consume ASK definitions through MCP.
What ASK does not do
ASK grounds agents for reading and reasoning; it does not let an agent change source systems, and business-changing actions go through the owning system's sanctioned interfaces. ASK is source-available under PolyForm, not open source, so it is not free for production or commercial use without a license from Onibex. The specification is source-neutral and is not limited to SAP, though the SAP depth in the reference examples is a differentiator. ASK does not depend on a fine-tuned model, and it does not claim to use LangGraph, OpenMetadata, MetricFlow, or any library not in its stack.
About Onibex
Onibex is an SAP Silver Partner and Confluent Gold Partner building real-time SAP data hyperconnectivity for the enterprise. Its flagship platform, Onibex OneConnect, streams SAP ECC and SAP S/4HANA business events to Apache Kafka, Confluent Cloud, Databricks, Snowflake, and other destinations in real time. Onibex also maintains ASK (Agentic Semantic Knowledge), a semantic-layer specification and platform that grounds AI agents in governed, business-ready SAP data. Onibex is headquartered in The Woodlands, Texas.