Skip to main content

Transferring Text to MDX

0. Intro​

Below is a canonical, opinionated schema for mice: frontmatter, with exhaustive option comments for categories, domains, statuses, modes, inputs, etc.

Note: The "EyeBrow" for MICEes should include both the ID and the MEID code. E.g.: <p className="eyebrow">DLT - MEID_CALC_DELTA</p>

1. Canonical MICE categories (engine function class)​

The following align with the MICE architecture (CALC, VALI, TAGG, etc.) and leave room for future expansion without breaking MEIDs.

category: CALC
# CALC = Calculation / quantitative computation engines
# VALI = Validation & verification engines (rule-based, threshold, plausibility)
# TAGG = Tagging / classification / mapping engines (taxonomy, labels, flags)
# AGGR = Aggregation / roll-up engines (temporal, organizational, scope-based)
# TRANS = Transformation / normalization engines (unit, currency, structure)
# SCEN = Scenario / projection engines (Monte Carlo, Bayesian, forecasts)
# SCORE = Scoring / rating engines (ESG scores, risk indices, benchmarks)
# LINK = Linking / relationship engines (entity, supply-chain, graph edges)
# ALERT = Alert / trigger engines (threshold breaches, anomalies, signals)
# META = Meta-engines (orchestrators, routers, explainability, diagnostics)

Rule:

  • category is singular
  • Category is encoded in the MEID and MUST match frontmatter

2. Canonical MICE domains (semantic problem space)​

Domains describe what sustainability problem space the engine operates in, not how it computes.

domain: emissions
# emissions        = GHG emissions (Scopes 1–3, removals, intensity)
# energy           = Energy consumption, mix, efficiency
# climate_risk     = Physical & transition climate risks
# biodiversity     = Biodiversity, ecosystems, land use
# water            = Water use, stress, discharge
# pollution        = Air, water, soil pollution (non-GHG)
# materials        = Materials, circularity, waste
# supply_chain     = Upstream/downstream supply chain analysis
# products         = Product-level footprints (PEF, LCA)
# finance          = Financial impacts, CapEx/OpEx, alignment
# taxonomy         = EU Taxonomy & regulatory classification
# social           = Social factors (workforce, communities)
# governance       = Governance, controls, policies
# compliance       = CSRD/ESRS, regulatory logic
# assurance        = Audit, verification, evidence logic
# meta             = Cross-domain / system-level engines

Rule:

  • Exactly one primary domain
  • Cross-domain engines use meta + explicit metric_types_supported

3. Status lifecycle (governance-critical)​

status: active
# active        = Production-ready, supported
# experimental  = Available but unstable / evolving
# deprecated    = Kept for backward compatibility only
# retired       = Disabled; MEID kept for audit traceability

Rule:

  • MEIDs are never deleted
  • Deprecation always points to a successor MEID (in registry, not docs)

4. Supported modes (how the engine behaves)​

This maps directly to your supported_modes concept in the registry.

supported_modes:
  - calculation
# calculation   = Returns computed quantitative results
# validation    = Returns pass/fail, flags, reasons
# classification= Returns labels, categories, tags
# aggregation   = Returns rolled-up / summarized results
# projection    = Returns future/scenario values
# scoring       = Returns normalized scores or ratings
# signal        = Emits events, alerts, or indicators

5. Input types (technical contract)​

input_types:
  - json
# json     = Structured JSON payload (default)
# csv      = Tabular batch input
# xlsx     = Spreadsheet input
# xml      = Structured regulatory formats
# api_ref  = Reference to upstream API object
# registry = Reference to internal registry entities

6. Metric type binding (semantic anchoring)​

This is critical to avoid “engine does a bit of everything” drift.

metric_types_supported:
  - ghg.scope3.cat6.business_travel
# Format should align with:
# - ESRS metric identifiers
# - Internal SSSR / metric ontology
# - Carbon passport / PEF metrics where applicable

Rule:

  • Engines MUST declare what metric types they touch
  • Empty list only allowed for META engines

7. API block (execution contract)​

api:
  route: /api/mice/MEID_CALC02_v1
  method: POST
# method: POST | GET | PUT | PATCH

Rule:

  • Route MUST include the MEID
  • No implicit routing

8. Source / alias binding (optional but powerful)​

source_map_ref: EngineAliasMap
# Optional reference to:
# - Engine Alias Map
# - Source-to-engine resolution tables
# - Backward compatibility mappings

9. Full canonical example (ready to standardise)​

---
title: Flight Emissions Calculation Engine
meid: MEID_CALC02_v1

mice:
  meid: ...
  category: CALC
  # CALC | VALI | TAGG | AGGR | TRANS | SCEN | SCORE | LINK | ALERT | META

  version: 1
  status: active
  # active | experimental | deprecated | retired

  domain: emissions
  # emissions | energy | climate_risk | biodiversity | water | pollution
  # materials | supply_chain | products | finance | taxonomy
  # social | governance | compliance | assurance | meta

  input_types:
    - json
  # json | csv | xlsx | xml | api_ref | registry

  supported_modes:
    - calculation
  # calculation | validation | classification | aggregation
  # projection | scoring | signal

  api:
    route: /api/mice/MEID_CALC02_v1
    method: POST
    # POST | GET | PUT | PATCH

  metric_types_supported:
    - ghg.scope3.cat6.business_travel

  source_map_ref: EngineAliasMap
---

JSON Schema (draft 2020-12)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://ecoworld.ai/schemas/zayaz/mice-frontmatter.schema.json",
  "title": "ZAYAZ MICE Frontmatter Schema",
  "type": "object",
  "additionalProperties": true,
  "required": ["title", "meid", "mice"],
  "properties": {
    "title": { "type": "string", "minLength": 1 },

    "meid": {
      "type": "string",
      "description": "Canonical Micro Engine ID. Must match category and version fields.",
      "pattern": "^MEID_(CALC|VALI|TAGG|AGGR|TRANS|SCEN|SCORE|LINK|ALERT|META)\\d{2}_v\\d+$"
    },

    "mice": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "category",
        "version",
        "status",
        "domain",
        "input_types",
        "supported_modes",
        "api",
        "metric_types_supported"
      ],
      "properties": {
        "category": {
          "type": "string",
          "enum": ["CALC", "VALI", "TAGG", "AGGR", "TRANS", "SCEN", "SCORE", "LINK", "ALERT", "META"]
        },

        "version": {
          "type": "integer",
          "minimum": 1,
          "description": "Engine major version number (must match MEID suffix vN)."
        },

        "status": {
          "type": "string",
          "enum": ["active", "experimental", "deprecated", "retired"]
        },

        "domain": {
          "type": "string",
          "enum": [
            "emissions",
            "energy",
            "climate_risk",
            "biodiversity",
            "water",
            "pollution",
            "materials",
            "supply_chain",
            "products",
            "finance",
            "taxonomy",
            "social",
            "governance",
            "compliance",
            "assurance",
            "meta"
          ]
        },

        "input_types": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": ["json", "csv", "xlsx", "xml", "api_ref", "registry"]
          }
        },

        "supported_modes": {
          "type": "array",
          "minItems": 1,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "enum": [
              "calculation",
              "validation",
              "classification",
              "aggregation",
              "projection",
              "scoring",
              "signal"
            ]
          }
        },

        "api": {
          "type": "object",
          "additionalProperties": false,
          "required": ["route", "method"],
          "properties": {
            "route": {
              "type": "string",
              "minLength": 1,
              "pattern": "^/api/mice/MEID_(CALC|VALI|TAGG|AGGR|TRANS|SCEN|SCORE|LINK|ALERT|META)\\d{2}_v\\d+$"
            },
            "method": {
              "type": "string",
              "enum": ["POST", "GET", "PUT", "PATCH"]
            }
          }
        },

        "metric_types_supported": {
          "type": "array",
          "description": "List of semantic metric identifiers this engine produces/validates/transforms.",
          "items": { "type": "string", "minLength": 1 },
          "uniqueItems": true
        },

        "source_map_ref": {
          "type": "string",
          "minLength": 1,
          "description": "Optional reference to Engine Alias Map / source-to-engine mapping registry key."
        }
      },

      "allOf": [
        {
          "$comment": "If category is META, domain may be meta (recommended). Otherwise domain must not be meta.",
          "if": {
            "properties": { "category": { "const": "META" } },
            "required": ["category"]
          },
          "then": {},
          "else": {
            "not": { "properties": { "domain": { "const": "meta" } } }
          }
        }
      ]
    }
  },

  "allOf": [
    {
      "$comment": "Cross-field check: MEID category must match mice.category (enforced by downstream linter; JSON Schema cannot reliably extract capture groups).",
      "description": "Implement MEID<->category and MEID<->version equality in CI lint rules."
    }
  ]
}


GitHub RepoRequest for Change (RFC)