Jira progress: loading…

Ask ZARA-VQ

Ask ZARA Verifier Query API

1. Purpose

The Ask ZARA Verifier Query API enables approved auditors, verifiers, and assurance partners to use Ask ZARA for controlled, evidence-bound deep dives into a client's ESG data.

This API is not a general chatbot interface over client data. It is a governed assurance interface that allows verifiers to:

explain reported ESG signals;
trace values back to evidence, artifacts, calculations, and source systems;
review AI-inferred or extrapolated data;
inspect trust scores and validation results;
raise verifier flags;
run non-persistent sandbox simulations;
create a complete ALTD audit trail for every verifier interaction.

The API belongs to the core_zara schema and references data from core_signals, core_zar, core_engine, and core_telemetry.

2. Architectural Principle

Ask ZARA Verifier Mode follows this rule:

Ask ZARA may explain, trace, compare, and simulate.
Ask ZARA must not generate, mutate, approve, or submit client disclosure data on behalf of a verifier.

architectural-principle.yamlGitHub ↗
allowed_actions:
  - explain
  - trace
  - compare
  - review
  - flag
  - sandbox_simulate

blocked_actions:
  - generate_missing_data
  - overwrite_signals
  - auto_complete_forms
  - submit_disclosures
  - approve_ai_generated_data

3. Schema Placement

Object Type	Schema
Ask ZARA verifier queries	`core_zara`
Ask ZARA verifier responses	`core_zara`
Ask ZARA verifier flags	`core_zara`
Ask ZARA sandbox simulations	`core_zara`
Signal definitions	`core_signals`
Artifact and evidence lineage	`core_zar`
Engine computation outputs	`core_engine`
Audit and telemetry events	`core_telemetry`
Static prompt/config registries	`core_metadata`

Ask ZARA should reference source-of-truth records in other schemas, not duplicate them.

4. Main Endpoint

main-endpoint.httpGitHub ↗
POST /api/v1/verifier/zara/query
Authorization: Bearer <access_token>
X-ZAYAZ-Client-ECO: ECO-196-123-456-789
X-ZAYAZ-Verifier-ECO: VER-196-456-789
Idempotency-Key: <uuid>
Content-Type: application/json

4.1 Request Body

main-endpoint.jsonGitHub ↗
{
  "query_id": "vq_01HVZ8K9P4X7",
  "client_eco_id": "ECO-196-123-456-789",
  "verifier_eco_id": "VER-196-456-789",
  "engagement_id": "eng_2025_csrd_assurance_001",
  "query_type": "signal_explain",
  "natural_language_query": "Explain the Scope 3 Category 4 emissions value and show all supporting evidence.",
  "scope": {
    "reporting_year": 2025,
    "frameworks": ["CSRD", "ESRS"],
    "disclosure_refs": ["E1-6"],
    "signal_ids": ["ghg_scope3_cat4_emissions"],
    "entity_scope": {
      "legal_entity_ids": ["le_001"],
      "site_ids": ["site_oslo_001"],
      "value_chain_scope": ["upstream"]
    }
  },
  "evidence_mode": true,
  "requested_views": [
    "source_data",
    "calculation_path",
    "validation_results",
    "trust_scores",
    "ai_inference_tags",
    "provenance_lineage",
    "xbrl_mapping",
    "change_history",
    "verifier_flags"
  ],
  "constraints": {
    "allow_generation": false,
    "allow_data_mutation": false,
    "allow_task_dispatch": false,
    "allow_sandbox_simulation": true,
    "max_result_rows": 500,
    "redaction_level": "engagement_scope"
  },
  "output": {
    "format": "structured_json",
    "language": "en",
    "include_citations": true,
    "include_confidence": true,
    "include_machine_readable_evidence_bundle": true
  }
}

5. Query Types

query-types.tsGitHub ↗
type VerifierQueryType =
  | "signal_explain"
  | "evidence_trace"
  | "calculation_replay"
  | "trust_score_review"
  | "ai_inference_review"
  | "xbrl_mapping_review"
  | "gap_analysis"
  | "anomaly_detection"
  | "benchmark_compare"
  | "policy_evidence_review"
  | "sandbox_simulation";

Query Type	Purpose
`signal_explain`	Explain a reported signal, including source, method, trust score, and limitations.
`evidence_trace`	Trace signals back to artifacts, source systems, uploads, APIs, or manual entries.
`calculation_replay`	Reconstruct how a value was calculated using registered formulas, MICE engines, and inputs.
`trust_score_review`	Explain DICE, DaVE, VTE, and other trust-related outputs.
`ai_inference_review`	Identify where AI, SEM, extrapolation, or default assumptions were used.
`xbrl_mapping_review`	Show how a ZAYAZ signal maps to ESRS/XBRL/iXBRL concepts.
`gap_analysis`	Identify missing, incomplete, weakly evidenced, or low-trust signals.
`anomaly_detection`	Highlight outliers, sudden changes, inconsistent values, or benchmark deviations.
`benchmark_compare`	Compare values against NACE, sector, country, or peer benchmarks.
`policy_evidence_review`	Review policies, procedures, supporting documents, and governance evidence.
`sandbox_simulation`	Run a non-persistent what-if calculation without changing client records.

6. Response Schema

response-schema.jsonGitHub ↗
{
  "query_id": "vq_01HVZ8K9P4X7",
  "status": "completed",
  "mode": "verifier_read_only",
  "answer": {
    "summary": "Scope 3 Category 4 emissions were calculated from supplier logistics activity data, distance estimates, transport mode factors, and approved emission factors.",
    "assurance_relevance": "Material because the signal contributes 18.4% of total reported Scope 3 emissions.",
    "limitations": [
      "Two supplier transport records were estimated using SEM.",
      "One emission factor was inherited from default regional assumptions."
    ]
  },
  "signals": [
    {
      "signal_id": "ghg_scope3_cat4_emissions",
      "display_name": "Scope 3 Category 4 - Upstream Transportation and Distribution",
      "reported_value": 12840.55,
      "unit": "kgCO2e",
      "period": "2025",
      "framework_refs": ["ESRS E1-6"],
      "xbrl_concept_id": "esrs:E1-6_Scope3Category4Emissions"
    }
  ],
  "evidence_bundle": {
    "bundle_id": "evb_01HVZ9E21A",
    "evidence_items": [
      {
        "evidence_id": "ev_001",
        "source_type": "supplier_invoice",
        "source_system": "ERP_API",
        "artifact_id": "zar_artifact_789",
        "hash": "sha256:...",
        "timestamp": "2026-04-28T10:42:00Z",
        "access_level": "verifier_visible"
      }
    ]
  },
  "calculation_path": {
    "engine": "MICE",
    "engine_id": "MEID_CALC02_v1",
    "formula_ref": "ghg_scope3_transport_v1",
    "steps": [
      {
        "step": 1,
        "operation": "distance_activity_factor",
        "input_refs": ["ev_001", "ev_002"],
        "output": 12840.55,
        "unit": "kgCO2e"
      }
    ]
  },
  "trust": {
    "overall_trust_score": 0.91,
    "data_validation_score": 0.94,
    "source_reliability_score": 0.89,
    "ai_inference_share": 0.12,
    "verifier_previous_approval": false,
    "trust_flags": [
      {
        "severity": "medium",
        "code": "AI_ESTIMATION_PRESENT",
        "message": "12% of the value depends on AI-assisted estimation."
      }
    ]
  },
  "ai_governance": {
    "ai_used": true,
    "ai_role": "explanation_only",
    "model_outputs_mutated_client_data": false,
    "human_review_required": true,
    "confidence": 0.88
  },
  "audit": {
    "altd_event_id": "altd_01HVZ9K222",
    "logged_at": "2026-04-28T10:45:00Z",
    "logged_actions": [
      "verifier_query_received",
      "rbac_checked",
      "evidence_resolved",
      "zara_response_generated",
      "response_returned"
    ]
  }
}

7. Verifier Permission Contract

verifier-permission-contract.jsonGitHub ↗
{
  "role": "verifier",
  "mode": "zara_verifier_mode",
  "permissions": {
    "read_client_data": true,
    "read_evidence": true,
    "read_provenance": true,
    "read_ai_tags": true,
    "read_trust_scores": true,
    "generate_missing_data": false,
    "edit_client_data": false,
    "submit_disclosure": false,
    "approve_own_generated_data": false,
    "create_verifier_flag": true,
    "request_clarification": true,
    "run_sandbox_simulation": true
  }
}

8. Verifier Flag Endpoint

verifier-flag.httpGitHub ↗
POST /api/v1/verifier/zara/flags
Authorization: Bearer <access_token>
Content-Type: application/json

verifier-flag.jsonGitHub ↗
{
  "client_eco_id": "ECO-196-123-456-789",
  "verifier_eco_id": "VER-196-456-789",
  "engagement_id": "eng_2025_csrd_assurance_001",
  "target": {
    "target_type": "signal",
    "signal_id": "ghg_scope3_cat4_emissions",
    "evidence_id": "ev_001"
  },
  "flag": {
    "severity": "medium",
    "category": "insufficient_evidence",
    "message": "Supplier invoice does not clearly identify transport mode.",
    "requested_action": "client_clarification",
    "due_date": "2026-05-12"
  }
}

Response:

verifier-flag-response.jsonGitHub ↗
{
  "flag_id": "vf_01HW01ABC9",
  "status": "open",
  "altd_event_id": "altd_01HW01LOG9"
}

9. Sandbox Simulation Endpoint

sandbox-simulation.httpGitHub ↗
POST /api/v1/verifier/zara/simulate
Authorization: Bearer <access_token>
Content-Type: application/json

sandbox-simulation.jsonGitHub ↗
{
  "simulation_id": "sim_001",
  "client_eco_id": "ECO-196-123-456-789",
  "verifier_eco_id": "VER-196-456-789",
  "engagement_id": "eng_2025_csrd_assurance_001",
  "base_signal_id": "ghg_scope3_cat4_emissions",
  "scenario": {
    "name": "Replace default emission factor with supplier-specific factor",
    "changes": [
      {
        "field": "emission_factor",
        "from": 0.18,
        "to": 0.22,
        "unit": "kgCO2e_tkm"
      }
    ]
  },
  "persistence": "non_persistent",
  "label_output_as": "AI_SIMULATED_NOT_DISCLOSED_DATA"
}

Response:

sandbox-simulation-response.jsonGitHub ↗
{
  "simulation_id": "sim_001",
  "base_value": 12840.55,
  "simulated_value": 15693.98,
  "delta_percent": 22.22,
  "materiality_warning": true,
  "label": "AI_SIMULATED_NOT_DISCLOSED_DATA",
  "altd_event_id": "altd_sim_001"
}

10. ALTD Audit Event Schema

Every verifier query must create an ALTD-compatible audit event.

altd-audit-event-schema.jsonGitHub ↗
{
  "event_type": "zara_verifier_query",
  "event_id": "altd_01HVZ9K222",
  "timestamp": "2026-04-28T10:45:00Z",
  "actor": {
    "user_id": "usr-ver196456789-0000001",
    "verifier_eco_id": "VER-196-456-789",
    "role": "verifier"
  },
  "target": {
    "client_eco_id": "ECO-196-123-456-789",
    "engagement_id": "eng_2025_csrd_assurance_001",
    "signal_ids": ["ghg_scope3_cat4_emissions"]
  },
  "ai_context": {
    "zara_mode": "verifier_read_only",
    "query_type": "signal_explain",
    "ai_used": true,
    "model_version": "zara-verifier-v1",
    "confidence": 0.88,
    "data_mutation": false
  },
  "security": {
    "rbac_decision": "allow",
    "policy_version": "zara_verifier_policy_v1",
    "redaction_level": "engagement_scope"
  }
}

11.

minimal-database-tables.sqlGitHub ↗
CREATE SCHEMA IF NOT EXISTS core_zara;

CREATE TABLE core_zara.zara_verifier_queries (
  query_id TEXT PRIMARY KEY,
  client_eco_id TEXT NOT NULL,
  verifier_eco_id TEXT NOT NULL,
  engagement_id TEXT NOT NULL,
  query_type TEXT NOT NULL,
  natural_language_query TEXT,
  structured_scope JSONB NOT NULL,
  requested_views JSONB NOT NULL,
  status TEXT NOT NULL DEFAULT 'received',
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE core_zara.zara_verifier_responses (
  response_id TEXT PRIMARY KEY,
  query_id TEXT NOT NULL REFERENCES core_zara.zara_verifier_queries(query_id),
  response_payload JSONB NOT NULL,
  confidence NUMERIC CHECK (confidence IS NULL OR confidence BETWEEN 0 AND 1),
  evidence_bundle_id TEXT,
  altd_event_id TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE TABLE core_zara.zara_verifier_flags (
  flag_id TEXT PRIMARY KEY,
  client_eco_id TEXT NOT NULL,
  verifier_eco_id TEXT NOT NULL,
  engagement_id TEXT NOT NULL,
  target_type TEXT NOT NULL,
  target_id TEXT NOT NULL,
  severity TEXT NOT NULL,
  category TEXT NOT NULL,
  message TEXT NOT NULL,
  status TEXT NOT NULL DEFAULT 'open',
  altd_event_id TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);

12. Recommended Hardening Additions

hardening-additions.sqlGitHub ↗
ALTER TABLE core_zara.zara_verifier_queries
ADD COLUMN IF NOT EXISTS idempotency_key TEXT,
ADD COLUMN IF NOT EXISTS created_by_user_id TEXT,
ADD COLUMN IF NOT EXISTS zara_mode TEXT NOT NULL DEFAULT 'verifier_read_only',
ADD COLUMN IF NOT EXISTS policy_version TEXT,
ADD COLUMN IF NOT EXISTS redaction_level TEXT DEFAULT 'engagement_scope',
ADD COLUMN IF NOT EXISTS completed_at TIMESTAMPTZ,
ADD COLUMN IF NOT EXISTS failed_at TIMESTAMPTZ,
ADD COLUMN IF NOT EXISTS error_code TEXT,
ADD COLUMN IF NOT EXISTS error_message TEXT;

ALTER TABLE core_zara.zara_verifier_responses
ADD COLUMN IF NOT EXISTS model_version TEXT,
ADD COLUMN IF NOT EXISTS prompt_template_id TEXT,
ADD COLUMN IF NOT EXISTS ai_used BOOLEAN NOT NULL DEFAULT true,
ADD COLUMN IF NOT EXISTS data_mutation BOOLEAN NOT NULL DEFAULT false,
ADD COLUMN IF NOT EXISTS human_review_required BOOLEAN NOT NULL DEFAULT true,
ADD COLUMN IF NOT EXISTS response_hash TEXT;

ALTER TABLE core_zara.zara_verifier_flags
ADD COLUMN IF NOT EXISTS requested_action TEXT,
ADD COLUMN IF NOT EXISTS due_date DATE,
ADD COLUMN IF NOT EXISTS assigned_to_user_id TEXT,
ADD COLUMN IF NOT EXISTS resolved_at TIMESTAMPTZ,
ADD COLUMN IF NOT EXISTS resolution_note TEXT;

13. Recommended Indexes

indexes.sqlGitHub ↗
CREATE INDEX IF NOT EXISTS idx_zara_vq_client_engagement
ON core_zara.zara_verifier_queries (client_eco_id, engagement_id);

CREATE INDEX IF NOT EXISTS idx_zara_vq_verifier
ON core_zara.zara_verifier_queries (verifier_eco_id);

CREATE INDEX IF NOT EXISTS idx_zara_vq_status
ON core_zara.zara_verifier_queries (status);

CREATE INDEX IF NOT EXISTS idx_zara_vr_query
ON core_zara.zara_verifier_responses (query_id);

CREATE INDEX IF NOT EXISTS idx_zara_vf_client_engagement
ON core_zara.zara_verifier_flags (client_eco_id, engagement_id);

CREATE INDEX IF NOT EXISTS idx_zara_vf_target
ON core_zara.zara_verifier_flags (target_type, target_id);

CREATE INDEX IF NOT EXISTS idx_zara_vf_status
ON core_zara.zara_verifier_flags (status);

14. Status Enums

status-enums.tsGitHub ↗
type ZaraVerifierQueryStatus =
  | "received"
  | "rbac_checking"
  | "resolving_context"
  | "resolving_evidence"
  | "generating_response"
  | "completed"
  | "failed"
  | "denied"
  | "expired";

type ZaraVerifierFlagStatus =
  | "open"
  | "client_response_requested"
  | "in_review"
  | "resolved"
  | "rejected"
  | "withdrawn";

type ZaraVerifierFlagSeverity =
  | "low"
  | "medium"
  | "high"
  | "critical";

15. Security Rules

A verifier may query client data only if:

the verifier has a valid VER-* E-C-O identifier;
the verifier is approved for the relevant assurance category;
an active engagement exists between the verifier and client;
the engagement scope includes the requested entity, reporting period, framework, and signal;
the verifier role has permission to access the requested evidence class;
the query is logged before response generation.

The API must deny requests where:

client_eco_id in the body does not match X-ZAYAZ-Client-ECO;
verifier_eco_id in the body does not match X-ZAYAZ-Verifier-ECO;
allow_data_mutation is true;
allow_generation is true;
requested signals fall outside the engagement scope;
requested evidence is confidential beyond verifier access level;
ALTD logging fails.

16. Example Verifier Queries

16.1 Identify AI-Inferred Signals

identify-ai-inferred-signals.jsonGitHub ↗
{
  "query_id": "vq_ai_review_001",
  "client_eco_id": "ECO-196-123-456-789",
  "verifier_eco_id": "VER-196-456-789",
  "engagement_id": "eng_2025_csrd_assurance_001",
  "query_type": "ai_inference_review",
  "natural_language_query": "List all AI-inferred signals above 10% contribution to Scope 3.",
  "scope": {
    "reporting_year": 2025,
    "frameworks": ["CSRD", "ESRS"],
    "disclosure_refs": ["E1-6"]
  },
  "evidence_mode": true,
  "requested_views": ["ai_inference_tags", "trust_scores", "calculation_path"],
  "constraints": {
    "allow_generation": false,
    "allow_data_mutation": false,
    "max_result_rows": 100,
    "redaction_level": "engagement_scope"
  },
  "output": {
    "format": "structured_json",
    "include_confidence": true
  }
}

16.2 Trace Metric to XBRL

trace-metric-to-xbrl.jsonGitHub ↗
{
  "query_id": "vq_xbrl_trace_001",
  "client_eco_id": "ECO-196-123-456-789",
  "verifier_eco_id": "VER-196-456-789",
  "engagement_id": "eng_2025_csrd_assurance_001",
  "query_type": "xbrl_mapping_review",
  "natural_language_query": "Trace this reported value from source data to XBRL tag.",
  "scope": {
    "reporting_year": 2025,
    "frameworks": ["CSRD", "ESRS"],
    "signal_ids": ["ghg_scope1_total_emissions"]
  },
  "evidence_mode": true,
  "requested_views": ["source_data", "calculation_path", "xbrl_mapping", "provenance_lineage"],
  "constraints": {
    "allow_generation": false,
    "allow_data_mutation": false,
    "max_result_rows": 250,
    "redaction_level": "engagement_scope"
  },
  "output": {
    "format": "structured_json",
    "include_citations": true,
    "include_confidence": true
  }
}

17. Implementation Notes

The API service must:

authenticate the verifier;
validate the engagement scope;
resolve requested signals through SSSR;
resolve evidence through ZAR;
resolve calculation outputs through MICE/core_engine;
resolve trust outputs through DICE, DaVE, and VTE;
call ZARA in verifier read-only mode;
persist the query and response in core_zara;
emit ALTD audit events;
return structured JSON.

ZARA responses are explanatory outputs. The source of truth remains:

core_signals for signal definitions;
core_zar for artifacts and provenance;
core_engine for computation outputs;
core_metadata for reference methods;
core_telemetry for audit and event history.

18. Final Design Decision

ZARA Verifier Mode is an evidence-bound assurance API, not a generic chatbot API.

The natural-language layer is only the interface. The backend must always resolve user prompts into:

query_type
scope
requested_views
evidence_bundle
trust_context
response_payload
ALTD audit event

This design protects verifier independence, preserves auditability, prevents unauthorized data mutation, and gives ZAYAZ a scalable foundation for AI-native ESG assurance.

GitHub Repo Request for Change (RFC)

1. Purpose​

2. Architectural Principle​

3. Schema Placement​

4. Main Endpoint​

4.1 Request Body​

5. Query Types​

6. Response Schema​

7. Verifier Permission Contract​

8. Verifier Flag Endpoint​

9. Sandbox Simulation Endpoint​

10. ALTD Audit Event Schema​

11.​

12. Recommended Hardening Additions​

13. Recommended Indexes​

14. Status Enums​

15. Security Rules​

16. Example Verifier Queries​

16.1 Identify AI-Inferred Signals​

16.2 Trace Metric to XBRL​

17. Implementation Notes​

18. Final Design Decision​