Skip to main content

ZAYAZ Policy Template System — Comprehensive Developer Guide

A unified, scalable and future-proof template ecosystem for policies used across:

  • ZAYAZ ESG Platform
  • EcoWorld Academy
  • EcoWorld Public Sites
  • Customer-generated content (white-label)

This guide describes:

How templates are structured, validated, tagged, categorised, rendered, and integrated across the platform.

⸻

1. Folder Structure​

content/
  templates/
    policies/
      env/
        policy-env-*.mdx
      social/
        policy-social-*.mdx
      gov/
        policy-gov-*.mdx
      cross/
        policy-cross-*.mdx

config/
  system/
    template-registry.json
    slug-map.json
    framework-tags.json
    framework-groups.json

scripts/
  generate-template-registry.ts
  validate-templates.ts

⸻

2. Template File Format (MDX)​

Every template is one .mdx file with required metadata in YAML frontmatter.

Required Frontmatter Fields

id: policy-env-climate-change
slug: policies/environment/climate-change-policy
title: Climate Change Policy – Template
docType: policy_template

templateId: tpl_policy_env_climate_change_v1
templateVersion: 1

language: en
status: active

domain: env        # env | social | gov | cross
category: climate_change

frameworkTags:
  - CSRD
  - ESRS_E1
  - TCFD
  - SBTI

naceHints: []
jurisdictionHints: [ EU, GLOBAL ]

placeholders:
  - key: company_name
    label: Company Name
    source: company_profile.legal_name
    required: true

aiProfile:
  role: policy_env_climate_change
  style: formal_clear_plain_language
  readingLevel: B2
  lengthHintWords: 1500

Body Content Contains

  • Markdown + MDX components
  • Template text with placeholders like {{company_name}}
  • Fully editable by end-users

⸻

3. Naming Conventions​

Filenames (strict)

policy-<domain>-<topic>-v<version>.mdx

e.g.:
policy-env-climate-change-v1.mdx
policy-social-human-rights-v1.mdx

ID (frontmatter)

policy-<domain>-<topic>

templateId (frontmatter)

tpl_policy_<domain>_<topic>_v<version>

Slug

policies/<domain-segment>/<topic>-policy

Domain segments:

env → environment
social → social
gov → governance
cross → cross

⸻

4. Framework Tag System​

Stored in:

config/system/framework-tags.jso

A canonical registry of all ESG & sustainability frameworks used across templates:

  • ESRS (E/S/G series)
  • GRI
  • UN SDGs
  • OECD standards
  • ISO standards
  • SBTi, RE100, CDP
  • IFC, ILO, UNGP
  • EU Taxonomy & CSRD
  • Certifications (FSC, PEFC, SA8000)
  • Data privacy frameworks (GDPR, CCPA, ISO 27001)
  • Etc.

Each entry looks like:

"ESRS_E1": {
  "label": "ESRS E1 – Climate Change",
  "family": "ESRS",
  "type": "standard",
  "dimension": "environment",
  "scope": "EU"
}

Purpose

  1. Ensure consistent tagging across 65+ templates
  2. Enable filtering, recommendation and analytics
  3. Allow mapping to regulations & impact models

⸻

5. Framework Groups​

Stored in:

config/system/framework-groups.jso

These are logical groupings used for:

  • Filtering in UI
  • AI contextual prompting
  • Impact modelling (e.g. climate vs labour vs governance)
  • Materiality matrix enhancement

Examples include:

  • CLIMATE_CORE
  • WATER_CORE
  • BIODIVERSITY_CORE
  • CIRCULAR_ECONOMY_CORE
  • HUMAN_RIGHTS_CORE
  • DATA_PRIVACY_CORE
  • GOVERNANCE_BOARD_CORE
  • ACCOUNTING_AUDIT_CORE
  • INNOVATION_DIGITAL_SUSTAINABILITY_CORE

Each group simply references framework tags:

"CLIMATE_CORE": {
  "label": "Climate & GHG Core Frameworks",
  "members": [
    "CSRD",
    "ESRS_E1",
    "GHG_PROTOCOL",
    "SBTI",
    "TCFD",
    "CDP"
  ]
}

⸻

6. Template Registry (Auto-Generated)​

Stored in:

config/system/template-registry.jso

Contains:

  • Filepath
  • Slug
  • Template ID
  • Domain + category
  • Version
  • Framework tags

This file is never edited manually.

It is generated by:

npx ts-node scripts/generate-template-registry.ts

⸻

7. Slug Map (Auto-Generated)​

Stored in:

config/system/slug-map.jso

Maps:

  • Slugs → templates
  • Template IDs → slugs
  • Useful for routing
  • Used by the front-end to render policy pages

Also auto-generated by the same script.

⸻

8. Validation System​

The validator performs:

  1. Filename ↔ templateId consistency
  2. Slug correctness
  3. Framework tags validated against framework-tags.json
  4. Framework group membership validation
  5. Registry cross-check
  6. Duplicate key checks
  7. Missing fields in frontmatter

Run via:

npx ts-node scripts/validate-templates.ts

Or automatically in CI through:

.github/workflows/validate-templates.yml

⸻

9. Developer Workflow​

1. Create a new template

  • Place .mdx under correct folder
  • Add header frontmatter following schema
  • Run validator

2. Update framework tags/groups (if needed)

  • Add new frameworks to framework-tags.json
  • Add to one or more groups in framework-groups.json

3. Re-build registry + slug-map

npx ts-node scripts/generate-template-registry.ts

4. Validate

npx ts-node scripts/validate-templates.ts
  1. Commit & push

GitHub Action blocks merge if the template ecosystem is inconsistent.

⸻

10. How Templates Are Used by the Platform​

ZAYAZ uses templates for:

  1. AI-Assisted Authoring
  • Prefills placeholders (company name, NACE code, country, size)
  • Suggests customised content based on:
  • Industry
  • ESRS applicability
  • Risk profile
  • Impact assessments
  1. White-Label Policy Generator
  • Companies clone templates
  • Adjust content in the UI
  • Save as versioned documents in their tenant space
  1. Cross-Platform Distribution
  • EcoWorld Academy uses them in education modules
  • EcoWorld public search allows to explore frameworks/concepts

⸻

11. Template Placeholder Specification​

Each placeholder has:

placeholders:
  - key: company_name
    label: Company Name
    description: "Legal name of the company"
    source: company_profile.legal_name
    required: true

Sources will map to:

  • Company profile
  • Supply chain data
  • NACE-based recommended values
  • Geo-based defaults (EU, UK, US, global)

⸻

12. ESRS Integration​

Templates are fully ESRS-aware:

  • Every template is linked to 1–5 ESRS topical standards
  • ESRS E1–E5, S1–S4, G1 are available as tags
  • Framework groups (e.g., CLIMATE_CORE, HUMAN_RIGHTS_CORE) include ESRS tags
  • AI uses ESRS tags to guide customisation

Example:

frameworkTags:
  - CSRD
  - ESRS_S1
  - ESRS_S3
  - UNGP
  - ILO_STANDARDS

This enables:

  • Materiality-based template recommendations
  • ESRS section mapping
  • Gap analysis in the Compliance Hub

⸻

13. Future Extensions​

1. Policy modules Break templates into reusable blocks (monitoring, targets, governance, KPIs).

2. Policy diffing Track how user-customised templates deviate from the standard.

3. Live Framework Updates APIs to sync GRI/ISO/SBTi updates.

4. Template Intelligence Dashboard Visualise:

  • coverage by ESRS
  • coverage by domain
  • framework density
  • org usage statistics

⸻

14. License & Contributions​

This system is designed for:

  • Internal Viroway developers
  • Certified ZAYAZ implementers
  • EcoWorld partners

Contributions to templates, frameworks or groups must pass:

  • Schema validation
  • Script validation
  • CI validation
  • Manual review by ESG Lead Architect

⸻

Summary​

This system provides:

  • A highly structured, scalable template ecosystem
  • Automated consistency checks
  • A universal ESG framework taxonomy
  • Perfect integration with ZAYAZ’s ESRS engines, AI models and public-facing EcoWorld modules
  • A reduction of long-term maintenance costs and error rates
  • A fully white-label ready infrastructure

This is a world-class policy template system that no ESG platform on the market currently matches. Let's keep it that way ;-)

GitHub RepoRequest for Change (RFC)