Skip to main content
Jira progress: loading…

AIIL-CON

API Contracts

1. API Contracts​

1.1. Purpose​

The API layer is the contractual glue that ties together:

  • The GDO (Global Disclosure Ontology) for standards resolution.
  • The ZADIF dispatcher for routing queries across agents.
  • The Computation Hub for numeric governance.
  • The Go/No-Go engine for lifecycle enforcement.

APIs must be:

  • Deterministic → predictable schemas, no hidden behavior.
  • uditable → every call logged with provenance IDs.
  • Composable → extensible to new frameworks without code rewrites.

1.2. Core Endpoints​

EndpointPurposeExample PayloadNotes
/gdo/resolveResolve disclosure requirement →GDO node{"query": "ESRS E1-5 GHG disclosure"} Returns node ID, metadata, citations.
/gdo/compareCrosswalk disclosures between frameworks{"source":"ESRS.E1", "target":"ISSB.S2"} Returns mapping confidence + overlap score.
/zadif/dispatchDispatch query to correct agent (RAG, Compute, Validator){"query":"What is Scope 2 intensity?", "mode":"auto"}Uses routing policy from ZADIF.
/compute/factorCall Computation Hub for numeric calc{"method":"GHG.intensity", "inputs":{"scope1":100, "scope2":200,"revenue":50}}Returns validated number + dataset provenance.
/eval/gateLifecycle gating check{"response_id":"abc123", "tests":["citation","refusal","numeric"]} Returns pass/fail per test.

1.3. Example: GDO API Contract​

Request (POST /gdo/resolve):

gdo-api-contract.jsonGitHub ↗
{
  "query": "List disclosure requirements for ESRS E1",
  "options": {
    "jurisdiction": "EU",
    "materiality": "environmental"
  }
}

Response:

gdo-api-contract-response.jsonGitHub ↗
{
  "status": "ok",
  "nodes": [
    {
      "id": "ESRS.E1.5",
      "title": "GHG Emissions – Scope 1-3",
      "doc_ref": "Amended_ESRS_E1.pdf:L50-L85",
      "jurisdiction": "EU",
      "effective_date": "2025-01-01"
    }
  ],
  "provenance_id": "px-23d9d"
}

1.4. ZADIF Dispatcher (Routing Contract)​

The ZADIF dispatcher routes user queries to the correct AI agent.

Routing Logic:

  • Standards Query → RAG agent.
  • Numeric Query → Computation Hub agent.
  • Validation/Check → Eval agent.
  • Multi-step → Composed pipeline.

Request (POST /zadif/dispatch):

routing-contract.jsonGitHub ↗
{
  "query": "What is Scope 2 intensity per revenue?",
  "context": "ESRS E1",
  "mode": "auto"
}

Response:

routing-contract-response.jsonGitHub ↗
{
  "route": "compute",
  "agent": "ComputationHub.GHG",
  "inputs": {
    "scope2": "from_context",
    "revenue": "from_context"
  },
  "provenance_id": "zadif-7f2e"
}

1.5. Computation Hub API Contract​

Request (POST /compute/factor):

computation-api-contract.jsonGitHub ↗
{
  "method": "GHG.intensity",
  "inputs": {
    "scope1": 100,
    "scope2": 200,
    "revenue": 50
  },
  "dataset_ref": "IPCC-EFDB.xlsx"
}

Response:

computation-api-contract-response.jsonGitHub ↗
{
  "status": "ok",
  "result": 6.0,
  "unit": "tCO2e/€m",
  "provenance": {
    "dataset": "IPCC-EFDB.xlsx",
    "method": "EFDB Tier 1",
    "hash": "sha256-98ad..."
  }
}

Response (Updated / Live code):

computation-api-contract-response.jsonGitHub ↗
{
  "status": "ok",
  "result": 6.0,
  "unit": "tCO2e/€m",
  "provenance": {
    "dataset": "IPCC-EFDB.xlsx",
    "method": "EFDB Tier 1",
    "hash": "sha256-98ad..."
  }
}

Explanation:

The /compute/factor request is asking the Computation Hub to calculate a numeric KPI (here: GHG intensity = total GHG emissions ÷ revenue).

  • method → tells the hub what computation to run. Here "GHG.intensity" = GHG emissions per € revenue.
  • inputs → the raw values needed to perform that calculation. In the example:
    • "scope1": 100 → 100 tCO₂e direct emissions (from company data).
    • "scope2": 200 → 200 tCO₂e indirect energy emissions.
    • "revenue": 50 → 50 €m company revenue.
  • dataset_ref → which dataset / emission factor library should be used to validate or contextualize. Here, "IPCC-EFDB.xlsx" means the EFDB emission factor reference is applied.

GHG intensity=scope1+scope2revenue=100+20050=6.0  tCO₂e / €m\text{GHG intensity} = \frac{\text{scope1} + \text{scope2}}{\text{revenue}} = \frac{100 + 200}{50} = 6.0 \; \text{tCO₂e / €m}

The data is just illustrative inputs, not defaults. In real life:

  • Scope 1 & 2 values would come from disclosures or extracted supplier/company reports.
  • Revenue would come from the financial dataset integrated in ZAYAZ.
  • The dataset_ref (IPCC-EFDB.xlsx) ensures the computation is aligned with the right factor library and auditable.

Contracted Functions

The Computation Hub exposes methods as contracted functions. Each method is versioned and auditable.

Supported methods examples

MethodDescriptionInputsOutputNotes
GHG.intensityGHG emissions per € revenue (Scope 1, 2, or 3)scope1, scope2, scope3_catX, revenuetCO₂e/€mCategory-specific optional inputs (Cat1, Cat4, etc.).
GHG.absAbsolute GHG emissions (summed across scopes)scope1, scope2, scope3_catXtCO₂eAligns with ESRS E1 and GHG Protocol.
Energy.intensityEnergy consumption per € revenueenergy_total, revenueMWh/€mEnergy includes fuel + purchased electricity.
Energy.absAbsolute energy consumptionenergy_totalMWhValidated via GDO mappings.
Water.intensityWater use per € revenuewater_withdrawal, revenuem³/€mUses ESRS E3 categories (withdrawal, consumption).
Water.absAbsolute water withdrawal/consumptionwater_withdrawal, water_consumptionm³Split by category (surface, groundwater, etc.).
Waste.intensityWaste generated per € revenuewaste_total, revenuetonnes/€mMaps to ESRS E5 disclosures.
Waste.absAbsolute waste generatedwaste_totaltonnesSupports hazardous/non-hazardous split.
GHG.target_gapDistance-to-target emissions gapcurrent_emissions, target_emissions% gapUsed for scenario pathways.
GHG.scenario_alignAlignment with 1.5°C / 2°C scenariosemissions, scenario_curve_ref% alignmentRequires scenario dataset (e.g., IEA, IPCC SSPs).

Example Call: Scenario Alignment

Request (POST /compute/factor):

scenario-alignment.jsonGitHub ↗
{
  "method": "GHG.scenario_align",
  "inputs": {
    "emissions": [2025, 12500, 2026, 12000, 2027, 11000],
    "scenario_curve_ref": "IPCC_SSP1_1.9"
  },
  "options": {
    "jurisdiction": "EU",
    "sector": "Manufacturing"
  }
}

Response:

scenario-alignment-response.jsonGitHub ↗
{
  "status": "ok",
  "result": 0.87,
  "unit": "alignment_score",
  "provenance": {
    "dataset": "IPCC Scenario SSP1-1.9",
    "method": "Scenario alignment check",
    "hash": "sha256-45c1..."
  }
}

Interpretation: The company’s emissions trajectory aligns with the 1.5°C-compatible curve at 87% confidence.

1.5.1. Compute Method Registry — Core v1 (32 methods)​

Column legend (for clarity)

  • inputs_schema_json / options_schema_json / output_schema_json → ZAR Artifact IDs (not inline JSON)
  • implementation_ref → Logical implementation pointer (service / code module)
  • micro_engine_ref → MEID (MICE binding)
  • dataset_requirements → External datasets required (if any)

Note: JSON and JSONB is excluded for an easier viewing experience

GHG (12)

method_idversionstatusmethod_typedescriptioninputs_schema_jsonoptions_schema_jsonoutput_schema_jsonimplementation_refmicro_engine_refdataset_requirementsacl_tags
GHG.abs1.0activeaggregationTotal absolute GHG emissions (Scopes 1+2+3 where available)SCHEMA:COMPUTE:GHG.abs.inputs:v1SCHEMA:COMPUTE:GHG.common.options:v1SCHEMA:COMPUTE:GHG.abs.output:v1comp.ghg.aggregateMEID_CALC_GHG_AGGR_v1IPCC_EFDBenv,csrd
GHG.intensity1.0activeintensityGHG emissions per € revenueSCHEMA:COMPUTE:GHG.intensity.inputs:v1SCHEMA:COMPUTE:GHG.common.options:v1SCHEMA:COMPUTE:GHG.intensity.output:v1comp.ghg.intensityMEID_CALC_GHG_INT_v1IPCC_EFDBenv,csrd
GHG.scope1.abs1.0activeaggregationScope 1 absolute emissionsSCHEMA:COMPUTE:GHG.scope1.inputs:v1SCHEMA:COMPUTE:GHG.common.options:v1SCHEMA:COMPUTE:GHG.scope.output:v1comp.ghg.scope1MEID_CALC_GHG_SCOPE1_v1IPCC_EFDBenv,csrd
GHG.scope2.abs1.0activeaggregationScope 2 emissions (location + market based)SCHEMA:COMPUTE:GHG.scope2.inputs:v1SCHEMA:COMPUTE:GHG.scope2.options:v1SCHEMA:COMPUTE:GHG.scope2.output:v1comp.ghg.scope2MEID_CALC_GHG_SCOPE2_v1IPCC_EFDBenv,csrd
GHG.scope3.abs1.0activeaggregationTotal Scope 3 emissionsSCHEMA:COMPUTE:GHG.scope3.inputs:v1SCHEMA:COMPUTE:GHG.common.options:v1SCHEMA:COMPUTE:GHG.scope.output:v1comp.ghg.scope3MEID_CALC_GHG_SCOPE3_v1IPCC_EFDBenv,csrd
GHG.scope3.cat.abs1.0activeaggregationScope 3 emissions for a single categorySCHEMA:COMPUTE:GHG.scope3.cat.inputs:v1SCHEMA:COMPUTE:GHG.scope3.cat.options:v1SCHEMA:COMPUTE:GHG.scope.output:v1comp.ghg.scope3.catMEID_CALC_GHG_SCOPE3_CAT_v1IPCC_EFDBenv,csrd
GHG.scope3.cat.share1.0activenormalizationShare of Scope 3 category of total Scope 3SCHEMA:COMPUTE:GHG.scope3.share.inputs:v1SCHEMA:COMPUTE:GHG.common.options:v1SCHEMA:COMPUTE:GHG.share.output:v1comp.ghg.scope3.shareMEID_CALC_GHG_SHARE_v1IPCC_EFDBenv
GHG.scope2.market_adjustment1.0activenormalizationDelta between location- and market-based Scope 2SCHEMA:COMPUTE:GHG.scope2.adjust.inputs:v1SCHEMA:COMPUTE:GHG.scope2.options:v1SCHEMA:COMPUTE:GHG.adjust.output:v1comp.ghg.scope2.adjustMEID_CALC_GHG_SCOPE2_ADJ_v1IPCC_EFDBenv
GHG.delta_yoy1.0activedeltaYear-over-year GHG changeSCHEMA:COMPUTE:GHG.delta.inputs:v1SCHEMA:COMPUTE:GHG.delta.options:v1SCHEMA:COMPUTE:GHG.delta.output:v1comp.ghg.deltaMEID_CALC_DELTA_v1noneenv
GHG.target_gap1.0activetarget_gapGap to emissions reduction targetSCHEMA:COMPUTE:GHG.target_gap.inputs:v1SCHEMA:COMPUTE:GHG.target.options:v1SCHEMA:COMPUTE:GHG.target_gap.output:v1comp.ghg.targetMEID_CALC_TARGET_GAP_v1noneenv,board
GHG.budget_remaining1.0activebudgetRemaining carbon budget to target yearSCHEMA:COMPUTE:GHG.budget.inputs:v1SCHEMA:COMPUTE:GHG.target.options:v1SCHEMA:COMPUTE:GHG.budget.output:v1comp.ghg.budgetMEID_CALC_CARBON_BUDGET_v1noneenv,board
GHG.scenario_align1.0activescenarioAlignment with climate scenario pathwaySCHEMA:COMPUTE:GHG.scenario.inputs:v1SCHEMA:COMPUTE:GHG.scenario.options:v1SCHEMA:COMPUTE:GHG.scenario.output:v1comp.ghg.scenarioMEID_SCEN_GHG_ALIGN_v1IPCC_SSP,IEAenv,board

Energy (8)

method_idversionstatusmethod_typedescriptioninputs_schema_jsonoptions_schema_jsonoutput_schema_jsonimplementation_refmicro_engine_refdataset_requirementsacl_tags
Energy.abs1.0activeaggregationTotal energy consumptionSCHEMA:COMPUTE:Energy.abs.inputs:v1SCHEMA:COMPUTE:Energy.common.options:v1SCHEMA:COMPUTE:Energy.abs.output:v1comp.energy.aggregateMEID_CALC_ENERGY_AGGR_v1noneenv
Energy.intensity1.0activeintensityEnergy per € revenueSCHEMA:COMPUTE:Energy.intensity.inputs:v1SCHEMA:COMPUTE:Energy.common.options:v1SCHEMA:COMPUTE:Energy.intensity.output:v1comp.energy.intensityMEID_CALC_ENERGY_INT_v1noneenv
Energy.renewable.abs1.0activeaggregationRenewable energy consumptionSCHEMA:COMPUTE:Energy.renewable.inputs:v1SCHEMA:COMPUTE:Energy.common.options:v1SCHEMA:COMPUTE:Energy.abs.output:v1comp.energy.renewableMEID_CALC_ENERGY_RE_v1noneenv
Energy.renewable.share1.0activenormalizationShare of renewables in total energySCHEMA:COMPUTE:Energy.share.inputs:v1SCHEMA:COMPUTE:Energy.common.options:v1SCHEMA:COMPUTE:Energy.share.output:v1comp.energy.shareMEID_CALC_SHARE_v1noneenv
Energy.electricity.abs1.0activeaggregationPurchased electricity consumptionSCHEMA:COMPUTE:Energy.electricity.inputs:v1SCHEMA:COMPUTE:Energy.common.options:v1SCHEMA:COMPUTE:Energy.abs.output:v1comp.energy.electricityMEID_CALC_ENERGY_ELEC_v1noneenv
Energy.fuels.abs1.0activeaggregationFuel energy consumptionSCHEMA:COMPUTE:Energy.fuels.inputs:v1SCHEMA:COMPUTE:Energy.common.options:v1SCHEMA:COMPUTE:Energy.abs.output:v1comp.energy.fuelsMEID_CALC_ENERGY_FUEL_v1noneenv
Energy.split_by_carrier1.0activesplitEnergy by carrier breakdownSCHEMA:COMPUTE:Energy.split.inputs:v1SCHEMA:COMPUTE:Energy.common.options:v1SCHEMA:COMPUTE:Energy.split.output:v1comp.energy.splitMEID_CALC_SPLIT_v1noneenv
Energy.delta_yoy1.0activedeltaYear-over-year energy changeSCHEMA:COMPUTE:Energy.delta.inputs:v1SCHEMA:COMPUTE:Energy.delta.options:v1SCHEMA:COMPUTE:Energy.delta.output:v1comp.energy.deltaMEID_CALC_DELTA_v1noneenv

Water (7)

method_idversionstatusmethod_typedescriptioninputs_schema_jsonoptions_schema_jsonoutput_schema_jsonimplementation_refmicro_engine_refdataset_requirementsacl_tags
Water.withdrawal.abs1.0activeaggregationTotal water withdrawalSCHEMA:COMPUTE:Water.withdrawal.inputs:v1SCHEMA:COMPUTE:Water.common.options:v1SCHEMA:COMPUTE:Water.abs.output:v1comp.water.withdrawalMEID_CALC_WATER_AGGR_v1noneenv
Water.withdrawal.intensity1.0activeintensityWater withdrawal per € revenueSCHEMA:COMPUTE:Water.intensity.inputs:v1SCHEMA:COMPUTE:Water.common.options:v1SCHEMA:COMPUTE:Water.intensity.output:v1comp.water.intensityMEID_CALC_WATER_INT_v1noneenv
Water.consumption.abs1.0activeaggregationWater consumptionSCHEMA:COMPUTE:Water.consumption.inputs:v1SCHEMA:COMPUTE:Water.common.options:v1SCHEMA:COMPUTE:Water.abs.output:v1comp.water.consumptionMEID_CALC_WATER_CONS_v1noneenv
Water.discharge.abs1.0activeaggregationWater dischargeSCHEMA:COMPUTE:Water.discharge.inputs:v1SCHEMA:COMPUTE:Water.common.options:v1SCHEMA:COMPUTE:Water.abs.output:v1comp.water.dischargeMEID_CALC_WATER_DISC_v1noneenv
Water.split_by_source1.0activesplitWater withdrawal by sourceSCHEMA:COMPUTE:Water.source.inputs:v1SCHEMA:COMPUTE:Water.common.options:v1SCHEMA:COMPUTE:Water.split.output:v1comp.water.sourceMEID_CALC_SPLIT_v1noneenv
Water.split_by_stress_area1.0activenormalizationWater in stressed areasSCHEMA:COMPUTE:Water.stress.inputs:v1SCHEMA:COMPUTE:Water.stress.options:v1SCHEMA:COMPUTE:Water.stress.output:v1comp.water.stressMEID_CALC_WATER_STRESS_v1WRI_AQUEDUCTenv
Water.delta_yoy1.0activedeltaYear-over-year water changeSCHEMA:COMPUTE:Water.delta.inputs:v1SCHEMA:COMPUTE:Water.delta.options:v1SCHEMA:COMPUTE:Water.delta.output:v1comp.water.deltaMEID_CALC_DELTA_v1noneenv

Waste (5)

method_idversionstatusmethod_typedescriptioninputs_schema_jsonoptions_schema_jsonoutput_schema_jsonimplementation_refmicro_engine_refdataset_requirementsacl_tags
Waste.abs1.0activeaggregationTotal waste generatedSCHEMA:COMPUTE:Waste.abs.inputs:v1SCHEMA:COMPUTE:Waste.common.options:v1SCHEMA:COMPUTE:Waste.abs.output:v1comp.waste.aggregateMEID_CALC_WASTE_AGGR_v1noneenv
Waste.intensity1.0activeintensityWaste per € revenueSCHEMA:COMPUTE:Waste.intensity.inputs:v1SCHEMA:COMPUTE:Waste.common.options:v1SCHEMA:COMPUTE:Waste.intensity.output:v1comp.waste.intensityMEID_CALC_WASTE_INT_v1noneenv
Waste.hazardous.abs1.0activeaggregationHazardous waste generatedSCHEMA:COMPUTE:Waste.hazard.inputs:v1SCHEMA:COMPUTE:Waste.common.options:v1SCHEMA:COMPUTE:Waste.abs.output:v1comp.waste.hazardMEID_CALC_WASTE_HAZ_v1noneenv
Waste.hazardous.share1.0activenormalizationHazardous share of total wasteSCHEMA:COMPUTE:Waste.share.inputs:v1SCHEMA:COMPUTE:Waste.common.options:v1SCHEMA:COMPUTE:Waste.share.output:v1comp.waste.shareMEID_CALC_SHARE_v1noneenv
Waste.diversion_rate1.0activenormalizationWaste diverted from landfill/incinerationSCHEMA:COMPUTE:Waste.diversion.inputs:v1SCHEMA:COMPUTE:Waste.common.options:v1SCHEMA:COMPUTE:Waste.diversion.output:v1comp.waste.diversionMEID_CALC_WASTE_DIV_v1noneenv

1.6. Compute Method Registry - Schema Reference​

Compute Method Registry

compute_method_registryDraft
Source file: compute_method_registry.xlsx
SignalTypeExampleDescription
acl_tagsJSONBEU_ONLY, NO_PHIArray of policy tags for enforcement (e.g., ['EU_ONLY','NO_PHI']). Validated against ACL Tag Registry (acl_tag_registry).
created_atTIMESTAMPTZ2025-01-12T09:14:22ZRow creation timestamp (UTC).
dataset_requirementsJSONBIPCC-EFDB, IEA_SSPArray/object describing required datasets/refs, e.g. ['IPCC-EFDB','IEA_SSP']. Validated against dataset_key registry.
descriptionTEXTComputes GHG intensity per revenue unitHuman-readable summary of what the method computes and when to use it.
implementation_refTEXTpython://zayaz.compute.ghg:intensity_v1Resolvable entrypoint, e.g. python://zayaz.compute.ghg:intensity_v1 or container/image ref. Loader imports/calls this.
inputs_schema_jsonTEXTzar://json-schema/ghg_intensity_inputs_v1ZAR artifact ID for JSON Schema describing required/optional input fields and constraints (units, mins, enums). Enforced at runtime.
method_idTEXT (PK)MID-00001Surrogate ID for the compute method, e.g. MID-00001. Used as stable contract ID across ZAYAZ.
method_nameTEXTGHG.intensityCanonical method name, e.g. GHG.intensity, Water.abs. Human/machine-friendly semantic identifier.
options_schema_jsonTEXTzar://json-schema/ghg_intensity_options_v1ZAR artifact ID for JSON Schema describing optional method options (e.g., jurisdiction, scope3_category). May point to a trivial {} schema.
output_schema_jsonTEXTzar://json-schema/ghg_intensity_output_v1ZAR artifact ID for JSON Schema describing method output payload (e.g., result, unit, provenance). Enforced post-compute.
statusTEXTsupportedLifecycle state: supported | beta | deprecated. Used by discovery and allowlists.
updated_atTIMESTAMPTZ2025-03-03T16:41:09ZRow last update timestamp (UTC)
versionTEXT1.0.0Semantic version of the method implementation and schema (e.g., 1.0.0). Enables side-by-side versions.
Family
auditclassificationcodeidtext
Used by engines
ALTDMICESEMZAAMZARAZHIFZSSR
Used by modules
CHUBRIHUBSISZARA

Example Row: GHG.intensity

compute_method_registry_row.jsonGitHub ↗
{
  "method_id": "GHG.intensity",
  "version": "1.0",
  "method_type": "intensity",
  "inputs_schema_json": {
    "scope1": "tCO2e",
    "scope2": "tCO2e",
    "scope3": "tCO2e",
    "revenue": "EUR"
  },
  "output_schema_json": {
    "value": "tCO2e_per_EUR_million"
  },
  "assumptions_json": {
    "currency": "EUR",
    "scope3_optional": true
  },
  "framework_refs": ["ESRS_E1", "GHG_PROTOCOL"],
  "micro_engine_ref": "MEID_CALC_GHG_INTENSITY_v1"
}

Example Row 2: GHG.scenario_align

compute_method_registry_row_2.jsonGitHub ↗
{
  "method_id": "GHG.scenario_align",
  "method_type": "scenario",
  "dataset_requirements": ["IEA_NZ2050", "IPCC_SSP1"],
  "assumptions_json": {
    "baseline_year": 2020,
    "linear_interpolation": true
  },
  "micro_engine_ref": "MEID_SCEN01_v1"
}

Detailed explanation:

"Inputs" in the example payload is the runtime data, whereas inputs_schema_json in compute_method_registry is the contract that validates that data.

They are tightly coupled, but not the same thing. Below is the clean, v1-correct mental model for ZAYAZ.

1.6.1. Three distinct layers (do not collapse them)​

A. inputs_schema_json (registry layer – static contract)

This is what lives in compute_method_registry.

It is:

  • A ZAR artifact ID (or embedded JSON)
  • Pointing to a JSON Schema that defines:
    • Required vs optional fields
    • Types, units, ranges, enums
    • Structural constraints

Example (conceptual):

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["emissions", "scenario_curve_ref"],
  "properties": {
    "emissions": {
      "type": "array",
      "description": "Time series of [year, value] pairs",
      "items": {
        "type": "array",
        "minItems": 2,
        "maxItems": 2,
        "items": [
          { "type": "integer", "minimum": 1990 },
          { "type": "number", "minimum": 0 }
        ]
      }
    },
    "scenario_curve_ref": {
      "type": "string",
      "pattern": "^IPCC_SSP[0-9]_[0-9.]+$"
    }
  }
}

In the registry this should be referenced as:

inputs_schema_json = "SCHEMA:COMPUTE:compute.GHG.scenario_align.inputs:v1"

✅ Enforced by:

  • Rule Engine
  • MICE pre-validation
  • DICE / DaVE trust scoring

B. inputs (execution layer – runtime payload)

This is what the example shows.

{
  "emissions": [[2025, 12500], [2026, 12000], [2027, 11000]],
  "scenario_curve_ref": "IPCC_SSP1_1.9"
}

This:

  • Is validated against inputs_schema_json
  • Is never stored in the registry
  • Lives in:
    • Execution requests
    • Computation jobs
    • Audit logs (ALTD)

C. options_schema_json → options (contextual modifiers)

Same pattern, different intent:

  • options_schema_json = contract
  • options = runtime modifiers (jurisdiction, sector, consolidation logic)

These must never leak into inputs, or you will break comparability.

1.6.2. Mapping the example correctly​

The above example:

{
  "method": "GHG.scenario_align",
  "inputs": {
    "emissions": [2025, 12500, 2026, 12000, 2027, 11000],
    "scenario_curve_ref": "IPCC_SSP1_1.9"
  },
  "options": {
    "jurisdiction": "EU",
    "sector": "Manufacturing"
  }
}

Correct ZAYAZ interpretation

LayerWhere it belongs
"method"API / orchestration layer
"inputs"Runtime payload → validated by inputs_schema_json
"options"Runtime payload → validated by options_schema_json
JSON SchemaZAR artifact referenced in registry

1.6.3. Strong v1 naming discipline (important)​

To avoid confusion:

TermMeaning
inputs_schema_jsonZAR reference to JSON Schema (contract)
inputsRuntime values
options_schema_jsonZAR reference to options schema
optionsRuntime modifiers
dataset_requirementsExternal data dependencies
assumptions_jsonMethod-level logic assumptions

1.6.4. Why this separation is critical for ZAYAZ​

This clean split enables:

  • 🔒 Audit replay (“re-run with same schema + data”)
  • 🤖 ZARA explainability (“input X violated constraint Y”)
  • 🔁 Engine reuse across methods
  • 🧩 White-label safety (partners can’t mutate logic)
  • 🛡 CSRD / ESRS defensibility

Compute Method Latest

compute_method_latestDraft
Source file: compute_method_latest.xlsx
SignalTypeExampleDescription
method_idTEXTMID-00001, MID-00042Method name (e.g., GHG.intensity, Water.abs). Primary key; one 'latest' row per method.
noteTEXTPromoted after validation and drift checks., Hotfix release validated and approved by platform ops.Admin/operator note explaining why this version is latest (e.g., 'post–gate promotion', 'hotfix').
updated_atTIMESTAMPTZ2025-01-15T08:22:12Z, 2025-01-16T10:45:09ZTimestamp (UTC) when 'latest' pointer was last changed.
versionTEXT1.1.2, 1.0.0Version currently designated as 'latest' for this method (e.g., 1.1.0). FK to compute_method_registry(method_id, version).
Family
auditcodeidtext
Used by engines
ALTDMICEZARAZSSR
Used by modules
CHUBSISZARA

Compute Executions

compute_executionsDraft
Source file: compute_executions.xlsx
SignalTypeExampleDescription
caller_ipTEXT192.168.14.52, 15.188.110.23Source IP for security / anomaly analysis.
created_atTEXT2025-02-01T10:14:33Z, 2025-02-01T10:14:34ZExecution timestamp (UTC).
dataset_hashesTEXTIPCC-EFDB:sha256-a123bc9f1d92f12398fabc77bb38d99f2c91afbd5311a37d,IEA_SSP:sha256-98231acd19fa0287fb29c8ff093a772cd44aa2bc1faff391, UN_FAO_WATER:sha256-71ab3cd19fa0aa77fb29c8ff093a772cd44aa2135d1ac191Array/map of dataset artifact hashes used (e.g., ['IPCC-EFDB:sha256-...','IEA_SSP:sha256-...']).
error_codeTEXTnull, SCHEMA_VALIDATION_FAILEDMachine-readable error code if status='error' (e.g., SCHEMA_VALIDATION_FAILED).
exec_idstring (pk)01J9Z9K4M2F7W7N4Q7ZJ9V9XGF, 01J9Z9KCN4AMJ5T2W6S5XYF4E9Globally unique execution ID (ULID). Primary key.
inputs_hashTEXTsha256:3fa42eab87cbdd29d8fd0c9a8bd1cb6a543920d8e16c08c28a1c78c9231e4b92, sha256:a128ab769e12ba91bb221b0a8afbd5311a37d4a0e366620eefb4e32976cf81aaCryptographic hash (e.g., sha256:...) of normalized input payload.
latency_msTEXT143, 212End-to-end compute latency in milliseconds.
method_idTEXTMID-00001, MID-00042Method ID (e.g., MID-00001). FK part 1 → ref_compute_method_registry.method_id.
options_hashTEXTsha256:92f8aa769e12b2a3bfb2f2c91afbd5311a37d4a0e366620eefb4e32976c029d2, sha256:81aeaa769e12f89dfbb2f2c91afbd5311a37d4a0e366620eefb4e32976acc2b0Cryptographic hash of normalized options payload.
output_hashTEXTsha256:4cd920fa8912a4627bb9eab32c5fdd314ff2a119e80cc291eabe927caae123ef, sha256:f12920fa8912ff111bb9eab32c5fdd314ff2a119e80cc291eabe927caac44ab1Cryptographic hash of normalized output payload. Optional if execution failed pre-output.
provenance_idTEXTprov-7f892b1a3cdd4e8f8fba2e, prov-c102aa39efdd4694948df2Correlation ID returned to caller; links UI/API to this audit row.
regionTEXTeu-north-1, eu-central-1Region tag where compute ran (e.g., eu-north-1).
statusTEXTok, errorok | error. Final outcome.
storage_refTEXTs3://zayaz-computations/exec/01J9Z9K4M2F7W7N4Q7ZJ9V9XGF/input_output.json, s3://zayaz-computations/exec/01J9Z9KCN4AMJ5T2W6S5XYF4E9/input_output.jsonPointer to sealed blob with full input/output snapshots if retained.
tenant_idTEXTeco-197-123-456-789, eco-044-001-882-331Tenant/customer identifier (used for multi-tenant isolation and audit).
versionTEXT1.1.2, 1.0.0Exact version used (e.g., 1.0.0). FK part 2 → ref_compute_method_registry.version.
Family
auditclassificationcodegeoidmetric
Used by engines
ALTDDAVEDICEMICEPOSTHSEMZARAZSSR
Used by modules
CHUBRIHUBSISZARA


Example row:

compute_method_registry.sqlGitHub ↗
INSERT INTO compute_method_registry (
  method_id, version, status, description,
  inputs_schema_json, options_schema_json, output_schema_json,
  implementation_ref, dataset_requirements, acl_tags
) VALUES (
  'GHG.intensity', '1.0.0', 'supported',
  'GHG emissions per € revenue (Scopes 1/2/3 or category subsets)',
  '{
    "$schema":"https://json-schema.org/draft/2020-12/schema",
    "type":"object",
    "properties":{
      "scope1":{"type":"number","minimum":0},
      "scope2":{"type":"number","minimum":0},
      "scope3_cat1":{"type":"number","minimum":0},
      "revenue":{"type":"number","exclusiveMinimum":0}
    },
    "required":["revenue"],
    "additionalProperties":false
  }'::jsonb,
  '{
    "type":"object",
    "properties":{"scope3_category":{"type":"string"}, "jurisdiction":{"type":"string"}},
    "additionalProperties":false
  }'::jsonb,
  '{
    "type":"object",
    "properties":{"result":{"type":"number"},"unit":{"type":"string"},"provenance":{"type":"object"}},
    "required":["result","unit","provenance"]
  }'::jsonb,
  "python://zayaz.compute.ghg:intensity_v1",
  '["IPCC-EFDB"]'::jsonb,
  '["EU_ONLY"]'::jsonb
);

Service startup: dynamic loader

compute_registry.pyGitHub ↗
# compute_registry.py
from importlib import import_module
from jsonschema import Draft202012Validator

class MethodSpec:
    def __init__(self, row):
        self.id = row["method_id"]
        self.version = row["version"]
        self.status = row["status"]
        self.inputs_schema = row["inputs_schema_json"]
        self.options_schema = row["options_schema_json"]
        self.output_schema = row["output_schema_json"]
        self.impl_ref = row["implementation_ref"]
        self.datasets = row["dataset_requirements"] or []
        self.acl = row["acl_tags"] or []

def load_methods(db):
    specs = {}
    for row in db.query("SELECT * FROM compute_method_registry WHERE status <> 'deprecated'"):
        spec = MethodSpec(row)
        # Resolve entrypoint like "python://package.module:function"
        module_path, fn_name = spec.impl_ref.replace("python://","").split(":")
        fn = getattr(import_module(module_path), fn_name)
        # Precompile validators
        spec.validate_in  = Draft202012Validator(spec.inputs_schema)
        spec.validate_opt = Draft202012Validator(spec.options_schema or {"type":"object"})
        spec.validate_out = Draft202012Validator(spec.output_schema)
        specs[(spec.id, spec.version)] = (spec, fn)
    return specs

METHODS = load_methods(db)

On request:

compute_registry-or.pyGitHub ↗
def execute(method_id, version, inputs, options, ctx):
    spec, fn = METHODS[(method_id, version)]
    spec.validate_in.validate(inputs)
    spec.validate_opt.validate(options or {})
    assert ctx.datasets_ok(spec.datasets)             # dataset presence/provenance
    assert ctx.acl_ok(spec.acl)                       # residency/tenant ACL
    result = fn(inputs, options, ctx)                 # pure function
    spec.validate_out.validate(result)                # guarantee contract
    ctx.audit_log(method_id, version, inputs, options, result, spec.datasets)
    return result

Method implementation skeleton

ghg.pyGitHub ↗
# zayaz/compute/ghg.py
def intensity_v1(inputs, options, ctx):
    s1 = inputs.get("scope1", 0.0)
    s2 = inputs.get("scope2", 0.0)
    s3 = sum(v for k,v in inputs.items() if k.startswith("scope3_"))
    rev = inputs["revenue"]  # schema guarantees present and >0
    val = (s1 + s2 + s3) / rev
    return {
        "result": val,
        "unit": "tCO2e/€m",
        "provenance": {
            "dataset": "IPCC-EFDB.xlsx",
            "method": "EFDB Tier 1",
            "hash": ctx.dataset_hash("IPCC-EFDB.xlsx")
        }
    }

Discovery endpoint Expose a discovery API so methods are never hard-coded:

compute-methods.htmlGitHub ↗
GET /compute/methods
Accept: application/json
compute-methods.jsonGitHub ↗
{
  "methods": [
    {
      "method_id": "GHG.intensity",
      "version": "1.0.0",
      "status": "supported",
      "description": "GHG emissions per € revenue…",
      "inputs_schema": { "$ref": "https://schemas.zayaz.io/compute/GHG.intensity/inputs/1.0.0" },
      "options_schema": { "$ref": "https://schemas.zayaz.io/compute/GHG.intensity/options/1.0.0" },
      "output_schema": { "$ref": "https://schemas.zayaz.io/compute/GHG.intensity/output/1.0.0" }
    },
    {
      "method_id": "GHG.scenario_align",
      "version": "1.0.0",
      "status": "beta",
      "description": "Scenario alignment against pathways",
      "inputs_schema": { "$ref": "https://schemas.zayaz.io/compute/GHG.scenario_align/inputs/1.0.0" },
      "options_schema": { "$ref": "https://schemas.zayaz.io/compute/GHG.scenario_align/options/1.0.0" },
      "output_schema": { "$ref": "https://schemas.zayaz.io/compute/GHG.scenario_align/output/1.0.0" }
    }
  ]
}

CI/CD & Governance

Contract tests (CI) - bash:

# 1) Lint schemas
jsonschema-lint schemas/**/*.json

# 2) Validate sample payloads against registry schemas
pytest tests/compute_contracts/ --maxfail=1 -q

# 3) Golden tests (determinism within tolerances)
pytest tests/compute_golden/ --maxfail=1 -q

Promotion policy:

  • New method → status = beta, requires:
    • Passing Evaluation Harness numeric gates (0% numeric hallucination).
    • SLO checks (latency P95, error rate).
    • Data residency & ACL checks.
  • After approval → flip to supported via DB migration/PR.
  • Deprecation: mark deprecated, keep available for 12 months; discovery API returns "status":"deprecated" and a "replacement":"<method,version>".

Helm values / feature flagging:

feature-flagging.yamlGitHub ↗
compute:
  allow_methods:
    - method_id: GHG.intensity
      version: "1.0.0"
    - method_id: GHG.scenario_align
      version: "1.0.0"

The service enforces an allowlist on top of the registry for staged rollout.

1.7. Standards Frameworks — Dynamic Policy Gate (Production Pack)​

JiraStoryUnlinkedZYZ-732AIIL-CON#17-standards-frameworks-dynamic-policy-gate-production-pack#1

The relationship between the Standards Frameworks tables and the Compute Methods tables is that the Standards Frameworks tables (such as the criteria tables holding rules and pack-specific standards) define the decision logic and criteria that the AI Intelligence Layer uses, while the Compute Methods tables provide the versioned, approved deterministic compute functions that the AI must call to perform calculations or validations.

Specifically:

  • Standards Frameworks tables contain critical/blocker rules and criteria that guide AI decision-making (e.g., from the framework’s criteria table).
  • Compute Methods tables register versioned compute functions that AI calls to ensure numbers are not fabricated and calculations are deterministic and auditable.
  • The AI Intelligence Layer connects these by enforcing that AI responses adhere to standards (from the frameworks) and rely on approved compute methods for calculations, ensuring provenance and auditability.

Thus, Standards Frameworks define what rules and criteria apply, and Compute Methods define how the computations to evaluate those rules are performed in a controlled, verifiable manner.

  • Postgres DDL: frameworks & criteria

Input Table Structure

standards_frameworksDraft
Source file: standards_frameworks.xlsx
SignalTypeExampleDescription
created_attimestamptz2025-01-10T08:22:14ZTimestamp when the framework record was created
descriptionstringESRS set of standards under CSRD for sustainability disclosuresTextual description of scope and purpose of the framework
framework_idstring (pk)ESRSCanonical identifier of a standards framework (e.g. ESRS, ISSB, SEC). Globally stable and later usable as a USO concept anchor, a policy routing key in TR/PG, a compliance scope discriminator in ZADIF
namestringEuropean Sustainability Reporting StandardsHuman-readable name of the standards framework
statusenumsupportedLifecycle status of the framework (supported, beta, deprecated)
updated_attimestamptz2025-06-02T11:05:37ZTimestamp when the framework record was last updated
Family
auditclassificationcodetext
Used by engines
ALTDTRPGZADIFZARAZSSR
Used by modules
IHUBRIHUBSISZARA

standards_frameworks.sql

standards_frameworks.sqlGitHub ↗
-- 1. Frameworks master
CREATE TABLE IF NOT EXISTS standards_frameworks (
  framework_id TEXT PRIMARY KEY,           -- e.g., 'ESRS', 'ISSB', 'SEC'
  name         TEXT NOT NULL,              -- human label
  status       TEXT NOT NULL DEFAULT 'supported', -- supported|beta|deprecated
  description  TEXT NOT NULL DEFAULT '',
  created_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at   TIMESTAMPTZ NOT NULL DEFAULT now()
);

Input Table Structure

standards_criteriaDraft
Source file: standards_criteria.xlsx
SignalTypeExampleDescription
created_attimestamptz2025-02-14T09:31:07ZTimestamp when the criterion was created
criterion_idstring (pk)ESRS.data_residency.eu_onlyCanonical identifier of a policy criterion (e.g. ESRS.data_residency.eu_only)
descriptionstringRequires all regulated data to remain within EU regionsHuman-readable explanation of the criterion
engineenumjsonlogicRule evaluation engine (jsonlogic, cel)
framework_idstring (fk)ESRSReference to owning standards framework
rule_jsonjsonb{”==”:[{“var”:“data_region”},“EU”]}Serialized rule definition executed by the policy engine
severityenumblockEnforcement level (block, warn, info)
updated_attimestamptz2025-05-21T16:44:52ZTimestamp when the criterion was last updated
versionstring1.0.0Semantic version of the criterion rule
Family
auditclassificationcodetext
Used by engines
ALTDTRPGZADIFZARA
Used by modules
RIHUBSISZARA

standards_criteria.sql

standards_criteria.sqlGitHub ↗
-- 2. Criteria catalog (per framework)
-- Each row is a boolean rule expressed as JSONLogic or CEL (your choice).
CREATE TABLE IF NOT EXISTS standards_criteria (
  criterion_id   TEXT PRIMARY KEY,      -- e.g., 'ESRS.data_residency.eu_only'
  framework_id   TEXT NOT NULL REFERENCES standards_frameworks(framework_id) ON DELETE CASCADE,
  version        TEXT NOT NULL,         -- semantic version for the rule
  engine         TEXT NOT NULL,         -- 'jsonlogic' | 'cel'
  rule_json      JSONB NOT NULL,        -- JSONLogic expr or CEL serialized config
  severity       TEXT NOT NULL DEFAULT 'block',  -- block|warn|info
  description    TEXT NOT NULL DEFAULT '',
  created_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at     TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (framework_id, criterion_id, version)
);

Input Table Structure

tenant_frameworksDraft
Source file: tenant_frameworks.xlsx
SignalTypeExampleDescription
created_attimestamptz2025-01-22T10:18:05ZTimestamp when the tenant-framework link was created
framework_idstring (pk, fk)ESRSFramework enabled or disabled for the tenant
notesstringEnabled for CSRD FY2025 reportingTenant-specific annotations or governance notes
statusenumenabledEnablement state (enabled, disabled)
tenant_idstring (pk, fk)eco-196-123-456-789Tenant identifier (E-C-O™ Number or internal tenant key)
updated_attimestamptz2025-06-01T15:42:11ZTimestamp when the tenant-framework link was last updated
Family
auditclassificationcodeidtext
Used by engines
ALTDTRPGZADIFZARA
Used by modules
SISZARA

tenant_frameworks.sql

tenant_frameworks.sqlGitHub ↗
-- 3. Framework enablement per tenant (allowlist)
CREATE TABLE IF NOT EXISTS tenant_frameworks (
  tenant_id     TEXT NOT NULL,
  framework_id  TEXT NOT NULL REFERENCES standards_frameworks(framework_id) ON DELETE CASCADE,
  status        TEXT NOT NULL DEFAULT 'enabled', -- enabled|disabled
  notes         TEXT NOT NULL DEFAULT '',
  created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  updated_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
  PRIMARY KEY (tenant_id, framework_id)
);

Input Table Structure

framework_criteria_latestDraft
Source file: framework_criteria_latest.xlsx
SignalTypeExampleDescription
criterion_idstringESRS.data_residency.eu_onlyCriterion identifier
descriptionstringEnforces EU-only data residency for regulated datasetsCriterion description
engineenumjsonlogicRule engine used
framework_idstringESRSFramework identifier
rule_jsonjsonb{”==”:[{“var”:“data_region”},“EU”]}Latest executable rule definition
severityenumblockEnforcement severity
updated_attimestamptz2025-06-10T09:55:31ZTimestamp of the latest criterion update
versionstring1.2.0Latest version of the criterion
Family
auditclassificationcodetext
Used by engines
ALTDTRPGZADIFZARA
Used by modules
RIHUBSISZARA

framework_criteria_latest.sql

framework_criteria_latest.sqlGitHub ↗
-- 4. Optional: “latest” view for criteria per framework
CREATE VIEW framework_criteria_latest AS
SELECT DISTINCT ON (framework_id, criterion_id)
  framework_id, criterion_id, version, engine, rule_json, severity, description, updated_at
FROM standards_criteria
ORDER BY framework_id, criterion_id, updated_at DESC;

Notes:

  • standards_frameworks

    • framework_id should be globally stable and later usable as:
      • a USO concept anchor
      • a policy routing key in TR/PG
      • a compliance scope discriminator in ZADIF

  • standards_criteria table

    • ZAYAZ best-practice extension (recommended):
      • Add applicable_scope later (reporting, data_ingest, export, ai_action)
      • Add trust_impact_weight to feed VTE / DaVE scoring

  • tenant_frameworks

    • Important design intent:
      • This table is what lets ZARA ask:
      • “Which frameworks am I allowed to reason under for this tenant?”

  • framework_criteria_latest

    • framework_criteria_latest is a read-optimized derived view, not a persistence table. It provides a deterministic projection of the most recent criterion version per framework and criterion ID, intended for:
      • policy evaluation engines
      • runtime compliance checks
      • API consumers requiring “current truth” without version negotiation

  • Seed data: ESRS, ISSB, SEC (minimum viable)

framework-examples.sqlGitHub ↗
-- Frameworks
INSERT INTO standards_frameworks (framework_id, name, status, description)
VALUES
  ('ESRS','EU ESRS','supported','European Sustainability Reporting Standards'),
  ('ISSB','ISSB IFRS S1/S2','beta','IFRS Sustainability & Climate disclosures'),
  ('SEC','US SEC Climate','beta','US SEC climate-related disclosures')
ON CONFLICT (framework_id) DO UPDATE
SET name=EXCLUDED.name, status=EXCLUDED.status, description=EXCLUDED.description, updated_at=now();

-- Criteria (examples)
-- ESRS: require EU data residency for compute + storage
INSERT INTO standards_criteria (criterion_id, framework_id, version, engine, rule_json, severity, description)
VALUES
('ESRS.data_residency.eu_only','ESRS','1.0.0','jsonlogic',
  '{"==":[{"var":"tenant.region"}, "EU"]}', 'block',
  'Tenant region must be EU for ESRS processing/export'),
('ESRS.pack.enabled','ESRS','1.0.0','jsonlogic',
  '{"in":[ "ESRS", {"var":"tenant.framework_allowlist"} ]}', 'block',
  'ESRS must be allowlisted for this tenant');

-- ISSB: allow global residency, but require ISSB pack enablement
INSERT INTO standards_criteria (criterion_id, framework_id, version, engine, rule_json, severity, description)
VALUES
('ISSB.pack.enabled','ISSB','1.0.0','jsonlogic',
  '{"in":[ "ISSB", {"var":"tenant.framework_allowlist"} ]}', 'block',
  'ISSB must be allowlisted for this tenant');

-- SEC: US residency or approved exception; pack enabled
INSERT INTO standards_criteria (criterion_id, framework_id, version, engine, rule_json, severity, description)
VALUES
('SEC.residency.us_or_exception','SEC','1.0.0','jsonlogic',
  {"or":[ {"==":[{"var":"tenant.region"}, "US"]}, {"==":[{"var":"tenant.policy_exception"}, true]} ]}, 'block',
  'SEC requires US residency or approved exception'),
('SEC.pack.enabled','SEC','1.0.0','jsonlogic',
  '{"in":[ "SEC", {"var":"tenant.framework_allowlist"} ]}', 'block',
  'SEC must be allowlisted for this tenant')
ON CONFLICT (criterion_id) DO NOTHING;

More granular rules can be added later (e.g., “export destinations”, “dataset white/blacklists”) by upserting new criteria rows — no app code change required.

  • FastAPI runtime: load criteria and evaluate dynamically Key idea: requests declare framework (e.g., "ESRS") and we evaluate all latest criteria for that framework (from the DB) against a context object (tenant profile + request metadata). Block or warn based on rule outcomes.
runtime.pyGitHub ↗
# app/standards/runtime.py
from typing import Dict, List
from fastapi import HTTPException
import asyncpg
import json
from jsonlogic import jsonLogic  # pip install json-logic-qubit (or equivalent)

class CriteriaRepo:
    def __init__(self, pool: asyncpg.Pool):
        self.pool = pool

    async def get_latest_rules(self, framework_id: str) -> List[Dict]:
        sql = """
          SELECT framework_id, criterion_id, version, engine, rule_json, severity
          FROM v_framework_criteria_latest
          WHERE framework_id = $1
        """
        async with self.pool.acquire() as conn:
            rows = await conn.fetch(sql, framework_id)
        return [dict(r) for r in rows]

async def evaluate_framework(pool: asyncpg.Pool, framework_id: str, context: Dict):
    repo = CriteriaRepo(pool)
    rules = await repo.get_latest_rules(framework_id)
    violations = []
    for r in rules:
        engine = r["engine"]
        rule = r["rule_json"]
        if engine == "jsonlogic":
            ok = bool(jsonLogic(rule, context))
        else:
            # Extend with CEL engine if used (compile/eval CEL expr)
            # ok = eval_cel(rule, context)
            raise HTTPException(status_code=500, detail=f"Unsupported engine: {engine}")
        if not ok and r["severity"] == "block":
            violations.append({"criterion_id": r["criterion_id"], "severity": r["severity"]})
    if violations:
        raise HTTPException(
            status_code=403,
            detail={"message": "Framework policy blocked", "framework": framework_id, "violations": violations}
        )

How to use: In the router or adapter path, call evaluate_framework(pool, framework_id, context) before retrieval/compute/export. The context object is table-driven (e.g., tenant.region, tenant.framework_allowlist, request.export_target, etc.).

Adaptive JSON Schema (driven by frameworks table)

Expose a disclosure request schema that validates framework against the DB and adapts optional/required fields based on what’s enabled. (In practice, you can serve a prebuilt static schema per framework or build at runtime.)

Minimal dynamic generator (Python)

schema.pyGitHub ↗
# app/standards/schema.py
from typing import Dict, List

def schema_for_frameworks(framework_ids: List[str]) -> Dict:
    return {
      "$id": "https://zayaz.io/schemas/disclosure.request.json",
      "type": "object",
      "required": ["framework", "datapoint_ref"],
      "properties": {
        "framework": { "type": "string", "enum": framework_ids },
        "datapoint_ref": { "type": "string" },
        "inputs": { "type": "object" },
        "options": { "type": "object" }
      },
      "allOf": [
        # Example: ESRS adds required 'citations'
        {
          "if": {"properties": {"framework": {"const": "ESRS"}}},
          "then": {
            "properties": {
              "citations": {
                "type": "array",
                "items": { "type": "string", "pattern": r"\[.+?:L\d+-L\d+\]" }
              }
            },
            "required": ["citations"]
          }
        },
        # Extend with ISSB/SEC specific clauses...
      ]
    }

Endpoint that serves the current schema (reads frameworks table):

api.pyGitHub ↗
# app/standards/api.py
from fastapi import APIRouter, Depends
import asyncpg
from .schema import schema_for_frameworks

router = APIRouter(prefix="/standards", tags=["standards"])

async def get_pool() -> asyncpg.Pool:
    # wire your pool creation elsewhere and inject here
    ...

@router.get("/schema")
async def get_dynamic_schema(pool: asyncpg.Pool = Depends(get_pool)):
    rows = await pool.fetch("SELECT framework_id FROM standards_frameworks WHERE status IN ('supported','beta')")
    framework_ids = [r["framework_id"] for r in rows]
    return schema_for_frameworks(framework_ids)

This guarantees clients always see a schema aligned to whatever frameworks are present in the table (and their policies baked into allOf clauses).

  • Admin endpoints (upsert frameworks/criteria)

Use idempotent upserts so admins can add/modify frameworks & criteria without redeploys. Wrap in RBAC (“standards_admin”) and audit every change.

admin_api.pyGitHub ↗
# app/standards/admin_api.py
from fastapi import APIRouter, Depends, HTTPException
from pydantic import BaseModel, Field
import asyncpg
from typing import List, Literal, Dict, Any

router = APIRouter(prefix="/admin/standards", tags=["admin-standards"])

class FrameworkUpsert(BaseModel):
    framework_id: str = Field(pattern=r"^[A-Z]{2,8}$")
    name: str
    status: Literal["supported","beta","deprecated"] = "supported"
    description: str = ""

class CriterionUpsert(BaseModel):
    criterion_id: str
    framework_id: str
    version: str
    engine: Literal["jsonlogic","cel"]
    rule_json: Dict[str, Any]
    severity: Literal["block","warn","info"] = "block"
    description: str = ""

async def get_pool() -> asyncpg.Pool: ...
def require_admin(): ...  # the RBAC

@router.post("/frameworks/upsert")
async def upsert_framework(payload: FrameworkUpsert, pool: asyncpg.Pool = Depends(get_pool), _=Depends(require_admin)):
    sql = """
      INSERT INTO standards_frameworks (framework_id, name, status, description)
      VALUES ($1,$2,$3,$4)
      ON CONFLICT (framework_id) DO UPDATE
      SET name=$2, status=$3, description=$4, updated_at=now()
      RETURNING framework_id;
    """
    async with pool.acquire() as conn:
        row = await conn.fetchrow(sql, payload.framework_id, payload.name, payload.status, payload.description)
    return {"ok": True, "framework_id": row["framework_id"]}

@router.post("/criteria/upsert")
async def upsert_criterion(payload: CriterionUpsert, pool: asyncpg.Pool = Depends(get_pool), _=Depends(require_admin)):
    sql = """
      INSERT INTO standards_criteria (criterion_id, framework_id, version, engine, rule_json, severity, description)
      VALUES ($1,$2,$3,$4,$5,$6,$7)
      ON CONFLICT (criterion_id) DO UPDATE
      SET framework_id=$2, version=$3, engine=$4, rule_json=$5, severity=$6, description=$7, updated_at=now()
      RETURNING criterion_id, version;
    """
    async with pool.acquire() as conn:
        row = await conn.fetchrow(sql, payload.criterion_id, payload.framework_id, payload.version,
                                  payload.engine, json.dumps(payload.rule_json), payload.severity, payload.description)
    return {"ok": True, "criterion_id": row["criterion_id"], "version": row["version"]}
  • Admin safety
    • Require standards_admin role (JWT claim) and log every change with a decision_id in the audit trail.
    • Optionally add dry-run endpoints that evaluate a proposed rule against sample tenant contexts before upsert.

How it ties to AI & compliance (summary)

  • Behavior adapters and routers consult the tables to know which frameworks are enabled and what rules to enforce.
  • RAG prompts and Packaging (JSON/XBRL) apply framework-specific requirements (e.g., ESRS citations, export ACLs) without changing code — admin updates the table.
  • Go/No-Go gates read the same source of truth (criteria) to determine if a call should proceed (block/warn).
  • Auditors/Verifiers can fetch a snapshot of active frameworks & criteria to see exactly what policies governed an AI response.

1.8. The “Standards Registry”s relationship to the “Dataset Registry”​

JiraStoryUnlinkedZYZ-730AIIL-CON#18-the-standards-registry-s-relationship-to-the-dataset-registry#1
  • “Standards Registry” (frameworks/criteria/tenant enablement)
  • “Dataset Registry” (artifacts/schema/provenance/read policies)

The “Standards Registry”s and the “Dataset Registry” are two different registries at two different abstraction layers:

What standards_frameworks is Purpose: A compliance framework registry (policy scope + obligations layer).

It answers:

  • “Which reporting/governance frameworks exist in this tenant’s universe?” (ESRS, ISSB, SEC…)
  • “Is this framework supported/beta/deprecated?”
  • “What policy criteria (rules) apply under that framework?” (via standards_criteria)
  • “Is this framework enabled for this tenant?” (via tenant_frameworks)

Nature of data: Normative / governance metadata (framework identity + policy gates).

Primary consumers: TR/PG policy gating, ZARA compliance reasoning, FOGE form selection by framework, validation requirement selection.

What dataset_registry is Purpose: A data artifact registry (datasets as inputs to computation).

It answers:

  • “What dataset artifact is this?” (dataset_id, provider, version)
  • “Where is it stored and what is its integrity lineage?” (checksum, validity window, docs)
  • “What is its structural contract?” (column_schema, schema_version, primary_keys, partitions)
  • “How may it be read safely?” (read_policy)
  • “How do we validate quality and freshness?” (integrity_rules, update_frequency)

Nature of data: Empirical / computational input metadata (data contracts, provenance, reproducibility).

Primary consumers: ingestion pipelines, validation engines (DaVE/DICE), compute hub / micro-engines, reproducibility/audit (ALTD), query planning/performance.

The clean distinction:

  • standards_frameworks = “What rules/obligations apply?” (policy universe)
  • dataset_registry = “What data is allowed/available to compute with, and under what contract?” (data universe)

How they relate A framework often depends on datasets (e.g., ESRS calculations might rely on IPCC EFDB factors). That dependency should be expressed explicitly, e.g.:

How to bridge tables

framework_dataset_bindings (or framework_dataset_requirements)

  • framework_id
  • dataset_id
  • usage_purpose (e.g., emission_factors, scenario_analysis, taxonomy_mapping)
  • required_for (e.g., E1, E2, ESRS_E1-6)
  • min_dataset_version / allowed_versions
  • tenant_override_allowed (bool)
  • policy_guard (optional: link to a criterion_id that enforces use/ban)

That keeps the system auditable:

  • frameworks define obligations
  • datasets define evidence + computation inputs
  • bindings define approved dependencies

Practical example

  • standards_frameworks: ESRS (supported)
  • standards_criteria: ESRS.data_residency.eu_only (block)
  • dataset_registry: IPCC-EFDB-2023 with checksum, schema, integrity rules
  • binding: ESRS -> IPCC-EFDB-2023 used for E1 emissions factors

So when ZARA or a micro-engine runs a calculation:

  • policy gate confirms ESRS allowed + criteria satisfied
  • compute engine loads dataset by registry key/version + enforces schema/read_policy/integrity_rules

2. Versioning & Lifecycle with Composite Keys.​

  • Parallel versions: Run GHG.intensity v1.0.0 and v1.1.0 side-by-side for canaries/rollouts.
  • Determinism: Every compute call is reproducible: method + version uniquely identifies code, schemas, and outputs.
  • Non-breaking evolution: You can add fields/tweaks in v1.1.0 without risking live users on v1.0.0.
  • Clean deprecation: Mark old versions deprecated without touching newer ones.

Service behavior with composite key

2.1. Discovery endpoint​

JiraStoryUnlinkedZYZ-731AIIL-CON#21-discovery-endpoint#1
  • GET /compute/methods → returns all (method_id, version, status, schemas).
  • Optional: GET /compute/methods/{method_id} to list versions, with a "latest" hint from compute_method_latest.

Invocation

  • Client must pass version for determinism:
    • POST /compute/factor { "method":"GHG.intensity", "version":"1.0.0", ... }
  • Server rejects calls without version (or uses a clear policy: permit only when compute_method_latest has an entry and the caller is on an allowlist).

Promotion

  • Add new row (method_id='GHG.intensity', version='1.1.0', status='beta').
  • Run Eval Harness → flip status to supported.
  • Update compute_method_latest to '1.1.0' when ready (doesn’t affect users who still request 1.0.0 explicitly).

Deprecation

  • Set status='deprecated' for 1.0.0; keep discoverable for a grace window.
  • Optionally enforce an allowlist that blocks deprecated versions in prod tenants.

2.2. Operational Controls & RBAC​

Purpose: Ensure only authorized tenants, users, or services can invoke compute methods, aligned with jurisdictional and contractual constraints.

  • Role-Based Access Control (RBAC):

    • Roles:

      • tenant_admin → full access to methods, can manage users.
      • compute_client → invoke methods approved for their tenant.
      • auditor → list methods, replay past jobs, no new execution.
      • regulator_view → read-only access to results and logs.

    • Scope:

      • RBAC applies at method level with ACL tags enforcing jurisdictional limits.
      • Example: A tenant in the US may be restricted from methods tagged EU_ONLY.

2.3. ACL Tags Integration:​

Each method in compute_method_registry carries acl_tags (JSON array):

tags-integration.jsonGitHub ↗
{
  "method_id": "GHG.intensity",
  "version": "1.0.0",
  "acl_tags": ["EU_ONLY", "NO_PHI"]
}

Runtime enforcement checks:

  • Tenant jurisdiction (tenant.country) vs. EU_ONLY.
  • Input dataset classification (contains_PHI) vs. NO_PHI.

If constraints fail → request rejected (403 Forbidden).

Example RBAC Policy (YAML)

rbac-policy.jsonGitHub ↗
roles:
  tenant_admin:
    allow:
      - "*"
  compute_client:
    allow:
      - "GHG.intensity:*"
      - "Energy.intensity:*"
    deny:
      - "Water.abs:*"   # not licensed
  auditor:
    allow:
      - "GET:/compute/methods"
      - "GET:/compute/jobs/*"
    deny:
      - "POST:/compute/*"
  regulator_view:
    allow:
      - "GET:/audit/logs/*"
      - "GET:/compute/jobs/*"
    deny:
      - "POST:/compute/*"

acl_overrides:
  EU_ONLY:
    allow_regions: ["EU", "NO", "IS", "LI"]
  NO_PHI:
    deny_if_dataset_contains: ["PHI"]

Runtime Enforcement

  • Pre-check: Verify user role & permissions.
  • ACL evaluation: Compare request context (tenant region, dataset tags).
  • Decision log: Write decision_id with outcome (ALLOW or DENY).

Audit Coupling: Every decision is recorded with full context → reproducible RBAC behavior for verifiers and regulators.

2.4. Audit Log Example​

Every RBAC and ACL decision is logged. Logs are immutable, signed, and queryable by verifiers.

audit-log-example.jsonGitHub ↗
{
  "timestamp": "2025-09-14T10:22:35Z",
  "decision_id": "dec-8f92c6a7",
  "tenant_id": "tenant-123",
  "user_id": "user-456",
  "role": "compute_client",
  "method_id": "GHG.intensity",
  "version": "1.0.0",
  "request_context": {
    "region": "NO",
    "datasets": ["IPCC-EFDB.xlsx"],
    "input_hash": "sha256:7f8a1e..."
  },
  "acl_evaluation": {
    "EU_ONLY": "ALLOW",
    "NO_PHI": "ALLOW"
  },
  "outcome": "ALLOW",
  "latency_ms": 43,
  "provenance_id": "prov-a17c22bc"
}

Key Points

  • decision_id: Unique ID for this RBAC evaluation; can be cross-referenced in other logs.
  • role: Role of the caller (compute_client in this case).
  • acl_evaluation: Shows tag-by-tag decision. Helpful when debugging jurisdictional denials.
  • outcome: Either ALLOW or DENY.
  • provenance_id: Links back to the compute job execution record for full reproducibility.

This gives us a closed loop:

  • RBAC Policy (YAML) defines what should happen.
  • Runtime Enforcement applies the rules.
  • Audit Log (JSON) proves what actually happened.

Security & Audit:

Purpose: Guarantee reproducibility, provenance, and traceability for every compute execution.

  • ACL tags (e.g., EU_ONLY) enforced per-tenant/jurisdiction.
  • Dataset requirements verified at runtime; include dataset hashes in output.
  • Audit log per call: tenant, method/version, input hash, output hash, dataset hashes, latency, decision IDs.
  • Reproducibility: every response includes a provenance_id and the method/version used.

Example: adding a new method:

  • PR adds row to compute_method_registry with schemas + implementation_ref.
  • Add implementation function under zayaz.compute.<domain>.
  • Add tests: contract validation + golden outputs.
  • CI passes → staged rollout (Helm allowlist enables for pilot tenants).
  • Promote to supported after Evaluation Harness gates pass.

2.5. Audit Log Query API​

Endpoints

GET /audit/logs Query RBAC/ACL and compute audit entries. Query params (all optional):

  • tenant_id (string)
  • user_id (string)
  • method_id (string) — e.g., GHG.intensity
  • version (string) — e.g., 1.0.0
  • decision (string) — ALLOW | DENY
  • acl_tag (string) — e.g., EU_ONLY
  • from (RFC3339) — start time
  • to (RFC3339) — end time
  • limit (int, default 100, max 1000)
  • cursor (string) — pagination token

Response (200)

audit-log-resp.jsonGitHub ↗
{
  "items": [
    {
      "timestamp": "2025-09-14T10:22:35Z",
      "decision_id": "dec-8f92c6a7",
      "tenant_id": "tenant-123",
      "user_id": "user-456",
      "role": "compute_client",
      "method_id": "GHG.intensity",
      "version": "1.0.0",
      "acl_evaluation": { "EU_ONLY": "ALLOW", "NO_PHI": "ALLOW" },
      "outcome": "ALLOW",
      "provenance_id": "prov-a17c22bc",
      "region": "NO",
      "latency_ms": 43
    }
  ],
  "next_cursor": "eyJwYWdlIjoyfQ=="
}

GET /audit/logs/{decision_id} Fetch a single audit record by decision ID. Response (200):

audit-rec.jsonGitHub ↗
{
  "timestamp": "2025-09-14T10:22:35Z",
  "decision_id": "dec-8f92c6a7",
  "tenant_id": "tenant-123",
  "user_id": "user-456",
  "role": "compute_client",
  "request": {
    "path": "/compute/factor",
    "method": "POST",
    "ip": "203.0.113.10"
  },
  "method_id": "GHG.intensity",
  "version": "1.0.0",
  "request_context": {
    "region": "NO",
    "datasets": ["IPCC-EFDB.xlsx"],
    "input_hash": "sha256:7f8a1e..."
  },
  "acl_evaluation": { "EU_ONLY": "ALLOW", "NO_PHI": "ALLOW" },
  "outcome": "ALLOW",
  "provenance_id": "prov-a17c22bc",
  "links": {
    "execution": "/compute/jobs/prov-a17c22bc"
  }
}

OpenAPI Excerpt

openai-excerpt.yamlGitHub ↗
paths:
  /audit/logs:
    get:
      summary: Query audit logs (RBAC/ACL + compute)
      parameters:
        - in: query; name: tenant_id; schema: { type: string }
        - in: query; name: user_id; schema: { type: string }
        - in: query; name: method_id; schema: { type: string }
        - in: query; name: version; schema: { type: string }
        - in: query; name: decision; schema: { type: string, enum: [ALLOW, DENY] }
        - in: query; name: acl_tag; schema: { type: string }
        - in: query; name: from; schema: { type: string, format: date-time }
        - in: query; name: to; schema: { type: string, format: date-time }
        - in: query; name: limit; schema: { type: integer, default: 100, maximum: 1000 }
        - in: query; name: cursor; schema: { type: string }
      responses:
        '200':
          description: Audit log page
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items: { $ref: '#/components/schemas/AuditLog' }
                  next_cursor:
                    type: string
  /audit/logs/{decision_id}:
    get:
      summary: Get a single audit log entry
      parameters:
        - in: path
          name: decision_id
          required: true
          schema: { type: string }
      responses:
        '200':
          description: The audit record
          content:
            application/json:
              schema: { $ref: '#/components/schemas/AuditLog' }

components:
  schemas:
    AuditLog:
      type: object
      properties:
        timestamp: { type: string, format: date-time }
        decision_id: { type: string }
        tenant_id: { type: string }
        user_id: { type: string }
        role: { type: string }
        method_id: { type: string }
        version: { type: string }
        request:
          type: object
          properties:
            path: { type: string }
            method: { type: string }
            ip: { type: string }
        request_context:
          type: object
          properties:
            region: { type: string }
            datasets:
              type: array
              items: { type: string }
            input_hash: { type: string }
        acl_evaluation:
          type: object
          additionalProperties:
            type: string
            enum: [ALLOW, DENY]
        outcome: { type: string, enum: [ALLOW, DENY] }
        provenance_id: { type: string }
        region: { type: string }
        latency_ms: { type: integer }
        links:
          type: object
          properties:
            execution: { type: string }

Security & Access

  • Roles allowed:

    • auditor, tenant_admin, regulator_view: read access.
    • compute_client: only own-tenant logs (enforced by tenancy scope).

  • Headers:

    • X-Tenant-ID, X-User-Role (or JWT claims) required for scoping.

  • PII:

    • IP/identifiers configurable; default redact or minimize for non-admin roles.

2.6. Index & Retention (DB)​

  • Indexes:

    • (tenant_id, timestamp DESC)
    • (decision_id) unique
    • (method_id, version, timestamp DESC)
    • GIN on acl_evaluation JSON if tag filtering is heavy

  • Retention:

    • Hot (90 days) online; warm (12–24 months) in object storage.
    • Export signing + hash chains for tamper-evidence.

2.6.1. Loader & Runtime Enforcement (Code Recipes)**​

**Minimal loader changes (pseudocode)

load_methods.pyGitHub ↗
def load_methods(db):
    specs = {}
    rows = db.query("""
        SELECT * FROM compute_method_registry
        WHERE status <> 'deprecated'
    """)
    for r in rows:
        key = (r["method_id"], r["version"])
        specs[key] = compile_spec_and_fn(r)  # imports impl, compiles JSON Schemas
    return specs

def execute(method_id, version, inputs, options, ctx):
    spec = METHODS[(method_id, version)]           # exact version lookup
    validate_inputs(spec, inputs, options)
    enforce_acl_and_datasets(spec, ctx)
    out = spec.fn(inputs, options, ctx)
    validate_output(spec, out)
    audit(spec, inputs, out, ctx)
    return out

2.6.2. Admin Flows (SQL Playbooks)​

Register new version

compute_method_registry-insert.sqlGitHub ↗
INSERT INTO compute_method_registry (method_id, version, status, description,
  inputs_schema_json, options_schema_json, output_schema_json,
  implementation_ref, dataset_requirements, acl_tags)
VALUES
('GHG.intensity','1.1.0','beta','Improved handling of Scope 3 categories',
 :inputs_schema, :options_schema, :output_schema,
 'python://zayaz.compute.ghg:intensity_v110', '["IPCC-EFDB"]', '["EU_ONLY"]');

Promote to “latest”

compute_method_registry-update.sqlGitHub ↗
UPDATE compute_method_registry
SET status='supported', updated_at=now()
WHERE method_id='GHG.intensity' AND version='1.1.0';

INSERT INTO compute_method_latest (method_id, version)
VALUES ('GHG.intensity','1.1.0')
ON CONFLICT (method_id) DO UPDATE SET version=EXCLUDED.version;

Deprecate old

compute_method_deprecate-old.sqlGitHub ↗
UPDATE compute_method_registry
SET status='deprecated', updated_at=now()
WHERE method_id='GHG.intensity' AND version='1.0.0';

OpenAPI excerpt (2)

Here’s a short OpenAPI excerpt showing how to expose both GET /compute/methods and POST /compute/factor, with the requirement that execution is deterministic only when the (method_id, version) pair is provided.

openai-excerpt-2.yamlGitHub ↗
openapi: 3.0.3
info:
  title: ZAYAZ Compute API
  version: 1.0.0

paths:
  /compute/methods:
    get:
      summary: List registered compute methods
      description: >
        Returns all registered compute methods. Clients must select both
        `method_id` and `version` to guarantee deterministic execution.
      responses:
        '200':
          description: List of methods
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    method_id:
                      type: string
                      example: "GHG.intensity"
                    version:
                      type: string
                      example: "1.0.0"
                    status:
                      type: string
                      enum: [supported, beta, deprecated]
                    description:
                      type: string
                      example: "GHG emissions per € revenue"
                    x-internal-tags:
                      type: object
                      properties:
                        acl_tags:
                          type: array
                          items:
                            type: string
                          example: ["EU_ONLY", "NO_PHI"]
                        dataset_requirements:
                          type: array
                          items:
                            type: string
                          example: ["IPCC-EFDB", "IEA_SSP"]

  /compute/factor:
    post:
      summary: Execute a compute method
      description: >
        Executes a registered compute method with inputs.  
        Both `method_id` and `version` are **required** for deterministic results.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - method_id
                - version
                - inputs
              properties:
                method_id:
                  type: string
                  example: "GHG.intensity"
                version:
                  type: string
                  example: "1.0.0"
                inputs:
                  type: object
                  additionalProperties: true
                  example:
                    scope1: 100
                    scope2: 200
                    revenue: 50
                dataset_ref:
                  type: string
                  example: "IPCC-EFDB.xlsx"
      responses:
        '200':
          description: Compute result
          content:
            application/json:
              schema:
                type: object
                properties:
                  result:
                    type: number
                    example: 6.0
                  unit:
                    type: string
                    example: "tCO2e/€"
                  provenance:
                    type: string
                    example: "IPCC-EFDB v2023"
                  x-internal-tags:
                    type: object
                    properties:
                      acl_tags:
                        type: array
                        items:
                          type: string
                        example: ["EU_ONLY"]
                      dataset_requirements:
                        type: array
                        items:
                          type: string
                        example: ["IPCC-EFDB"]

2.6.3. Eval/Gate API Contract​

Request:

eval-gate-request.jsonGitHub ↗
POST /eval/gate
{
  "response_id": "resp-99c2a",
  "tests": ["citation", "numeric", "refusal"]
}

Response:

eval-gate-response.jsonGitHub ↗
{
  "status": "pass",
  "results": {
    "citation": true,
    "numeric": true,
    "refusal": true
  },
  "provenance_id": "gate-5541f"
}

2.6.4. Governance​

  • Schema Registry → All API schemas versioned in registry (JSON Schema + OpenAPI).
  • Immutable IDs → Every response includes provenance_id for audit.
  • Backward Compatibility → Old schema versions supported for 12 months.
  • Audit Trail → API logs exportable for assurance providers.


GitHub RepoRequest for Change (RFC)