2.1Source Text

A KnowQL document is a valid JSON object conforming to this specification. :: A clause is a named field within a KnowQL document, consisting of a clause name and a clause value. Clause names are lowercase ASCII strings. Unknown clauses MUST be rejected by a conforming implementation unless the clause name begins with x-, which is reserved for implementation-specific extensions.

2.2Document Structure

A KnowQL document has the following top-level structure:

Document :
  QueryDocument
  ExplainDocument
  IntrospectionDocument

QueryDocument :
  { QueryClauses }

ExplainDocument :
  { "explain": true, QueryClauses }

IntrospectionDocument :
  { "introspect": IntrospectionTarget }

A QueryDocument is the standard form for retrieving knowledge.

An ExplainDocument includes "explain": true alongside query clauses. The service MUST return an execution plan instead of executing the query.

An IntrospectionDocument queries the service’s schema.

2.3Clauses

A primitive is a named clause with formal, defined semantics. Clauses are order-independent: a KnowQL service MUST produce equivalent results regardless of the order in which clauses appear in the document.

2.4Values

KnowQL clause values follow standard JSON value types:

Value :
  StringValue
  NumberValue
  BooleanValue
  NullValue
  ListValue
  ObjectValue

2.5Identifiers

Context identifiers referenced in scope and link are opaque strings from the perspective of the KnowQL language. Their structure is defined by the service’s schema. By convention, service implementations use a namespace/name or ctx_name format, but this is not normative.

2.6Fragments

A shape fragment is a reusable named shape template that can be referenced by name. Shape fragments allow callers to define common output schemas once and reuse them across queries.

ShapeFragment :
  { "fragment": FragmentName, "shape": ShapeValue }

FragmentName :
  String

Fragment definitions are registered with the service schema. A fragment reference within a shape value uses a $ref key:

{
  "ask": "Summarize the contract terms",
  "scope": ["ctx_contracts"],
  "shape": { "$ref": "ContractSummary" }
}

Fragment support is OPTIONAL. Services MUST document whether fragments are supported.

2.7Schema Coordinates

A schema coordinate is a human-readable string that uniquely identifies a schema element within a KnowQL service’s schema. Schema coordinates follow the form:

SchemaCoordinate :
  ContextCoordinate
  FieldCoordinate

ContextCoordinate :
  ContextName

FieldCoordinate :
  ContextName . FieldName

Examples:

Schema coordinates are used in error messages, ground source references, trace output, and tooling.

3.1Type System Descriptions

Documentation is a first-class feature of the KnowQL type system. Every named definition in a schema SHOULD carry a human-readable description. These descriptions are returned via introspection and remain consistent with the service’s capabilities.

Descriptions are provided as plain strings or as Markdown (CommonMark). Description strings appear as a "description" field on each schema object.

{
  "context": "ctx_contracts",
  "description": "Active and historical contracts for all customers.",
  "fields": {
    "customer_id": {
      "type": "ID!",
      "description": "Unique identifier for the customer."
    }
  }
}

3.2Named Types

KnowQL uses a JSON Schema-aligned type notation for shape fields:

Type :
  NamedType
  ListType
  NonNullType

NamedType :
  String
  Int
  Float
  Boolean
  ID
  Date
  DateTime
  JSON

ListType :
  [ Type ]

NonNullType :
  Type !

{
  "shape": {
    "contract": {
      "id": "ID!",
      "start_date": "Date",
      "value_usd": "Float"
    }
  }
}

{
  "shape": {
    "applicable_rules": [{ "rule_id": "ID!", "reason": "String" }]
  }
}

{
  "shape": {
    "qualifies": "Boolean!",
    "discount_pct": "Float"
  }
}

3.3Contexts

A context is the fundamental unit of knowledge in KnowQL. It corresponds to a named, queryable source of information — analogous to a table or view in SQL, or a dataset in a vector database.

ContextDefinition :
  {
    "context": ContextName,
    "description": String?,
    "fields": { FieldName: FieldDefinition },
    "links": [ LinkDefinition ]?,
    "version": String?
  }

Each context MUST have:

• A unique context name within the schema
• A fields object defining the filterable and returnable fields

Each context MAY have:

• description for documentation
• links defining cross-context join targets
• version for versioning (see Versioning)

3.4Fields

A field definition declares the type and metadata of a queryable field within a context.

FieldDefinition :
  {
    "type": TypeExpression,
    "description": String?,
    "filterable": Boolean?,
    "returnable": Boolean?
  }

filterable — if true, this field can appear in where predicates. Defaults to true for scalar fields.

returnable — if true, this field can appear in shape. Defaults to true.

3.5Shape Types

A shape defines the structure and types of the response object a caller expects. Shape definitions are validated against the schema at query time.

Shape types extend the base type system with two additional constructs:

TypedNull: When a field in the response is null because the service could not confidently resolve it (as opposed to being legitimately absent), the service SHOULD accompany the null with a confidence indicator in the ground response (see the Primitives and Response sections).

ConfidenceAnnotation: Every field in a shaped response MAY carry a confidence value (high, medium, low, or derived) in the ground section of the response. This is independent of the field’s type.

3.6Link Types

A link definition describes a joinable relationship between two contexts, modeled on foreign-key semantics:

LinkDefinition :
  {
    "from": FieldName,
    "to": ContextName . FieldName,
    "description": String?
  }

Links are declared in the schema and used in link clause queries.

3.7Schema

A KnowQL schema is the top-level container for all type definitions accessible to a service:

Schema :
  {
    "version": SchemaVersion,
    "name": String?,
    "description": String?,
    "contexts": [ ContextDefinition ],
    "fragments": [ FragmentDefinition ]?,
    "directives": [ DirectiveDefinition ]?
  }

The schema is returned by the introspection system (see the Introspection section).

3.8Versioning

KnowQL schemas evolve additively. New contexts and fields MAY be added in minor versions. Existing contexts and fields MUST NOT be removed or have their types narrowed without a major version increment.

Additive changes (always safe):

• Adding a new context
• Adding a new field to an existing context
• Adding a new link
• Adding a new enum value

Breaking changes (require major version):

• Removing or renaming a context
• Removing or renaming a field
• Changing a field’s type in a non-widening way
• Changing a field from non-null to null or vice versa

Services SHOULD document their versioning policy. The RECOMMENDED versioning scheme is calendar-based (e.g., 2026-04) for major releases, following GraphQL’s precedent.

4.1Group A: Intent

Intent primitives declare what the caller wants to know. They are the semantic core of a KnowQL query.

ask : StringValue

{
  "ask": "What are the payment terms for Acme Corp's current contract?",
  "scope": ["ctx_contracts"]
}

shape : ShapeValue

{
  "ask": "Does Acme Corp qualify for a renewal discount?",
  "scope": ["ctx_contracts", "ctx_pricing_policy"],
  "shape": {
    "qualifies": "Boolean!",
    "discount_pct": "Float",
    "reason": "String"
  }
}

scope : [ ContextIdentifier ]

{
  "ask": "What is the pricing for enterprise tier?",
  "scope": ["ctx_pricing_policy"]
}

4.2Group B: Filter

Filter primitives narrow the result set deterministically. Their semantics are fully deterministic: a filter either includes or excludes a record with no probabilistic component.

where : { FieldName: PredicateValue }

{
  "where": {
    "$and": [
      { "customer_id": "acme_corp_001" },
      { "status": { "$in": ["active", "pending"] } }
    ]
  }
}

as_of : DateTimeValue

{
  "ask": "What were the contract terms for Acme Corp?",
  "scope": ["ctx_contracts"],
  "where": { "customer_id": "acme_corp_001" },
  "as_of": "2025-12-31T23:59:59Z"
}

since : DateTimeValue

window : { "from": DateTimeValue, "to": DateTimeValue }

4.3Group C: Composition

Composition primitives combine knowledge from multiple sources before returning. They execute entirely within the engine before the response is formed.

link : LinkExpression | [ LinkExpression ]

LinkExpression :
  {
    "contexts": [ ContextName ],
    "on": FieldName | { "left": FieldPath, "right": FieldPath }
  }

{
  "ask": "Do usage metrics exceed the contract threshold?",
  "scope": ["ctx_contracts", "ctx_usage"],
  "link": {
    "contexts": ["ctx_contracts", "ctx_usage"],
    "on": "customer_id"
  },
  "where": { "customer_id": "acme_corp_001" }
}

resolve : ResolutionPolicy

ResolutionPolicy :
  { "precedence": [ ContextName ] }
  | { "strategy": "latest" | "highest_confidence" | "union" }

4.4Group D: Provenance

Provenance is the citable origin of a response value — the source records that were retrieved, the confidence with which the engine resolved each field, and the reasoning that connected sources to the final answer.

Provenance primitives ground the answer in citable knowledge.

ground : GroundOptions

GroundOptions :
  {
    "per_field": Boolean,
    "min_confidence": "high" | "medium" | "low"
  }

{
  "ask": "What is Acme Corp's annual contract value?",
  "scope": ["ctx_contracts"],
  "where": { "customer_id": "acme_corp_001" },
  "shape": { "acv_usd": "Float!" },
  "ground": { "per_field": true, "min_confidence": "medium" }
}

trace : TraceOptions

TraceOptions :
  {
    "enabled": Boolean,
    "handle": Boolean
  }

4.5Group E: Control

Control primitives declare the resource envelope and execution mode.

budget : BudgetOptions

BudgetOptions :
  {
    "max_tokens": Int,
    "max_latency_ms": Int,
    "depth": "shallow" | "standard" | "deep"
  }

await : "sync" | "async" | "stream"

apply : { DirectiveName: DirectiveValue }

4.6Meta Primitive: explain

explain : true

{
  "explain": true,
  "ask": "Does Acme qualify for a renewal discount?",
  "scope": ["ctx_contracts", "ctx_pricing_policy"],
  "where": { "customer_id": "acme_corp_001" }
}

{
  "plan": {
    "steps": [
      {
        "type": "filter",
        "context": "ctx_contracts",
        "predicate": { "customer_id": "acme_corp_001" },
        "estimated_records": 1
      },
      {
        "type": "semantic_retrieval",
        "context": "ctx_pricing_policy",
        "query": "renewal discount qualification criteria",
        "strategy": "dense_vector",
        "estimated_records": 4
      },
      {
        "type": "synthesis",
        "model": "default",
        "estimated_tokens": 850
      }
    ],
    "estimated_total_tokens": 850,
    "estimated_latency_ms": 320
  }
}

5.1Document Validation

{
  "ask": "What are the contract terms?",
  "filter": { "customer_id": "acme_corp_001" }
}

{
  "scope": ["ctx_contracts"],
  "where": { "customer_id": "acme_corp_001" }
}

{
  "ask": 42
}

{
  "ask": "What is the ACV?",
  "budget": 2000
}

5.2Scope Validation

{
  "ask": "What are the contract terms?",
  "scope": ["ctx_contracts", "ctx_does_not_exist"]
}

5.3Where Validation

{
  "ask": "Summarize contract terms",
  "scope": ["ctx_contracts"],
  "where": { "full_text_content": "annual" }
}

{
  "where": { "customer_id": { "$gt": "acme" } }
}

5.4Shape Validation

{
  "ask": "What is the discount?",
  "shape": { "discount_pct": "Percentage" }
}

{
  "ask": "What is the discount?",
  "shape": {}
}

5.5Ground Validation

{
  "ask": "What is the discount?",
  "ground": { "per_field": true }
}

5.6Budget Validation

{
  "ask": "What is the discount?",
  "budget": { "max_tokens": -100 }
}

5.7Link Validation

5.8Temporal Validation

{
  "window": { "from": "2026-12-31", "to": "2026-01-01" }
}

5.9Explain Validation

6.1Executing a Request

A KnowQL request carries a document, optional caller identity, and optional variable bindings. The service executes the request and produces a response.

ExecuteRequest(schema, document, caller, variables):
  1. Validate document against schema. If validation fails, return a request
     error (see Response section).
  2. If document contains "explain: true", return ExecutePlan(schema, document).
  3. If document contains "introspect", return ExecuteIntrospection(schema,
     document).
  4. Return ExecuteQuery(schema, document, caller, variables).

6.2Executing a Query

ExecuteQuery(schema, document, caller, variables):
  1. Let scope = ResolveScope(schema, document, caller).
  2. Let filtered = ApplyFilters(scope, document).
  3. Let linked = ApplyLinks(filtered, document).
  4. Let resolved = ApplyResolution(linked, document).
  5. Let budget = ResolveBudget(document).
  6. Let retrieved = Retrieve(resolved, document, budget).
  7. Let data = Synthesize(retrieved, document, budget).
  8. Let grounded = ApplyGround(data, retrieved, document).
  9. Return FormatResponse(data, grounded, document).

ResolveScope(schema, document, caller):
  1. If "scope" is present, let contextIds = document.scope.
  2. If "scope" is absent, let contextIds = all contexts accessible to caller
     in schema.
  3. For each id in contextIds:
     a. Assert id exists in schema. (Guaranteed by validation.)
     b. Assert caller has access to id.
  4. Return the set of context definitions for contextIds.

ApplyFilters(contexts, document):
  1. If "where" is absent, return contexts unchanged.
  2. Let predicate = document.where.
  3. For each context in contexts:
     a. Evaluate predicate against each record's filterable metadata.
     b. Exclude records that do not satisfy the predicate.
  4. Apply temporal filters if "as_of", "since", or "window" are present.
  5. Return the filtered contexts.

ApplyTemporalFilter(contexts, document):
  1. If "as_of" is present, include only records valid at document.as_of.
  2. If "since" is present, include only records created/updated after
     document.since.
  3. If "window" is present, include only records valid within the window.
  4. Return the temporally filtered contexts.

ApplyLinks(contexts, document):
  1. If "link" is absent, return contexts unchanged.
  2. For each link expression L in document.link:
     a. Let leftContext = resolve L.contexts[0] from contexts.
     b. Let rightContext = resolve L.contexts[1] from contexts.
     c. Let joinField = L.on.
     d. Perform an inner join: for each record in leftContext, find all
        records in rightContext where joinField values match.
     e. Produce a joined record set.
  3. Return the joined context set.

ApplyResolution(contexts, document):
  1. If "resolve" is absent, use the implementation's default conflict
     strategy.
  2. For each field F that appears in multiple contexts with different values:
     a. If resolve.precedence is set, use the value from the highest-
        precedence context.
     b. If resolve.strategy is "latest", use the most recently updated value.
     c. If resolve.strategy is "highest_confidence", use the value that
        retrieval assigns the highest relevance score to.
     d. If resolve.strategy is "union", collect all values as a list.
  3. Record every resolution decision for the "ground" output.
  4. Return the resolved record set.

Retrieve(contexts, document, budget):
  1. Let ask = document.ask (if present).
  2. Let shape = document.shape (if present).
  3. Derive a retrieval query from ask and/or the field names in shape.
  4. For each context in contexts:
     a. Perform semantic retrieval using the retrieval query.
     b. Respect budget.depth hint (shallow/standard/deep).
     c. Collect retrieved records with relevance scores.
  5. If budget.max_tokens is approaching, truncate retrieved records,
     prioritizing highest-relevance records.
  6. Return the retrieved record set with relevance scores.

Synthesize(retrieved, document, budget):
  1. Let ask = document.ask (if present).
  2. Let shape = document.shape (if present).
  3. Using the retrieved records as context:
     a. If shape is present, produce a JSON object conforming to shape.
     b. If ask is present without shape, produce a free-form response.
     c. If both are present, produce a shaped response that addresses ask.
  4. For each field f in shape:
     a. Attempt to extract or infer the value of f from retrieved records.
     b. If f cannot be resolved and f is non-null (!), raise a field error.
     c. If f cannot be resolved and f is nullable, set f to null.
  5. Track per-field confidence and source records for ground output.
  6. Return the synthesized data object.

ApplyGround(data, retrieved, document):
  1. If "ground" is absent, return null (no ground section in response).
  2. Let options = document.ground.
  3. If options.per_field is true:
     a. For each field f in data:
        i. Let confidence = the confidence level assigned during synthesis.
        ii. Let sources = the schema coordinates of records that contributed.
        iii. If options.min_confidence is set and confidence < min_confidence:
             - Set data[f] = null.
             - Set groundEntry.confidence = actual confidence.
             - Set groundEntry.suppressed = true.
        iv. Else record { confidence, sources } for f.
     b. Return a map of field -> groundEntry.
  4. If options.per_field is false:
     a. Compute an aggregate confidence for the entire response.
     b. Return { confidence, sources } for the whole response.

6.3Executing an Explain Request

ExecutePlan(schema, document):
  1. Validate document against schema.
  2. Build an execution plan as if executing the query, but do not perform
     retrieval or synthesis.
  3. Estimate costs (tokens, latency) based on schema statistics.
  4. Return a "plan" object (see Response section).

6.4Error Handling

6.5Determinism Guarantees

The following aspects of execution are REQUIRED to be deterministic for any given dataset and query:

• The set of records included or excluded by where predicates
• The set of records included or excluded by temporal filters
• The structure of the data object (keys and types match shape)
• The resolution decisions made by resolve with deterministic strategies (precedence, latest)

The following aspects are explicitly probabilistic:

• The relevance scores assigned during semantic retrieval
• The values synthesized from retrieved records
• The confidence levels assigned during synthesis
• The resolve: highest_confidence strategy (based on retrieval scores)

Probabilistic aspects MUST be surfaced via the ground section. They MUST NOT be silently presented as certain.

7.1Introspection Documents

An introspection request is a document with an introspect clause:

IntrospectionDocument :
  { "introspect": IntrospectionTarget }

IntrospectionTarget :
  "__schema"
  | "__context"  ":" ContextName
  | "__field"    ":" FieldCoordinate
  | "__trace"    ":" TraceId

{ "introspect": "__schema" }

{
  "data": {
    "__schema": {
      "version": "2026-04",
      "name": "Nexus Knowledge Service",
      "contexts": [
        {
          "name": "ctx_contracts",
          "description": "Active and historical contracts.",
          "fields": {
            "customer_id": { "type": "ID!", "filterable": true },
            "start_date": { "type": "Date", "filterable": true },
            "value_usd": { "type": "Float", "filterable": false }
          },
          "links": [
            {
              "from": "customer_id",
              "to": "ctx_usage.customer_id",
              "description": "Join contracts to usage metrics"
            }
          ]
        }
      ],
      "fragments": [],
      "knowql_version": "April2026"
    }
  }
}

{ "introspect": "__context:ctx_contracts" }

{
  "data": {
    "__context": {
      "name": "ctx_contracts",
      "description": "Active and historical contracts for all customers.",
      "fields": {
        "customer_id": {
          "type": "ID!",
          "description": "Unique customer identifier.",
          "filterable": true,
          "returnable": true
        },
        "start_date": {
          "type": "Date",
          "description": "Contract start date.",
          "filterable": true,
          "returnable": true
        },
        "value_usd": {
          "type": "Float",
          "description": "Annual contract value in USD.",
          "filterable": false,
          "returnable": true
        }
      },
      "links": [
        {
          "from": "customer_id",
          "to": "ctx_usage.customer_id",
          "description": "Links to usage metrics by customer"
        }
      ],
      "version": "2026-04"
    }
  }
}

{ "introspect": "__field:ctx_contracts.value_usd" }

{
  "data": {
    "__field": {
      "coordinate": "ctx_contracts.value_usd",
      "type": "Float",
      "description": "Annual contract value in USD.",
      "filterable": false,
      "returnable": true,
      "context": "ctx_contracts"
    }
  }
}

{ "introspect": "__trace:tr_abc123" }

7.2Introspection Schema

The introspection system is itself typed. The schema introspection response conforms to the following type definitions:

__Schema :
  {
    version: String!
    name: String
    description: String
    contexts: [__Context!]!
    fragments: [__Fragment!]!
    knowql_version: String!
  }

__Context :
  {
    name: String!
    description: String
    fields: { FieldName: __Field }
    links: [__Link!]
    version: String
  }

__Field :
  {
    type: String!
    description: String
    filterable: Boolean!
    returnable: Boolean!
  }

__Link :
  {
    from: String!
    to: String!
    description: String
  }

__Fragment :
  {
    name: String!
    description: String
    shape: JSON!
  }

7.3First-Class Documentation

All schema elements — contexts, fields, links, fragments — SHOULD provide a description field. Descriptions are returned via introspection and MUST remain consistent with the service’s actual capabilities.

Descriptions SHOULD be written in Markdown (CommonMark). Tools that display descriptions SHOULD render Markdown.

Introspection is not just for machines. Human operators building agents, writing evals, or debugging production queries benefit from a clear, browsable description of the available knowledge.

7.4Stable Ordering

Introspection responses SHOULD return schema elements in a stable, consistent order. The RECOMMENDED order is the source order in which elements were defined in the schema. Stable ordering improves readability, diffs, and deterministic tooling behavior.

7.5Conformance Requirement

A conforming KnowQL implementation MUST support __schema introspection. Support for __context, __field, and __trace introspection is RECOMMENDED but not required for Core conformance.

8.1Response Format

Every KnowQL response is a JSON object with the following possible top-level fields:

Response :
  {
    "data":   DataObject?,
    "ground": GroundObject?,
    "trace":  TraceObject?,
    "plan":   PlanObject?,
    "errors": [ ErrorObject ]?,
    "meta":   MetaObject?
  }

A response MUST contain at least one of data, errors, or plan.

A response MUST NOT contain both data (with a non-null value) and a request error in errors at the same time.

A response MAY contain both data and field errors in errors simultaneously (partial response).

GroundObject :
  {
    FieldName: FieldGroundEntry
  }
  |
  {
    "confidence": ConfidenceLevel,
    "sources": [ SchemaCoordinate ]
  }

FieldGroundEntry :
  {
    "confidence": ConfidenceLevel,
    "sources": [ SchemaCoordinate ],
    "suppressed": Boolean?,
    "resolution": ResolutionEntry?
  }

ConfidenceLevel :
  "high" | "medium" | "low" | "derived" | "none"

ResolutionEntry :
  {
    "strategy": String,
    "candidates": [ { "source": SchemaCoordinate, "value": JSON } ]
  }

{
  "data": {
    "qualifies": true,
    "discount_pct": 12.5,
    "reason": null
  },
  "ground": {
    "qualifies": {
      "confidence": "high",
      "sources": ["ctx_contracts/record_001"]
    },
    "discount_pct": {
      "confidence": "medium",
      "sources": ["ctx_pricing_policy/tier-2"]
    },
    "reason": {
      "confidence": "none",
      "sources": [],
      "suppressed": false
    }
  }
}

{
  "data": { ... },
  "trace": { "trace_id": "tr_abc123def456" }
}

PlanObject :
  {
    "steps": [ PlanStep ],
    "estimated_total_tokens": Int,
    "estimated_latency_ms": Int,
    "warnings": [ String ]?
  }

PlanStep :
  {
    "type": StepType,
    "context": ContextName?,
    "predicate": JSON?,
    "query": String?,
    "strategy": String?,
    "estimated_records": Int?,
    "model": String?,
    "estimated_tokens": Int?
  }

StepType :
  "filter" | "semantic_retrieval" | "link" | "resolve" | "synthesis" | "ground"

ErrorObject :
  {
    "message": String!,
    "type": ErrorType!,
    "path": [ String | Int ]?,
    "locations": [ { "key": String } ]?
  }

ErrorType :
  "REQUEST_ERROR"
  | "VALIDATION_ERROR"
  | "FIELD_ERROR"
  | "BUDGET_EXCEEDED"
  | "AUTHORIZATION_ERROR"
  | "CONTEXT_NOT_FOUND"

{
  "errors": [
    {
      "message": "Context 'ctx_does_not_exist' is not defined in the schema.",
      "type": "CONTEXT_NOT_FOUND",
      "locations": [{ "key": "scope" }]
    }
  ]
}

{
  "data": {
    "qualifies": true,
    "discount_pct": null
  },
  "errors": [
    {
      "message": "Field 'discount_pct' declared non-null but could not be resolved.",
      "type": "FIELD_ERROR",
      "path": ["discount_pct"]
    }
  ]
}

MetaObject :
  {
    "partial": Boolean?,
    "tokens_used": Int?,
    "latency_ms": Int?,
    "knowql_version": String?,
    "request_id": String?
  }

8.2Query Response

A successful query response with both data and ground:

{
  "data": {
    "qualifies": true,
    "discount_pct": 12.5,
    "applicable_rules": [
      { "rule_id": "R-42", "reason": "12-month renewal with >80% usage" }
    ],
    "conflicts": []
  },
  "ground": {
    "qualifies": {
      "confidence": "high",
      "sources": ["ctx_contracts/record_acme_001"]
    },
    "discount_pct": {
      "confidence": "medium",
      "sources": ["ctx_pricing_policy/tier-2-rules"]
    },
    "applicable_rules": {
      "confidence": "medium",
      "sources": [
        "ctx_pricing_policy/rule_R42",
        "ctx_contracts/usage_summary_acme"
      ]
    },
    "conflicts": {
      "confidence": "high",
      "sources": []
    }
  },
  "meta": {
    "tokens_used": 1240,
    "latency_ms": 310,
    "knowql_version": "April2026",
    "request_id": "req_xk9a2b3c4d"
  }
}

8.3Error Response (Request Error)

When a request error prevents execution entirely, no data field is present:

{
  "errors": [
    {
      "message": "Query must contain at least one of 'ask' or 'shape'.",
      "type": "VALIDATION_ERROR",
      "locations": []
    }
  ]
}

8.4Explain Response

{
  "plan": {
    "steps": [
      {
        "type": "filter",
        "context": "ctx_contracts",
        "predicate": { "customer_id": "acme_corp_001" },
        "estimated_records": 1
      },
      {
        "type": "semantic_retrieval",
        "context": "ctx_pricing_policy",
        "query": "renewal discount qualification",
        "strategy": "dense_vector",
        "estimated_records": 4
      },
      {
        "type": "synthesis",
        "model": "default",
        "estimated_tokens": 850
      }
    ],
    "estimated_total_tokens": 850,
    "estimated_latency_ms": 320
  },
  "meta": {
    "knowql_version": "April2026",
    "request_id": "req_explain_zz001"
  }
}

8.5Introspection Response

Introspection responses follow the same envelope format with data containing the introspection result (see the Introspection section for examples).

8.6Serialization

KnowQL responses MUST be serialized as JSON. No other serialization format is defined in this specification. Transport-level encoding (e.g., gzip) is outside the scope of this specification.

Numeric values in responses MUST NOT use JSON serializations that are not universally parseable, such as Infinity, -Infinity, or NaN. These values MUST be represented as null with an appropriate error or confidence annotation.

A.1Conformance Levels

A.2Conforming Algorithms

Algorithms in this specification are normative with respect to their observable results. Implementations may use any equivalent strategy. An implementation must not produce results that differ from the specified algorithms in any observable way.

A.3Non-Normative Portions

All contents of this document are normative except portions explicitly declared as non-normative.

Examples in this document are non-normative, and are presented to aid understanding. Examples are either introduced explicitly in prose (e.g., “for example”) or are set apart in labeled blocks.

Notes in this document are non-normative, and are presented to clarify intent, draw attention to edge cases, and answer common implementation questions.

B.1B.1 Grammar Notation

This specification describes the structure of KnowQL documents using a simplified JSON grammar notation. Non-terminal production rules use the following form:

NonTerminal :
  Component1 Component2
  | Alternative

In this notation:

• NonTerminal names the construct being defined.
• Components separated by newlines are alternatives.
• Components on the same line are sequences.
• ? following a component means it is optional.
• [ ] denotes a list (JSON array).
• { } denotes an object (JSON object).
• | separates alternatives in a compact list.
• Quoted strings (e.g., "ask") represent literal JSON string values.

B.2B.2 Algorithm Notation

Algorithms in this specification use pseudo-code with the following conventions:

• Let x = expression — binds a name to a value.
• Assert: condition — asserts that a condition must be true; if false, the algorithm has a bug.
• If condition: ... — conditional branch.
• For each x in collection: ... — iteration.
• Return value — terminates the algorithm with a result.
• Raise error — terminates the algorithm with an error condition.

Algorithms are normative with respect to their observable results. Equivalent implementations are conforming.

B.3B.3 RFC 2119 Key Words

Normative key words (MUST, SHOULD, MAY, etc.) are from IETF RFC 2119. They retain their defined meaning when written in uppercase throughout this specification.

B.4B.4 Confidence Ordering

Confidence levels form a total order for the purposes of min_confidence comparison:

none < low < medium < high

derived is a special case: it represents a computed value and is treated as equivalent to medium for threshold comparisons unless otherwise specified.

B.5B.5 Schema Coordinate Syntax

Schema coordinates use dotted-path notation:

ContextName           → identifies a context
ContextName.FieldName → identifies a field within a context

In source references within ground, schema coordinates MAY include a record identifier appended with /:

ctx_contracts/record_acme_001

This is an informational extension and implementations may use any opaque string format for record identifiers within schema coordinates.

B.6B.6 Type Expression Syntax

Type expressions in shape values follow a shorthand notation aligned with JSON Schema and GraphQL:

In shape values, the type expression is provided as the value for the field key:

{
  "shape": {
    "name": "String!",
    "score": "Float",
    "tags": ["String"]
  }
}