You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@ossie.apache.org by "eisber (via GitHub)" <gi...@apache.org> on 2026/10/06 19:10:52 UTC
[PR] docs: propose execute_query MCP interoperability profile [ossie]
eisber opened a new pull request, #529:
URL: https://github.com/apache/ossie/pull/529
## Proposal
Define an optional `execute_query` interoperability profile implemented by engines/catalogs, not an Ossie-hosted server or a core-model change.
- **Request:** source ID + native query string; optional language, required for multi-dialect bindings. Query syntax determines analytical limits; independent server ceilings are enforced and disclosed.
- **Result:** embedded CSV, optional exact previews, concise Markdown and extensible structured diagnostics. Includes reversible null encoding, exact numerics, locale-neutral values and honest completeness.
- **Lifecycle:** recommend negotiated MCP Tasks for long-running execution/materialization; no query generation, automatic repair or client-input round trips.
Adds the proposed contract, JSON Schemas, examples and conformance boundaries under `docs/proposals/`, linked from the documentation index. Existing model schemas, converters and runtime behavior are unchanged.
## Discussion
Related to [#510](https://github.com/apache/ossie/discussions/510) and the [dev@ execution-contract proposal](https://lists.apache.org/thread/olc629g9zmqgx66bo2hdl9hg0on6jtlg). Query execution complements model discovery/management; it does not settle the relational/declarative query proposals or imply community approval.
The draft uses pinned MCP tools/resources and Tasks specifications. Preview selection is guidance, not a fixed row cap; structured output is recommended with Markdown-only compatibility. CSV null/escape encoding and the diagnostic core are proposed for review.
## Validation
Documentation-only. Locally checked both JSON Schemas and all examples: 89 positive/negative schema cases against MCP latest/preview, legacy compatibility and Tasks definitions, plus dialect admission, preview/resource consistency, CSV null/escape and locale/precision round trips. `git diff --check` passes; ASF headers are present. No runtime/converter changes, dependencies or vendored source.
## AI assistance
Prepared with AI assistance; schema and example validation was executed locally.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@ossie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: propose Layer 3 execute_query MCP profile [ossie]
Posted by "christianeu-db (via GitHub)" <gi...@apache.org>.
christianeu-db commented on code in PR #529:
URL: https://github.com/apache/ossie/pull/529#discussion_r4333751337
##########
validation/mcp/execute-query-query.schema.json:
##########
@@ -0,0 +1,146 @@
+{
+ "$comment": "Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See NOTICE for copyright ownership. Licensed under the Apache License, Version 2.0; http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, distributed on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND. Generated by scripts/generate-mcp-profile.py; do not edit.",
+ "$id": "urn:apache:ossie:execute-query:query:0.4-draft",
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "$ref": "#/$defs/query",
+ "$defs": {
+ "expression": {
+ "type": "string",
+ "minLength": 1,
+ "pattern": "\\S"
+ },
+ "projection": {
+ "type": "array",
+ "items": {
+ "$ref": "#/$defs/expression"
+ }
+ },
+ "predicate": {
+ "oneOf": [
+ {
+ "$ref": "#/$defs/expression"
+ },
+ {
+ "type": "array",
+ "minItems": 1,
+ "items": {
+ "$ref": "#/$defs/expression"
+ }
+ }
+ ]
+ },
+ "query": {
Review Comment:
I'm wondering whether we could also support Layer 2 SQL.
This would use Ossie SQL's declarative extensions for querying measures on datasets via AGG(). Like Layer 3, these queries would ultimately be compiled to native SQL. For example, joins involving AGG() would likely be rewritten as correlated subqueries.
The reason I ask is that Layer 2 is now merged / we'll hopefully have some compliance tests for it soon.
Layer 3 still remains a draft (but hopefully, the community can align on an MVP to merge)
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@ossie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: propose Layer 3 execute_query MCP profile [ossie]
Posted by "orca-review-bot (via GitHub) via issues" <is...@ossie.apache.org>.
orca-review-bot commented on code in PR #529:
URL: https://github.com/apache/ossie/pull/529#discussion_r4608596487
##########
docs/proposals/execute-query-mcp.md:
##########
@@ -0,0 +1,682 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Proposal: `execute_query` MCP profile
+
+**Status:** Proposed, `0.4-draft`. An optional execution contract for engines and
+catalogs, not an Ossie server implementation or a condition of model conformance.
+MUST, SHOULD and MAY describe requirements of this proposed profile.
+
+## Scope
+
+Execute an agent-authored, read-only **Layer 3 query object resolved against an
+Ossie model**; return embedded data, optional previews and actionable diagnostics.
+The engine owns model resolution, safe planning and authorization; the calling
+agent owns analytical intent and correction. Native SQL/DAX/KQL execution,
+Layer 2 queries, query generation, writes, batches, federation, model
+authoring/conversion and client-input round trips are outside this profile.
+Adoption does not change the core model schema, converters, or API/CLI access.
+
+This complements model management/discovery rather than prescribing it:
+[MCP discussion #510](https://github.com/apache/ossie/discussions/510),
+[execution-contract proposal on dev@](https://lists.apache.org/thread/olc629g9zmqgx66bo2hdl9hg0on6jtlg),
+[specification versus implementation](https://lists.apache.org/thread/wpj5nnpodysds1vqd2s1vxhzw0vkcndy),
+and the [REST proposal](https://lists.apache.org/thread/hf71m6g1g1bnhqj5v0f4kc0rf4h8g4kg).
+Query semantics are those of the [Layer 3 Foundation draft][layer3], pinned to
+`cc0d0709` from [#246](https://github.com/apache/ossie/pull/246). This profile
+defines its JSON/MCP binding, not new join, grain or filter semantics.
+The dependency remains proposed, not an adopted standard. Layer 2's relational
+interface ([#354](https://github.com/apache/ossie/pull/354)) is separate.
+The [declarative-scope discussion](https://lists.apache.org/thread/9007r91vf33y04grtk8yn58nqc4oyco)
+motivates model-resolved input and direct semantic error codes.
+
+## Binding and request
+
+A catalog, REST API, MCP resource/tool or deployment configuration MUST expose
+the source's opaque `data_source_id`, bound **model identity and revision**,
+profile and Foundation revisions, supported query shapes/capabilities, output
+formats, diagnostic capabilities and execution/materialization ceilings.
+Each call MUST resolve against one fixed authorized model revision; successful
+results identify it. No mandatory discovery endpoint or core model connection
+property is introduced.
+The server MUST resolve and authorize the binding for the caller; model names
+and dataset sources are not credentials or globally unique execution IDs.
+An execution binding ID MUST NOT be reassigned to a different model or revision;
+updating the model publishes a new binding, and retired IDs return
+`SOURCE_UNAVAILABLE`. This prevents an agent's discovered model from being
+silently replaced between discovery and execution.
+
+Tool name: `execute_query`. `inputSchema`:
+
+```json
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["data_source_id", "query"],
+ "properties": {
+ "data_source_id": { "type": "string", "minLength": 1, "pattern": "\\S" },
+ "query": { "$ref": "#/$defs/query" }
+ },
+ "$defs": {
+ "expression": { "type": "string", "minLength": 1, "pattern": "\\S" },
+ "projection": { "type": "array", "items": { "$ref": "#/$defs/expression" } },
+ "predicate": {
+ "oneOf": [
+ { "$ref": "#/$defs/expression" },
+ { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/expression" } }
+ ]
+ },
+ "query": {
+ "type": "object", "additionalProperties": false,
+ "properties": {
+ "dimensions": { "$ref": "#/$defs/projection" },
+ "measures": { "$ref": "#/$defs/projection" },
Review Comment:
Main's Layer 3 calls these `metrics` (wide_table_semantics.md ยง3.2). Can we rename here and in the output schema `$defs`? The query part is `filter` there, not `where`.
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
##########
docs/proposals/execute-query-mcp.md:
##########
@@ -0,0 +1,682 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Proposal: `execute_query` MCP profile
+
+**Status:** Proposed, `0.4-draft`. An optional execution contract for engines and
+catalogs, not an Ossie server implementation or a condition of model conformance.
+MUST, SHOULD and MAY describe requirements of this proposed profile.
+
+## Scope
+
+Execute an agent-authored, read-only **Layer 3 query object resolved against an
+Ossie model**; return embedded data, optional previews and actionable diagnostics.
+The engine owns model resolution, safe planning and authorization; the calling
+agent owns analytical intent and correction. Native SQL/DAX/KQL execution,
+Layer 2 queries, query generation, writes, batches, federation, model
+authoring/conversion and client-input round trips are outside this profile.
+Adoption does not change the core model schema, converters, or API/CLI access.
+
+This complements model management/discovery rather than prescribing it:
+[MCP discussion #510](https://github.com/apache/ossie/discussions/510),
+[execution-contract proposal on dev@](https://lists.apache.org/thread/olc629g9zmqgx66bo2hdl9hg0on6jtlg),
+[specification versus implementation](https://lists.apache.org/thread/wpj5nnpodysds1vqd2s1vxhzw0vkcndy),
+and the [REST proposal](https://lists.apache.org/thread/hf71m6g1g1bnhqj5v0f4kc0rf4h8g4kg).
+Query semantics are those of the [Layer 3 Foundation draft][layer3], pinned to
+`cc0d0709` from [#246](https://github.com/apache/ossie/pull/246). This profile
Review Comment:
This pins Layer 3 to #246 `cc0d0709`, but main now has `core-spec/wide_table_semantics.md` with a different query surface (`dimensions`/`metrics`/`filter`). Can we pin to that, or say why #246 is still the target?
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
##########
scripts/generate-mcp-profile.py:
##########
@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Publish executable schemas and an endpoint capture from the profile examples."""
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+PROFILE = ROOT / "docs/proposals/execute-query-mcp.md"
+DESTINATION = ROOT / "validation/mcp"
+LICENSE = (
+ "Licensed to the Apache Software Foundation (ASF) under one or more "
+ "contributor license agreements. See NOTICE for copyright ownership. "
+ "Licensed under the Apache License, Version 2.0; "
+ "http://www.apache.org/licenses/LICENSE-2.0 . "
+ "Unless required by applicable law or agreed to in writing, distributed "
+ "on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND."
+)
+
+
+def generated_files() -> dict[str, str]:
+ blocks = [
+ json.loads(block)
+ for block in re.findall(r"```json\n(.*?)\n```", PROFILE.read_text(encoding="utf-8"), re.S)
+ ]
+ schemas = [block for block in blocks if "$schema" in block]
Review Comment:
nit: this breaks as soon as the doc gains another block with `$schema`. Can we select the input/output schemas by an explicit marker instead, e.g. a ```json input-schema info string?
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
##########
docs/proposals/execute-query-mcp.md:
##########
@@ -0,0 +1,682 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Proposal: `execute_query` MCP profile
+
+**Status:** Proposed, `0.4-draft`. An optional execution contract for engines and
+catalogs, not an Ossie server implementation or a condition of model conformance.
+MUST, SHOULD and MAY describe requirements of this proposed profile.
+
+## Scope
+
+Execute an agent-authored, read-only **Layer 3 query object resolved against an
+Ossie model**; return embedded data, optional previews and actionable diagnostics.
+The engine owns model resolution, safe planning and authorization; the calling
+agent owns analytical intent and correction. Native SQL/DAX/KQL execution,
+Layer 2 queries, query generation, writes, batches, federation, model
+authoring/conversion and client-input round trips are outside this profile.
+Adoption does not change the core model schema, converters, or API/CLI access.
+
+This complements model management/discovery rather than prescribing it:
+[MCP discussion #510](https://github.com/apache/ossie/discussions/510),
+[execution-contract proposal on dev@](https://lists.apache.org/thread/olc629g9zmqgx66bo2hdl9hg0on6jtlg),
+[specification versus implementation](https://lists.apache.org/thread/wpj5nnpodysds1vqd2s1vxhzw0vkcndy),
+and the [REST proposal](https://lists.apache.org/thread/hf71m6g1g1bnhqj5v0f4kc0rf4h8g4kg).
+Query semantics are those of the [Layer 3 Foundation draft][layer3], pinned to
+`cc0d0709` from [#246](https://github.com/apache/ossie/pull/246). This profile
+defines its JSON/MCP binding, not new join, grain or filter semantics.
+The dependency remains proposed, not an adopted standard. Layer 2's relational
+interface ([#354](https://github.com/apache/ossie/pull/354)) is separate.
+The [declarative-scope discussion](https://lists.apache.org/thread/9007r91vf33y04grtk8yn58nqc4oyco)
+motivates model-resolved input and direct semantic error codes.
+
+## Binding and request
+
+A catalog, REST API, MCP resource/tool or deployment configuration MUST expose
+the source's opaque `data_source_id`, bound **model identity and revision**,
+profile and Foundation revisions, supported query shapes/capabilities, output
+formats, diagnostic capabilities and execution/materialization ceilings.
+Each call MUST resolve against one fixed authorized model revision; successful
+results identify it. No mandatory discovery endpoint or core model connection
+property is introduced.
+The server MUST resolve and authorize the binding for the caller; model names
+and dataset sources are not credentials or globally unique execution IDs.
+An execution binding ID MUST NOT be reassigned to a different model or revision;
+updating the model publishes a new binding, and retired IDs return
+`SOURCE_UNAVAILABLE`. This prevents an agent's discovered model from being
+silently replaced between discovery and execution.
+
+Tool name: `execute_query`. `inputSchema`:
+
+```json
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["data_source_id", "query"],
+ "properties": {
+ "data_source_id": { "type": "string", "minLength": 1, "pattern": "\\S" },
+ "query": { "$ref": "#/$defs/query" }
+ },
+ "$defs": {
+ "expression": { "type": "string", "minLength": 1, "pattern": "\\S" },
+ "projection": { "type": "array", "items": { "$ref": "#/$defs/expression" } },
+ "predicate": {
+ "oneOf": [
+ { "$ref": "#/$defs/expression" },
+ { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/expression" } }
+ ]
+ },
+ "query": {
+ "type": "object", "additionalProperties": false,
+ "properties": {
+ "dimensions": { "$ref": "#/$defs/projection" },
+ "measures": { "$ref": "#/$defs/projection" },
+ "fields": { "allOf": [{ "$ref": "#/$defs/projection" }], "minItems": 1 },
+ "where": { "$ref": "#/$defs/predicate" },
+ "having": { "$ref": "#/$defs/predicate" },
+ "order_by": {
Review Comment:
`order_by`, `limit`, `fields` and `having` aren't Layer 3 parts on main. ยง3.2 says sorting, limits, row listings and metric predicates are not supported. Should these be dropped, or marked as profile extensions?
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
##########
scripts/generate-mcp-profile.py:
##########
@@ -0,0 +1,103 @@
+#!/usr/bin/env python3
+# Licensed to the Apache Software Foundation (ASF) under one
+# or more contributor license agreements. See the NOTICE file
+# distributed with this work for additional information
+# regarding copyright ownership. The ASF licenses this file
+# to you under the Apache License, Version 2.0 (the
+# "License"); you may not use this file except in compliance
+# with the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing,
+# software distributed under the License is distributed on an
+# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+# KIND, either express or implied. See the License for the
+# specific language governing permissions and limitations
+# under the License.
+
+"""Publish executable schemas and an endpoint capture from the profile examples."""
+
+import argparse
+import json
+import re
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+PROFILE = ROOT / "docs/proposals/execute-query-mcp.md"
+DESTINATION = ROOT / "validation/mcp"
+LICENSE = (
+ "Licensed to the Apache Software Foundation (ASF) under one or more "
+ "contributor license agreements. See NOTICE for copyright ownership. "
+ "Licensed under the Apache License, Version 2.0; "
+ "http://www.apache.org/licenses/LICENSE-2.0 . "
+ "Unless required by applicable law or agreed to in writing, distributed "
+ "on an AS IS BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND."
+)
+
+
+def generated_files() -> dict[str, str]:
+ blocks = [
+ json.loads(block)
+ for block in re.findall(r"```json\n(.*?)\n```", PROFILE.read_text(encoding="utf-8"), re.S)
+ ]
+ schemas = [block for block in blocks if "$schema" in block]
+ if len(schemas) != 2:
+ raise ValueError("Expected exactly the input and output schemas in the profile")
+ inputs, outputs = schemas
+ for name in ("expression", "projection", "predicate", "query"):
+ if inputs["$defs"][name] != outputs["$defs"][name]:
+ raise ValueError(f"Request and replacement query definitions differ: {name}")
+ version = outputs["properties"]["contract_version"]["const"]
+ query = {
+ "$schema": inputs["$schema"],
+ "$ref": "#/$defs/query",
+ "$defs": {key: inputs["$defs"][key] for key in ("expression", "projection", "predicate", "query")},
+ }
+ files = {}
+ for name, schema in (("input", inputs), ("output", outputs), ("query", query)):
+ schema = {
+ "$comment": LICENSE + " Generated by scripts/generate-mcp-profile.py; do not edit.",
+ "$id": f"urn:apache:ossie:execute-query:{name}:{version}",
+ **schema,
+ }
+ files[f"execute-query-{name}.schema.json"] = json.dumps(schema, indent=2) + "\n"
+ arguments = next(block for block in blocks if "data_source_id" in block)
Review Comment:
nit: this binds to whichever example with `data_source_id` comes first. Can we tag the canonical example so reordering the doc can't swap it?
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
##########
docs/proposals/execute-query-mcp.md:
##########
@@ -0,0 +1,682 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Proposal: `execute_query` MCP profile
+
+**Status:** Proposed, `0.4-draft`. An optional execution contract for engines and
+catalogs, not an Ossie server implementation or a condition of model conformance.
+MUST, SHOULD and MAY describe requirements of this proposed profile.
+
+## Scope
+
+Execute an agent-authored, read-only **Layer 3 query object resolved against an
+Ossie model**; return embedded data, optional previews and actionable diagnostics.
+The engine owns model resolution, safe planning and authorization; the calling
+agent owns analytical intent and correction. Native SQL/DAX/KQL execution,
+Layer 2 queries, query generation, writes, batches, federation, model
+authoring/conversion and client-input round trips are outside this profile.
+Adoption does not change the core model schema, converters, or API/CLI access.
+
+This complements model management/discovery rather than prescribing it:
+[MCP discussion #510](https://github.com/apache/ossie/discussions/510),
+[execution-contract proposal on dev@](https://lists.apache.org/thread/olc629g9zmqgx66bo2hdl9hg0on6jtlg),
+[specification versus implementation](https://lists.apache.org/thread/wpj5nnpodysds1vqd2s1vxhzw0vkcndy),
+and the [REST proposal](https://lists.apache.org/thread/hf71m6g1g1bnhqj5v0f4kc0rf4h8g4kg).
+Query semantics are those of the [Layer 3 Foundation draft][layer3], pinned to
+`cc0d0709` from [#246](https://github.com/apache/ossie/pull/246). This profile
+defines its JSON/MCP binding, not new join, grain or filter semantics.
+The dependency remains proposed, not an adopted standard. Layer 2's relational
+interface ([#354](https://github.com/apache/ossie/pull/354)) is separate.
+The [declarative-scope discussion](https://lists.apache.org/thread/9007r91vf33y04grtk8yn58nqc4oyco)
+motivates model-resolved input and direct semantic error codes.
+
+## Binding and request
+
+A catalog, REST API, MCP resource/tool or deployment configuration MUST expose
+the source's opaque `data_source_id`, bound **model identity and revision**,
+profile and Foundation revisions, supported query shapes/capabilities, output
+formats, diagnostic capabilities and execution/materialization ceilings.
+Each call MUST resolve against one fixed authorized model revision; successful
+results identify it. No mandatory discovery endpoint or core model connection
+property is introduced.
+The server MUST resolve and authorize the binding for the caller; model names
+and dataset sources are not credentials or globally unique execution IDs.
+An execution binding ID MUST NOT be reassigned to a different model or revision;
+updating the model publishes a new binding, and retired IDs return
+`SOURCE_UNAVAILABLE`. This prevents an agent's discovered model from being
+silently replaced between discovery and execution.
+
+Tool name: `execute_query`. `inputSchema`:
+
+```json
+{
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
+ "type": "object",
+ "additionalProperties": false,
+ "required": ["data_source_id", "query"],
+ "properties": {
+ "data_source_id": { "type": "string", "minLength": 1, "pattern": "\\S" },
+ "query": { "$ref": "#/$defs/query" }
+ },
+ "$defs": {
+ "expression": { "type": "string", "minLength": 1, "pattern": "\\S" },
+ "projection": { "type": "array", "items": { "$ref": "#/$defs/expression" } },
+ "predicate": {
+ "oneOf": [
+ { "$ref": "#/$defs/expression" },
+ { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/expression" } }
+ ]
+ },
+ "query": {
+ "type": "object", "additionalProperties": false,
+ "properties": {
+ "dimensions": { "$ref": "#/$defs/projection" },
+ "measures": { "$ref": "#/$defs/projection" },
+ "fields": { "allOf": [{ "$ref": "#/$defs/projection" }], "minItems": 1 },
+ "where": { "$ref": "#/$defs/predicate" },
+ "having": { "$ref": "#/$defs/predicate" },
+ "order_by": {
+ "type": "array", "minItems": 1,
+ "items": {
+ "type": "object", "additionalProperties": false, "required": ["field"],
+ "properties": {
+ "field": { "$ref": "#/$defs/expression" },
+ "direction": { "enum": ["ASC", "DESC"] },
+ "nulls": { "enum": ["FIRST", "LAST"] }
+ }
+ }
+ },
+ "limit": { "type": "integer", "minimum": 0 }
+ },
+ "oneOf": [
+ {
+ "not": { "required": ["fields"] },
+ "anyOf": [
+ { "required": ["dimensions"], "properties": { "dimensions": { "minItems": 1 } } },
+ { "required": ["measures"], "properties": { "measures": { "minItems": 1 } } }
+ ]
+ },
+ {
+ "required": ["fields"],
+ "not": { "anyOf": [{ "required": ["dimensions"] }, { "required": ["measures"] }, { "required": ["having"] }] }
+ }
+ ]
+ }
+ }
+}
+```
+
+### Layer 3 surface and interpretation
+
+This schema serializes Foundation section 5, not a native query inside JSON.
+Property names are lowercase; `query` contains the clauses directly,
+without another `query` wrapper. All expression strings use the portable
+`OSSIE_SQL_2026` expression language and resolve only against the bound model.
+Statement text, native dialects, connection properties, query parameters, joins,
+grain overrides and undeclared clauses are outside the surface.
+
+| Clause / shape | Contract |
+| --- | --- |
+| Aggregation | `dimensions` and/or `measures`, at least one nonempty. Omitted arrays mean empty. No `fields`; empty dimensions request totals. |
+| Scalar | Nonempty `fields`; no `dimensions`, `measures` or `having`, even if empty. Foundation table-grain and fan-out rules apply. |
+| Projections | Dimensions/fields/metrics, ad-hoc expressions and aliases follow Foundation section 5 and its expression subset. Schema validity alone does not establish name, type, grain or expression validity. |
+| `where` / `having` | One predicate string or a nonempty list interpreted as AND. Row-level versus aggregate/window predicates follow Foundation sections 6.3/6.10; OR is inside an expression. |
+| `order_by` | Objects containing `field` (in-scope name or projection-valid expression), optional `direction` (default `ASC`) and `nulls`. `nulls: FIRST/LAST` explicitly serializes section 5's NULL placement; defaults are ASC/LAST, DESC/FIRST. Positional ordinals are not allowed. |
+| `limit` | Nonnegative integer bounding final query rows, including zero; absent means no query-authored cap. Accepted without ordering, but no stable row selection is implied. Server ceilings are independent and any resulting truncation is disclosed. |
+
+The engine resolves names, relationships, join paths and grain-safe aggregation
+according to the pinned Foundation, not backend-native semantics. Implementation
+may compile to SQL/DAX or another engine representation internally; that does
+not change the accepted interface or its meaning. Model expressions without a
+supported semantics-preserving evaluation MUST be refused, not interpreted as
+native text or silently dropped.
+
+Bindings MUST advertise supported shapes and capability restrictions (such as
+M:N traversal, windows, multi-fact queries or path length). Partial implementations
+MUST refuse unsupported cases explicitly; exposing this MCP profile does not
+claim full Foundation conformance. Reuse an applicable Foundation refusal code
+where defined; otherwise return `UNSUPPORTED_QUERY` with the missing capability.
+Unsettled Foundation semantics are resolved there, not by inventing backend
+defaults here; implementations unable to guarantee the declared semantics MUST
+refuse the case. Shape-only tests do not establish equivalent answers.
+
+Each call returns one table. Semantics-preserving compilation is expected;
+semantic query mutation, automatic repair/retry, broadened filters, source
+fallback and discarded result tables are prohibited. No `language`, connection,
+impersonation, external limits or diagnostic arguments are accepted.
+Suggested annotations are `readOnlyHint: true`,
+`destructiveHint: false` and an `openWorldHint` reflecting the actual deployment;
+annotations are not enforcement or an idempotence guarantee.
+
+## Results
+
+A final `CallToolResult` MUST contain concise Markdown-readable status,
+completeness, attachment names and applicable guidance. Successful calls,
+including zero rows, use `isError: false`; tool failures use `isError: true`.
+Malformed MCP envelopes, unknown tools and protocol-capability failures use
+protocol errors instead. No failure may masquerade as successful empty data.
+
+Structured output is RECOMMENDED. A tool advertising `outputSchema` MUST supply
+conforming `structuredContent` on success and tool errors; Markdown-only
+compatibility MAY omit both. `outputSchema` constrains that object, not content
+blocks or Task handles. Text, structured fields and embedded resources MUST
+agree. MCP's recommended serialized-JSON text fallback SHOULD be provided
+where needed, without duplicating the full dataset in prose.
+Every successful result MUST identify the evaluated model and revision;
+Markdown-only results carry that identity in text or resource metadata.
+
+### Data and previews
+
+Success MUST include CSV as an embedded MCP resource: `type: "resource"` with
+`resource.uri`, `mimeType: "text/csv"` and `text`. Known-schema zero-row results
+produce header-only CSV; missing column schema is an explicit unsupported-result
+error. Optional XLSX/Parquet use separate base64 `resource.blob` blocks with
+`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` or
+`application/vnd.apache.parquet`. All formats represent the same materialized
+rows, columns and values, without re-execution.
+
+Use safe, distinct filename-like URI labels (`file:///sales.csv`), not private
+paths or credentials. Embedded bytes are already in the response; the URI
+implies neither a physical file nor `resources/read`. Hosts determine how to
+save/expose attachments. Resource links do not replace embedded CSV in this
+profile. If delivery exceeds policy, return `RESOURCE_LIMIT` with narrowing
+guidance, not preview-only success. Base64 overhead counts toward ceilings;
+Tasks solve latency, not payload size. Servers embedding resources SHOULD
+implement the resources capability, without promising retrieval of every label.
+
+Preview selection is non-normative guidance; no row count or first-row rule is
+required:
+
+| Selection | Recommended use |
+| --- | --- |
+| First few rows, often 5-10 | Economical default; without ordering these are not ranked "top" rows. |
+| All rows | Small results within a cell/byte budget. |
+| Labeled sample | Exploration; no implied order or statistical representativeness. |
+| No preview | Wide/large values; retain column metadata and embedded data. |
+
+An optional structured preview MUST preserve exact cells, positional column
+arity and JSON nulls; it MUST NOT synthesize statistics as query rows. Shortened
+Markdown cells MUST be labeled and retain originals in CSV. Display selection
+does not change execution. `preview.row_count` equals displayed rows;
+`result.row_count` equals materialized rows excluding the header;
+`preview.has_more` equals `result.row_count > preview.row_count`.
+Independently, `result.completeness` is `complete` only with evidence of query
+exhaustion, `truncated` with evidence of omitted rows, otherwise `unknown`.
+Query-authored `limit` is query semantics, not export truncation. Capped or
+sampled materializations MUST NOT be described as complete.
+
+### Diagnostics
+
+Every final result includes diagnostic availability, suggestions and filter
+alternatives; empty arrays are valid. Applicable enrichment SHOULD be produced
+under server policy, not an input flag. Supplemental probes MUST share caller
+authorization, RLS/OLS and aggregate budgets. Partial/unavailable enrichment
+requires an explanation, not an implied exhaustive search or a changed primary
+query outcome. Zero rows remain success.
+
+Suggestions are advice: `replacement_query` is a complete **Layer 3 object
+matching the same query schema**, not native text, a JSON-encoded string or a
+patch. It remains scoped to the same source/model and is never automatically
+executed. Static examples are not verified query results.
+Alternatives identify candidates for the original authorized filter field;
+cross-field hints belong in suggestions. Their `complete` flag concerns
+candidate search, not query completeness. Unauthorized names/values, connection
+strings, credentials and stack traces MUST NOT appear in diagnostics.
+
+The structured core is extensible through namespaced object-valued `extensions`;
+clients MUST tolerate unfamiliar extension keys, error codes and guidance kinds,
+but extensions cannot override core status, access or execution semantics.
+Common codes: `INVALID_ARGUMENT`, `SOURCE_UNAVAILABLE`, `UNSUPPORTED_QUERY`,
+`QUERY_REJECTED`, `QUERY_INVALID`, `PERMISSION_DENIED`, `TIMEOUT`, `CANCELLED`,
+`RESOURCE_LIMIT`, `BACKEND_ERROR`. `SOURCE_UNAVAILABLE` may conceal inaccessible
+bindings; error source IDs echo supplied values, not privileged resolved IDs.
+Guidance kinds include `name`, `query`, `filter`, `limit`, `diagnostic`.
+
+Foundation semantic refusals MUST appear unchanged in **`error.code`**, not
+only in `extensions` or flattened to `QUERY_INVALID`. For example,
+`E_NAME_NOT_FOUND`, `E_NO_PATH`, `E_AMBIGUOUS_PATH` and
+`E3013_NO_STITCHING_DIMENSION` retain their defined triggers.
+Mixed/empty query shapes use `E_MIXED_QUERY_SHAPE`,
Review Comment:
`E_MIXED_QUERY_SHAPE`, `E_EMPTY_SCALAR_QUERY` (and `E3013_NO_STITCHING_DIMENSION` at :254) aren't in main's error list. Also, the inputSchema already rejects empty/mixed shapes, so a host validating arguments never reaches these codes. Can we say which code (`INVALID_ARGUMENT` vs the Foundation code) clients should expect here?
<sub>๐ค AI-generated review comment โ agents make mistakes, so please verify before acting on it.</sub>
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@ossie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: propose execute_query MCP interoperability profile [ossie]
Posted by "jbonofre (via GitHub)" <gi...@apache.org>.
jbonofre commented on PR #529:
URL: https://github.com/apache/ossie/pull/529#issuecomment-6038615653
@christianeu-db I replied on the mailing list.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@ossie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: propose execute_query MCP interoperability profile [ossie]
Posted by "christianeu-db (via GitHub)" <gi...@apache.org>.
christianeu-db commented on PR #529:
URL: https://github.com/apache/ossie/pull/529#issuecomment-6028339862
@jbonofre curious on your take on [this thread](https://lists.apache.org/thread/y7zdqybc1c83hfovqmlp15fnh756m0do). Directionally, is an Ossie MCP interopability meant to be tied to Ossie semantics? Is the goal to guide clients toward portable Ossie query interfaces, or also to standardize the execution of vendor-specific query languages compiled outside Ossie?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: issues-unsubscribe@ossie.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org