1.1Example

A free-form turn over one context:

{
  "ask": "Compare Q3 revenue across the targets.",
  "scope": ["vantage-data-room"]
}

A structured turn that continues a session:

{
  "ask": "Does Acme Corp qualify for a renewal discount?",
  "session_id": "ses_…",
  "shape": {
    "type": "object",
    "properties": {
      "qualifies": { "type": "boolean" },
      "discount_pct": { "type": "number" },
      "reason": { "type": "string" }
    },
    "required": ["qualifies"]
  }
}

A retrieval-only turn (no synthesis):

{
  "ask": "payment terms Acme current contract",
  "scope": ["ctx_contracts"],
  "retrieval_only": true,
  "max_retrieved": 20
}

1.2Design principles

Declarative. The query document states intent, scope, shape, and controls. Clause order does not change meaning. The engine chooses retrieval and synthesis strategy.

Turn-based. One query document produces one response document. Multi-turn conversation is a sequence of queries chained by session identity.

Grounded by default. Implementations SHOULD return citations that point back into the scoped knowledge. Retrieval-only mode returns the retrieved material itself.

Transport-agnostic document. The canonical form is JSON. HTTP bindings (paths, status codes, SSE) are RECOMMENDED shapes in this document, not the only legal transport.

Honest about determinism. Retrieval ranking and free-form synthesis are probabilistic. Structural contracts — shape conformity, retrieval-only payload layout, session scope pinning — are deterministic for a given implementation and knowledge snapshot.

1.3What 0.1.0 covers

Version 0.1.0 specifies the functional surface of a production query API:

1.4Out of scope

This specification does not define:

• How contexts are built (ingest, curation, manifests, indexes)
• Authentication, tenancy, or billing
• Any particular model provider or tool runtime
• Client SDKs

Implementations MAY extend the document with additional fields. Extensions MUST NOT redefine the meaning of fields defined here.

2.1Context

:: A context is a named unit of knowledge that a query may scope over. Contexts are created and curated outside KnowQL. From the query language’s point of view, a context is an opaque identifier (slug or UUID) that the implementation resolves to a queryable knowledge base.

A context is queryable when the implementation is prepared to answer over it. Implementations MUST reject a new session whose scope includes a context that is not yet queryable, unless the implementation documents a deliberate open-empty behavior for that context kind.

2.2Query

:: A query is one turn — the object created by submitting a Query Document. It carries the caller’s ask, optional per-turn controls, normalized input messages, and (once complete) output, structured result, citations, usage, and status.

Lifecycle states:

A query is created in in_progress and transitions to exactly one terminal state.

2.3Session

:: A session is a durable conversation: an ordered chain of queries plus a pinned configuration. Scope and session-level config are fixed at creation and apply to every subsequent turn.

A session is project-owned (or equivalent tenancy boundary) and is a top-level resource — not nested under an “agent” entity. There is no persisted agent object in KnowQL 0.1.0.

Pinned at creation (see Sessions):

• scope — 1–10 context identifiers
• system_prompt — optional guidance prepended every turn
• guardrails — optional hard constraints every turn
• models — optional default model preference list
• tools — optional default tool subset
• vars — optional implementation-defined env / config map

Not pinned on the session: shape, retrieval-only controls, stream, background, timeout_seconds, max_steps, thinking_level. Those are per-turn.

2.4Relationship

Session 1──* Query
Session *──* Context   (via fixed scope, 1–10)
Query   ?──1 Query     (previous_query_id chain)

Listing a session’s queries in creation order reconstructs the full conversation. There is no separate message store in the language model — each query row holds its turn’s input and output.

3.1Intent

[{ "role": "user", "content": "<ask text>" }]

3.2Scope and session binding

3.3Model and tools

3.4Session configuration (new session only)

These fields are honored only when the document starts a new session. On a continuing turn they MUST be ignored (or rejected — implementations SHOULD document which).

3.5Delivery controls

3.6Execution controls

3.7Retrieval / compose controls

See Retrieval Modes for full semantics.

These are per-turn and are not pinned on the session.

3.8Fields not in 0.1.0

The following names appeared in earlier drafts or are reserved for later versions. They are not required, and implementations MUST NOT treat them as part of Core 0.1.0 conformance. See Future Work.

where, ground, budget, explain, as_of, since, window, link, resolve, trace (as a request primitive), await, apply.

4.1Field semantics

4.2Example (completed free-form)

{
  "id": "qry_01h…",
  "object": "query",
  "session_id": "ses_01h…",
  "model": "anthropic/claude-sonnet-4-6",
  "created": 1786051200,
  "status": "completed",
  "error": null,
  "previous_query_id": null,
  "input": [{ "role": "user", "content": "What are Acme's payment terms?" }],
  "output": [
    {
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "Net 30 on the current MSA, with 2% 10 net 30 on renewals."
        }
      ]
    }
  ],
  "output_json": null,
  "citations": [{ "source": "contracts/acme-msa.pdf", "section_path": "§4.2" }],
  "steps": [],
  "usage": {
    "input_tokens": 4200,
    "output_tokens": 180,
    "total_tokens": 4380,
    "cost_usd": 0.012
  },
  "runtime_ms": 12400
}

4.3Example (shaped)

When shape was supplied, output_json holds the conforming object:

{
  "status": "completed",
  "output": [
    {
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "" }]
    }
  ],
  "output_json": {
    "qualifies": true,
    "discount_pct": 12.5,
    "reason": "12-month renewal with >80% usage"
  },
  "citations": [{ "source": "pricing/tier-2.md" }]
}

4.4Errors

A terminal failed document MUST set status to "failed" and SHOULD set error to a clear message. Validation failures MAY be returned as HTTP 4xx (or transport equivalent) without creating a query, or as a failed query — implementations SHOULD be consistent and document the choice.

5.1Creating a session

A session is created implicitly when a Query Document is submitted without previous_query_id and without session_id.

Required on create:

• ask
• scope (1–10 queryable contexts)

Optional on create (pinned):

• system_prompt, guardrails, vars
• models / model (become session default preference)
• tools
• workflow (when the implementation treats workflow as session-defining)

The first query becomes the head of the chain. Implementations SHOULD derive a short title from the first ask for list UIs.

5.2Continuing a session

Submit a new Query Document with either:

• previous_query_id set to a query in the session, or
• session_id set to the session id

Continuation rules:

1. scope and other session-pinned fields from the create request remain in force; new values for those fields on a continue request are ignored or rejected.
2. The implementation replays prior turns as conversation history so the runtime can answer in context.
3. Per-turn fields (shape, model override, retrieval controls, delivery flags, max_steps, thinking_level) apply only to the new turn.

5.3Session resource (recommended HTTP binding)

Path prefixes (e.g. /api/v0) are deployment-defined.

{
  "id": "ses_…",
  "scope": ["ctx_a", "ctx_b"],
  "title": "Compare Q3 revenue…",
  "system_prompt": null,
  "guardrails": null,
  "models": ["standard"],
  "tools": [],
  "vars": {},
  "workflow": "search",
  "last_query_id": "qry_…",
  "created_at": "2026-08-06T00:00:00Z",
  "updated_at": "2026-08-06T00:05:00Z"
}

5.4Workspace / tenancy (informative)

Implementations MAY scope session visibility to a workspace or project. Cross-tenant access MUST be denied. Orphan sessions whose entire scope has been deleted MAY be hidden from lists.

5.5No agent entity

KnowQL 0.1.0 does not define a reusable persisted agent. Anything that looks like agent configuration is session-pinned fields on create. Clients that want reuse re-send the same create payload.

6.1Synchronous

1. Validate and accept the Query Document.
2. Create session (if needed) and query row in in_progress.
3. Execute the turn.
4. Return the terminal Response Document in the response body.

Suitable for short turns and simple clients. Long turns should use stream or background so intermediaries do not time out.

6.2Stream

When stream is true (or the client negotiates an event stream via transport headers), the implementation emits a sequence of events and ends with the full query document.

6.3Background

When background is true:

1. Accept, persist in_progress, start execution.
2. Return the Response Document immediately with status: "in_progress" (RECOMMENDED HTTP status: 202 Accepted).
3. Client polls GET /queries/{id} until status is terminal (completed | failed | cancelled).

6.4Timeout

timeout_seconds bounds execution. Default and maximum are implementation-defined; 900 seconds (15 minutes) is the RECOMMENDED default and ceiling. On timeout the query MUST end in failed or cancelled with an explanatory error.

6.5Cancel

Implementations MAY expose a cancel operation for an in_progress query. A cancelled turn sets status to "cancelled". Cancel is Future as a standardized request field; product APIs may already support it out of band.

7.1`shape` format

shape is a JSON Schema document (object). KnowQL 0.1.0 does not define a custom type shorthand. Draft version support is implementation-defined; implementations SHOULD accept common JSON Schema object schemas with type, properties, required, items, and nested objects/arrays.

Example:

{
  "ask": "Does Acme Corp qualify for a renewal discount?",
  "scope": ["ctx_contracts", "ctx_pricing_policy"],
  "shape": {
    "type": "object",
    "properties": {
      "qualifies": { "type": "boolean" },
      "discount_pct": { "type": "number" },
      "applicable_rules": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "rule_id": { "type": "string" },
            "reason": { "type": "string" }
          },
          "required": ["rule_id", "reason"]
        }
      }
    },
    "required": ["qualifies"]
  }
}

7.2Response contract

1. On success, output_json MUST be a JSON value that validates against shape.
2. output MAY contain empty or summary prose; clients that need structure MUST read output_json.
3. If the engine cannot produce a conforming document, the turn MUST failed (or return a validation error) rather than return a silently non-conforming output_json.
4. shape is per-turn. Omitting it on a later turn returns free-form output even if earlier turns in the session used a shape.

7.3Interaction with retrieval-only

If both shape and a retrieval-only control are set, implementations SHOULD prefer retrieval-only semantics for output_json (retrieved material envelope) and MAY ignore shape, or reject the combination. The originating implementation skips synthesis in retrieval modes; clients SHOULD NOT combine shape with retrieval_only / *_only / compose: false until a future revision defines the mix.

8.1Controls

All controls are per-turn booleans or caps on the Query Document.

8.2Retrieval envelope (`output_json`)

When synthesis is skipped, output_json SHOULD match:

{
  "answered_by": "retrieval",
  "mode": "retrieval_only",
  "counts": { "chunks": 0, "artifacts": 0 },
  "chunks": [],
  "artifacts": [],
  "retrieval": {
    "query_variants": [],
    "keyword_query": null,
    "matched_artifacts": [],
    "entry_level": null,
    "expand_window": 0
  }
}

8.3Precedence

When multiple flags are set, the following resolution is RECOMMENDED (and used by the reference implementation):

1. chunks_only → no compose, kind = chunks
2. else artifacts_only → no compose, kind = artifacts
3. else retrieval_only or pointers_only → no compose, kind = both
4. else compose === false → no compose, kind = both
5. else → compose

8.4Prose output in retrieval modes

output MAY be empty or a short stub. Clients MUST treat output_json as the payload of record when answered_by is "retrieval".

9.1Required checks

9.2Soft rules

9.3Response validation

On completed with a shape, output_json MUST validate against that schema. On retrieval-only completion, output_json SHOULD carry answered_by: "retrieval".

9.4Error shape (recommended)

Transport-level errors SHOULD include a stable machine code and message:

{
  "error": {
    "code": "bad_request",
    "message": "ask is required"
  }
}

Query-level failures use status: "failed" and error string on the Response Document.

10.1Metadata filters — `where`

Exact-match (and later, richer) predicates over context metadata / fields.

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

Status: supported in the future.

10.2Field-level grounding — `ground`

Per-field citations and confidence on shaped results.

{
  "shape": { "…": "…" },
  "ground": { "per_field": true, "min_confidence": "medium" }
}

Status: supported in the future. 0.1.0 provides document-level citations only.

10.3Budget envelope — `budget`

First-class token, latency, and depth controls beyond timeout_seconds, max_steps, and thinking_level.

{
  "budget": { "max_tokens": 2000, "depth": "standard", "max_latency_ms": 5000 }
}

Status: supported in the future. Partial control exists today via timeout_seconds, max_steps, thinking_level, and model selection.

10.4Temporal — `as_of` / `since` / `window`

Time-travel and windowed knowledge views.

Status: supported in the future.

10.5Composition — `link` / `resolve`

Declarative cross-context joins and conflict precedence.

Status: supported in the future. 0.1.0 multi-context scope is a union of knowledge sources under one agent loop, not a join algebra.

10.6Explain — `explain`

Return an execution plan without running the turn.

Status: supported in the future. Partial observability exists via steps, rollup, and trace_ref on executed turns.

10.7Introspection

Schema discovery (__schema, context/field catalogs) as KnowQL documents.

Status: supported in the future. Implementations MAY expose catalogs via separate control-plane APIs.

10.8Textual DSL

A non-JSON surface syntax for KnowQL.

Status: supported in the future. 0.1.0 is JSON-only.

10.9Standardized cancel field

A request primitive to cancel an in-flight turn (vs out-of-band product API).

Status: supported in the future.

10.10Custom shape shorthand

Earlier drafts used a compact type language (Boolean!, Float, …). 0.1.0 standardizes on JSON Schema. A compact sugar MAY return in a later version as pure syntactic sugar over JSON Schema.

A.1Version

This document defines KnowQL version 0.1.0 (working draft), dated August 6, 2026.

A.2Conformance levels

A.3Conforming algorithms

Algorithms in this specification are normative with respect to their observable results. Implementations may use any equivalent strategy.

A.4Non-normative portions

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

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 under { } are object fields.
• ? following a component means it is optional.
• [ ] denotes a list (JSON array).
• { } denotes an object (JSON object).
• | separates alternatives.
• 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.

B.3B.3 Types used in prose