MCP tool schemas
This page is the consolidated input/output reference for the seven Metatate Cloud MCP tools. Every input and output key is snake_case; each tool also accepts a 1:1 hyphenated protocol alias (authorize-use for authorize_use, and so on — underscores replaced by hyphens, nothing more). The server speaks MCP over HTTP and authenticates every request with a bearer workspace access token; see Connect an agent. Each accepted tool invocation consumes exactly one metered MCP call, charged before any read — a schema-rejected input (invalid_parameters) is not metered.
Schemas below are JSON-Schema-style renderings of the server's validators. Inputs are strict: unknown keys are rejected. Outputs of decision-bearing tools are discriminated unions on state — see Typed answer states. Per-tool behavior lives on the tool pages: discover_context, get_decision_context, inspect_data_meaning, inspect_governance_rules, authorize_use, validate_query_context, explain_why.
Shared shapesDirect link to Shared shapes
The tool schemas below reference these definitions via #/$defs/.... They are defined once here.
{
"$defs": {
"identifier": { "type": "string", "minLength": 1, "maxLength": 255 },
"uuid": { "type": "string", "format": "uuid" },
"scenario_key": {
"type": "string",
"description": "One of the 65 canonical scenario keys, e.g. access.read, masking.display, ai.training, ai.inference, purpose.allowed_use, purpose.prohibited_use, residency.cross_border_transfer."
},
"scenario_lane": { "type": "string", "enum": ["platform", "agent", "human"] },
"instruction_decision": {
"type": "string",
"enum": ["allow", "deny", "mask_full", "mask_partial", "require_review", "log_only", "retain", "conditional"]
},
"transfer_token": {
"type": "string",
"minLength": 1,
"maxLength": 64,
"pattern": "^[A-Za-z0-9][A-Za-z0-9 _.-]*$"
},
"asset_ref": {
"type": "object",
"additionalProperties": false,
"required": ["database", "schema", "table"],
"properties": {
"database": { "$ref": "#/$defs/identifier" },
"schema": { "$ref": "#/$defs/identifier" },
"table": { "$ref": "#/$defs/identifier" },
"column": { "$ref": "#/$defs/identifier" }
}
},
"asset_scope": {
"type": "object",
"additionalProperties": false,
"required": ["database", "schema", "table", "column"],
"properties": {
"database": { "$ref": "#/$defs/identifier" },
"schema": { "$ref": "#/$defs/identifier" },
"table": { "$ref": "#/$defs/identifier" },
"column": { "anyOf": [{ "$ref": "#/$defs/identifier" }, { "type": "null" }] }
}
},
"publication": {
"type": "object",
"additionalProperties": false,
"required": ["publication_id", "published_at"],
"properties": {
"publication_id": { "$ref": "#/$defs/uuid" },
"published_at": { "type": "string", "minLength": 1, "maxLength": 64 }
}
},
"provenance": {
"type": "object",
"additionalProperties": false,
"required": ["policy_id", "policy_version_id", "policy_name", "version_number"],
"properties": {
"policy_id": { "$ref": "#/$defs/uuid" },
"policy_version_id": { "$ref": "#/$defs/uuid" },
"policy_name": { "type": "string", "minLength": 1, "maxLength": 64 },
"version_number": { "type": "integer", "minimum": 1 }
}
},
"resolution_path": {
"type": "object",
"additionalProperties": false,
"required": ["source", "ref"],
"properties": {
"source": { "type": "string", "enum": ["selector", "collection", "taxonomy"] },
"ref": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 }
}
},
"conflict_ref": {
"type": "object",
"additionalProperties": false,
"required": ["policy_version_id", "instruction_key", "decision"],
"properties": {
"policy_version_id": { "type": ["string", "null"], "minLength": 1, "maxLength": 128 },
"instruction_key": { "type": ["string", "null"], "minLength": 1, "maxLength": 256 },
"decision": { "$ref": "#/$defs/instruction_decision" }
}
},
"instruction_record": {
"type": "object",
"additionalProperties": false,
"required": [
"decision_id", "instruction_key", "instruction_family", "scenario_key",
"scenario_lane", "category", "priority", "weight", "enforcement_mode",
"decision", "decision_reason", "parameters", "scope", "provenance",
"primary_resolution_source", "resolution_paths", "conflict_status",
"conflict_group_id", "conflicts_with"
],
"properties": {
"decision_id": { "$ref": "#/$defs/uuid" },
"instruction_key": { "type": "string", "minLength": 1, "maxLength": 256 },
"instruction_family": { "type": "string", "minLength": 1, "maxLength": 64 },
"scenario_key": { "$ref": "#/$defs/scenario_key" },
"scenario_lane": { "$ref": "#/$defs/scenario_lane" },
"category": { "type": "string", "enum": ["enforceable", "advisory"] },
"priority": { "type": "integer", "minimum": 0, "maximum": 3 },
"weight": { "type": "number", "minimum": 0 },
"enforcement_mode": { "type": "string", "enum": ["enforce", "monitor", "advisory"] },
"decision": { "$ref": "#/$defs/instruction_decision" },
"decision_reason": { "type": "string", "minLength": 1, "maxLength": 2000 },
"parameters": {
"type": "object",
"description": "Extracted policy DSL parameters served verbatim. Keys inside follow the authoring-side policy DSL — the documented exemption from the snake_case wire convention."
},
"scope": { "$ref": "#/$defs/asset_scope" },
"provenance": { "$ref": "#/$defs/provenance" },
"primary_resolution_source": { "type": "string", "enum": ["selector", "collection", "taxonomy"] },
"resolution_paths": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/resolution_path" } },
"conflict_status": { "type": "string", "enum": ["none", "conflicted"] },
"conflict_group_id": { "anyOf": [{ "$ref": "#/$defs/uuid" }, { "type": "null" }] },
"conflicts_with": { "type": "array", "items": { "$ref": "#/$defs/conflict_ref" } }
}
},
"conflict_group": {
"type": "object",
"additionalProperties": false,
"required": ["group_id", "sources"],
"properties": {
"group_id": { "anyOf": [{ "$ref": "#/$defs/uuid" }, { "type": "null" }] },
"sources": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/instruction_record" } }
}
},
"context_facts": {
"type": "object",
"additionalProperties": false,
"required": ["sensitivity", "category", "subcategory", "pii", "masking"],
"properties": {
"sensitivity": { "type": ["string", "null"], "minLength": 1, "maxLength": 64 },
"category": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
"subcategory": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
"pii": { "type": "boolean" },
"masking": {
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"required": ["type", "exempt_roles"],
"properties": {
"type": { "type": "string", "minLength": 1, "maxLength": 255 },
"exempt_roles": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 } }
}
},
{ "type": "null" }
]
}
}
},
"unresolved_target": {
"type": "object",
"additionalProperties": false,
"required": ["policy_name", "instruction_key", "kind", "ref", "reason"],
"properties": {
"policy_name": { "type": "string", "minLength": 1, "maxLength": 64 },
"instruction_key": { "type": ["string", "null"], "minLength": 1, "maxLength": 256 },
"kind": { "type": "string", "enum": ["selector", "collection", "taxonomy"] },
"ref": { "type": "string", "minLength": 1, "maxLength": 255 },
"reason": { "type": "string", "enum": ["no_match", "empty_collection", "unknown_type", "stale_member"] }
}
},
"not_enough_reason_code": {
"type": "string",
"enum": ["no_current_publication", "no_published_instruction_state", "unresolved_published_target", "scenario_unresolved"]
},
"review_reason_code": {
"type": "string",
"enum": ["decision_requires_review", "conflicted_published_state"]
},
"next_actions": {
"type": "array",
"items": { "type": "string", "minLength": 1, "maxLength": 256 }
}
}
}
discover_contextDirect link to discover_context
Alias discover-context. The domain, sensitivity, pii, and compliance_tag filters are accepted by the input schema but currently answer with a not_supported error.
Input:
{
"type": "object",
"additionalProperties": false,
"required": [],
"properties": {
"database": { "$ref": "#/$defs/identifier" },
"schema": { "$ref": "#/$defs/identifier" },
"domain": { "$ref": "#/$defs/identifier" },
"sensitivity": { "type": "string", "enum": ["public", "internal", "confidential", "restricted"] },
"pii": { "type": "boolean" },
"compliance_tag": { "type": "string", "minLength": 1, "maxLength": 255 }
}
}
Output:
{
"oneOf": [
{
"title": "answered",
"type": "object",
"additionalProperties": false,
"required": ["state", "assets", "publication"],
"properties": {
"state": { "const": "answered" },
"assets": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["ref", "instruction_count", "scenario_keys"],
"properties": {
"ref": { "$ref": "#/$defs/asset_scope" },
"instruction_count": { "type": "integer", "minimum": 0 },
"scenario_keys": { "type": "array", "items": { "$ref": "#/$defs/scenario_key" } }
}
}
},
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "not_enough_published_state",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "message", "unresolved_targets", "next_actions"],
"properties": {
"state": { "const": "not_enough_published_state" },
"reason_code": { "$ref": "#/$defs/not_enough_reason_code" },
"message": { "type": "string", "minLength": 1, "maxLength": 300 },
"unresolved_targets": { "type": "array", "items": { "$ref": "#/$defs/unresolved_target" } },
"next_actions": { "$ref": "#/$defs/next_actions" }
}
}
]
}
get_decision_contextDirect link to get_decision_context
Alias get-decision-context. At least one of asset or proposed_use is required; proposed_use without an asset currently answers not_supported.
Input:
{
"type": "object",
"additionalProperties": false,
"anyOf": [{ "required": ["asset"] }, { "required": ["proposed_use"] }],
"properties": {
"asset": { "$ref": "#/$defs/asset_ref" },
"proposed_use": { "type": "string", "minLength": 1, "maxLength": 2000 },
"scenario_key": { "$ref": "#/$defs/scenario_key" }
}
}
Output:
{
"oneOf": [
{
"title": "answered",
"type": "object",
"additionalProperties": false,
"required": ["state", "asset", "scenario_key", "decisions", "effective_decision", "business_context", "publication"],
"properties": {
"state": { "const": "answered" },
"asset": { "$ref": "#/$defs/asset_scope" },
"scenario_key": { "anyOf": [{ "$ref": "#/$defs/scenario_key" }, { "type": "null" }] },
"decisions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/instruction_record" } },
"effective_decision": { "$ref": "#/$defs/instruction_decision" },
"business_context": {
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"required": ["owner", "steward", "domain", "purpose"],
"properties": {
"owner": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
"steward": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
"domain": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
"purpose": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000 }
}
},
{ "type": "null" }
]
},
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "review_required",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "asset", "scenario_key", "decisions", "conflict", "next_actions", "publication"],
"properties": {
"state": { "const": "review_required" },
"reason_code": { "$ref": "#/$defs/review_reason_code" },
"asset": { "$ref": "#/$defs/asset_scope" },
"scenario_key": { "anyOf": [{ "$ref": "#/$defs/scenario_key" }, { "type": "null" }] },
"decisions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/instruction_record" } },
"conflict": { "anyOf": [{ "$ref": "#/$defs/conflict_group" }, { "type": "null" }] },
"next_actions": { "$ref": "#/$defs/next_actions" },
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "not_enough_published_state",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "message", "unresolved_targets", "next_actions", "asset", "scenario_key"],
"properties": {
"state": { "const": "not_enough_published_state" },
"reason_code": { "$ref": "#/$defs/not_enough_reason_code" },
"message": { "type": "string", "minLength": 1, "maxLength": 300 },
"unresolved_targets": { "type": "array", "items": { "$ref": "#/$defs/unresolved_target" } },
"next_actions": { "$ref": "#/$defs/next_actions" },
"asset": { "$ref": "#/$defs/asset_scope" },
"scenario_key": { "anyOf": [{ "$ref": "#/$defs/scenario_key" }, { "type": "null" }] }
}
}
]
}
inspect_data_meaningDirect link to inspect_data_meaning
Alias inspect-data-meaning. Returns published facts, not a decision — the output is a single object with no state field. An unresolvable ref is an asset_not_found error.
Input:
{
"type": "object",
"additionalProperties": false,
"required": ["ref"],
"properties": {
"ref": { "$ref": "#/$defs/asset_ref" }
}
}
Output:
{
"type": "object",
"additionalProperties": false,
"required": ["ref", "meaning", "data_type", "classification", "pii", "masking"],
"properties": {
"ref": { "$ref": "#/$defs/asset_scope" },
"meaning": { "type": ["string", "null"], "minLength": 1, "maxLength": 4000 },
"data_type": { "anyOf": [{ "$ref": "#/$defs/identifier" }, { "type": "null" }] },
"classification": {
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"required": ["sensitivity", "category", "subcategory"],
"properties": {
"sensitivity": { "type": "string", "enum": ["public", "internal", "confidential", "restricted"] },
"category": { "$ref": "#/$defs/identifier" },
"subcategory": { "anyOf": [{ "$ref": "#/$defs/identifier" }, { "type": "null" }] }
}
},
{ "type": "null" }
]
},
"pii": { "type": "boolean" },
"masking": {
"anyOf": [
{
"type": "object",
"additionalProperties": false,
"required": ["type", "exempt_roles"],
"properties": {
"type": { "$ref": "#/$defs/identifier" },
"exempt_roles": { "type": "array", "items": { "$ref": "#/$defs/identifier" } }
}
},
{ "type": "null" }
]
}
}
}
inspect_governance_rulesDirect link to inspect_governance_rules
Alias inspect-governance-rules.
Input:
{
"type": "object",
"additionalProperties": false,
"required": ["asset"],
"properties": {
"asset": { "$ref": "#/$defs/asset_ref" },
"scenario_key": { "$ref": "#/$defs/scenario_key" }
}
}
Output:
{
"oneOf": [
{
"title": "answered",
"type": "object",
"additionalProperties": false,
"required": ["state", "asset", "scenario_key", "rules", "publication"],
"properties": {
"state": { "const": "answered" },
"asset": { "$ref": "#/$defs/asset_scope" },
"scenario_key": { "anyOf": [{ "$ref": "#/$defs/scenario_key" }, { "type": "null" }] },
"rules": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/instruction_record" } },
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "review_required",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "asset", "scenario_key", "rules", "conflict", "next_actions", "publication"],
"properties": {
"state": { "const": "review_required" },
"reason_code": { "$ref": "#/$defs/review_reason_code" },
"asset": { "$ref": "#/$defs/asset_scope" },
"scenario_key": { "anyOf": [{ "$ref": "#/$defs/scenario_key" }, { "type": "null" }] },
"rules": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/instruction_record" } },
"conflict": { "anyOf": [{ "$ref": "#/$defs/conflict_group" }, { "type": "null" }] },
"next_actions": { "$ref": "#/$defs/next_actions" },
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "not_enough_published_state",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "message", "unresolved_targets", "next_actions", "asset", "scenario_key"],
"properties": {
"state": { "const": "not_enough_published_state" },
"reason_code": { "$ref": "#/$defs/not_enough_reason_code" },
"message": { "type": "string", "minLength": 1, "maxLength": 300 },
"unresolved_targets": { "type": "array", "items": { "$ref": "#/$defs/unresolved_target" } },
"next_actions": { "$ref": "#/$defs/next_actions" },
"asset": { "$ref": "#/$defs/asset_scope" },
"scenario_key": { "anyOf": [{ "$ref": "#/$defs/scenario_key" }, { "type": "null" }] }
}
}
]
}
authorize_useDirect link to authorize_use
Alias authorize-use. destination requires at least one of system or jurisdiction when present.
Input:
{
"type": "object",
"additionalProperties": false,
"required": ["asset", "use"],
"properties": {
"asset": { "$ref": "#/$defs/asset_ref" },
"scenario_key": { "$ref": "#/$defs/scenario_key" },
"use": { "type": "string", "minLength": 1, "maxLength": 2000 },
"operation": { "$ref": "#/$defs/transfer_token" },
"destination": {
"type": "object",
"additionalProperties": false,
"anyOf": [{ "required": ["system"] }, { "required": ["jurisdiction"] }],
"properties": {
"system": { "$ref": "#/$defs/transfer_token" },
"jurisdiction": { "$ref": "#/$defs/transfer_token" }
}
},
"consumer_jurisdiction": { "$ref": "#/$defs/transfer_token" }
}
}
Output:
{
"oneOf": [
{
"title": "answered",
"type": "object",
"additionalProperties": false,
"required": [
"state", "advisory", "decision", "decision_id", "reason", "scenario_key",
"scenario_lane", "asset", "instructions", "context_facts", "obligations",
"conditions", "prohibitions", "next_actions", "can_proceed_now", "publication"
],
"properties": {
"state": { "const": "answered" },
"advisory": { "const": true },
"decision": { "$ref": "#/$defs/instruction_decision" },
"decision_id": { "$ref": "#/$defs/uuid" },
"reason": { "type": "string", "minLength": 1, "maxLength": 2000 },
"scenario_key": { "$ref": "#/$defs/scenario_key" },
"scenario_lane": { "$ref": "#/$defs/scenario_lane" },
"asset": { "$ref": "#/$defs/asset_scope" },
"instructions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/instruction_record" } },
"context_facts": { "anyOf": [{ "$ref": "#/$defs/context_facts" }, { "type": "null" }] },
"obligations": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["type", "target", "method", "required_by_policy"],
"properties": {
"type": { "type": "string", "enum": ["mask", "retain"] },
"target": { "type": "string", "minLength": 1, "maxLength": 512 },
"method": { "type": ["string", "null"], "minLength": 1, "maxLength": 128 },
"required_by_policy": { "type": "string", "minLength": 1, "maxLength": 64 }
}
}
},
"conditions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "required_role", "requirement", "satisfied_by", "required_by_policy"],
"properties": {
"kind": { "type": "string", "enum": ["approval_required", "anonymize_first", "role_restricted", "ai_restriction"] },
"required_role": { "type": ["string", "null"], "minLength": 1, "maxLength": 255 },
"requirement": { "type": "string", "minLength": 1, "maxLength": 512 },
"satisfied_by": { "type": ["string", "null"], "minLength": 1, "maxLength": 512 },
"required_by_policy": { "type": "string", "minLength": 1, "maxLength": 64 }
}
}
},
"prohibitions": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": ["source", "detail", "required_by_policy"],
"properties": {
"source": { "type": "string", "enum": ["deny_decision", "prohibited_use", "ai_governance"] },
"detail": { "type": "string", "minLength": 1, "maxLength": 512 },
"required_by_policy": { "type": "string", "minLength": 1, "maxLength": 64 }
}
}
},
"next_actions": { "$ref": "#/$defs/next_actions" },
"can_proceed_now": { "type": "boolean" },
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "review_required",
"type": "object",
"additionalProperties": false,
"required": [
"state", "advisory", "reason_code", "decision", "reason", "scenario_key",
"scenario_lane", "asset", "instructions", "conflict", "context_facts",
"next_actions", "can_proceed_now", "publication"
],
"properties": {
"state": { "const": "review_required" },
"advisory": { "const": true },
"reason_code": { "$ref": "#/$defs/review_reason_code" },
"decision": { "const": "require_review" },
"reason": { "type": "string", "minLength": 1, "maxLength": 2000 },
"scenario_key": { "$ref": "#/$defs/scenario_key" },
"scenario_lane": { "$ref": "#/$defs/scenario_lane" },
"asset": { "$ref": "#/$defs/asset_scope" },
"instructions": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/instruction_record" } },
"conflict": { "anyOf": [{ "$ref": "#/$defs/conflict_group" }, { "type": "null" }] },
"context_facts": { "anyOf": [{ "$ref": "#/$defs/context_facts" }, { "type": "null" }] },
"next_actions": { "$ref": "#/$defs/next_actions" },
"can_proceed_now": { "const": false },
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "not_enough_published_state",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "message", "unresolved_targets", "next_actions", "advisory", "asset", "scenario_key"],
"properties": {
"state": { "const": "not_enough_published_state" },
"reason_code": { "$ref": "#/$defs/not_enough_reason_code" },
"message": { "type": "string", "minLength": 1, "maxLength": 300 },
"unresolved_targets": { "type": "array", "items": { "$ref": "#/$defs/unresolved_target" } },
"next_actions": { "$ref": "#/$defs/next_actions" },
"advisory": { "const": true },
"asset": { "$ref": "#/$defs/asset_scope" },
"scenario_key": { "anyOf": [{ "$ref": "#/$defs/scenario_key" }, { "type": "null" }] }
}
}
]
}
validate_query_contextDirect link to validate_query_context
Alias validate-query-context. SQL parse and identifier-resolution failures are typed errors (query_parse_failed, query_unresolved_identifier), not answer states.
Input:
{
"type": "object",
"additionalProperties": false,
"required": ["sql"],
"properties": {
"sql": { "type": "string", "minLength": 1, "maxLength": 100000 },
"default_database": { "$ref": "#/$defs/identifier" },
"default_schema": { "$ref": "#/$defs/identifier" },
"scenario_key": { "$ref": "#/$defs/scenario_key" },
"use": { "type": "string", "minLength": 1, "maxLength": 2000 },
"operation": { "$ref": "#/$defs/transfer_token" },
"destination": {
"type": "object",
"additionalProperties": false,
"anyOf": [{ "required": ["system"] }, { "required": ["jurisdiction"] }],
"properties": {
"system": { "$ref": "#/$defs/transfer_token" },
"jurisdiction": { "$ref": "#/$defs/transfer_token" }
}
},
"consumer_jurisdiction": { "$ref": "#/$defs/transfer_token" }
}
}
Output (the finding object is shown inline in the answered variant and referenced by name in review_required):
{
"$defs": {
"finding": {
"type": "object",
"additionalProperties": false,
"required": ["ref", "status", "reason_code", "decision", "decision_reason", "instructions", "conflict"],
"properties": {
"ref": { "$ref": "#/$defs/asset_scope" },
"status": { "type": "string", "enum": ["evaluated", "not_enough_published_state"] },
"reason_code": { "anyOf": [{ "$ref": "#/$defs/not_enough_reason_code" }, { "type": "null" }] },
"decision": { "anyOf": [{ "$ref": "#/$defs/instruction_decision" }, { "type": "null" }] },
"decision_reason": { "type": ["string", "null"], "minLength": 1, "maxLength": 2000 },
"instructions": { "type": "array", "items": { "$ref": "#/$defs/instruction_record" } },
"conflict": { "anyOf": [{ "$ref": "#/$defs/conflict_group" }, { "type": "null" }] }
}
}
},
"oneOf": [
{
"title": "answered",
"type": "object",
"additionalProperties": false,
"required": ["state", "advisory", "verdict", "findings", "publication"],
"properties": {
"state": { "const": "answered" },
"advisory": { "const": true },
"verdict": { "type": "string", "enum": ["pass", "warn", "fail"] },
"findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
"publication": { "anyOf": [{ "$ref": "#/$defs/publication" }, { "type": "null" }] }
}
},
{
"title": "review_required",
"type": "object",
"additionalProperties": false,
"required": ["state", "advisory", "reason_code", "verdict", "findings", "next_actions", "publication"],
"properties": {
"state": { "const": "review_required" },
"advisory": { "const": true },
"reason_code": { "$ref": "#/$defs/review_reason_code" },
"verdict": { "type": "string", "enum": ["pass", "warn", "fail"] },
"findings": { "type": "array", "items": { "$ref": "#/$defs/finding" } },
"next_actions": { "$ref": "#/$defs/next_actions" },
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "not_enough_published_state",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "message", "unresolved_targets", "next_actions", "advisory"],
"properties": {
"state": { "const": "not_enough_published_state" },
"reason_code": { "$ref": "#/$defs/not_enough_reason_code" },
"message": { "type": "string", "minLength": 1, "maxLength": 300 },
"unresolved_targets": { "type": "array", "items": { "$ref": "#/$defs/unresolved_target" } },
"next_actions": { "$ref": "#/$defs/next_actions" },
"advisory": { "const": true }
}
}
]
}
explain_whyDirect link to explain_why
Alias explain-why. The input is discriminated on kind; kind: "validation" is accepted by the schema but answers with a not_supported error. There is no not_enough_published_state variant — an unresolvable decision_id is an asset_not_found error.
Input:
{
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": ["kind", "decision_id"],
"properties": {
"kind": { "const": "decision" },
"decision_id": { "$ref": "#/$defs/uuid" }
}
},
{
"type": "object",
"additionalProperties": false,
"required": ["kind", "validation_id"],
"properties": {
"kind": { "const": "validation" },
"validation_id": { "$ref": "#/$defs/uuid" }
}
}
]
}
Output:
{
"oneOf": [
{
"title": "answered",
"type": "object",
"additionalProperties": false,
"required": ["state", "explanation", "record", "current", "publication"],
"properties": {
"state": { "const": "answered" },
"explanation": { "type": "string", "minLength": 1, "maxLength": 4000 },
"record": { "$ref": "#/$defs/instruction_record" },
"current": { "type": "boolean" },
"publication": { "$ref": "#/$defs/publication" }
}
},
{
"title": "review_required",
"type": "object",
"additionalProperties": false,
"required": ["state", "reason_code", "explanation", "record", "current", "publication"],
"properties": {
"state": { "const": "review_required" },
"reason_code": { "$ref": "#/$defs/review_reason_code" },
"explanation": { "type": "string", "minLength": 1, "maxLength": 4000 },
"record": { "$ref": "#/$defs/instruction_record" },
"current": { "type": "boolean" },
"publication": { "$ref": "#/$defs/publication" }
}
}
]
}