ESG Data Taxonomy Mapper & Normalizer
Map between ESG frameworks, normalize metrics, and identify material issues by sector. The foundational plumbing every ESG tool needs.
ESG data is chaos. Every source uses different frameworks:
- GRI (Global Reporting Initiative)
- SASB (industry-specific metrics)
- TCFD (climate-focused)
- CDP (Carbon Disclosure Project)
- CSRD/ESRS (new EU standards)
- SFDR (EU fund disclosures)
You literally can't compare Company A's "Scope 1 emissions" (reported under GRI 305-1) to Company B's "Direct GHG emissions" (reported under ESRS E1-4) without manual mapping.
esg-taxonomy provides:
- Unified Taxonomy - A normalized ESG category structure that maps all frameworks
- Framework Mappings - Cross-walk between GRI, SASB, TCFD, CDP, CSRD/ESRS, SFDR
- Data Normalizer - Convert raw ESG data to unified format with proper units
- Materiality Matrix - Identify which ESG issues matter for which industries
- Unit Converter - Handle the mess of tCO2e, MWh, ML, GJ, etc.
npm install esg-taxonomyconst {
ESGTaxonomy,
FrameworkMapper,
ESGNormalizer,
MaterialityMatrix
} = require('esg-taxonomy');
// 1. Map between frameworks
const mapper = new FrameworkMapper();
// Find equivalent metrics across frameworks
const equivalents = mapper.findEquivalents('GRI', 'GRI 305-1');
console.log(equivalents);
// {
// source: { framework: 'GRI', metricId: 'GRI 305-1', name: 'Direct (Scope 1) GHG emissions' },
// equivalents: [
// { framework: 'CSRD', metricId: 'ESRS-E1-4', name: 'Gross Scope 1 GHG emissions' },
// { framework: 'CDP', metricId: 'CDP-C6.1', name: 'Scope 1 emissions' },
// { framework: 'TCFD', metricId: 'TCFD-SCOPE1', name: 'Scope 1 GHG emissions' }
// ]
// }
// 2. Normalize data from any source
const normalizer = new ESGNormalizer();
const normalized = normalizer.normalizeDataPoint({
name: 'Total greenhouse gas emissions',
value: 125000,
unit: 'tCO2e',
sourceFramework: 'GRI',
sourceMetricId: 'GRI 305-1',
company: 'Acme Corp',
period: 'FY2024'
});
console.log(normalized);
// {
// taxonomyId: 'E.CC.GHG',
// taxonomyPath: ['Environmental', 'Climate Change', 'GHG Emissions'],
// pillar: 'E',
// value: 125000,
// unit: 'tCO2e',
// confidence: 1.0,
// ...
// }
// 3. Check materiality for an industry
const materiality = MaterialityMatrix.forSector('FN-AC'); // Asset Management
console.log(materiality.issues);
// {
// 'E.CC.RISK': { level: 'HIGH', note: 'Climate risk in investments' },
// 'G.RM.ESG': { level: 'HIGH', note: 'ESG integration in investment' },
// ...
// }A hierarchical classification for all ESG issues:
E (Environmental)
├── E.CC (Climate Change)
│ ├── E.CC.GHG (GHG Emissions)
│ ├── E.CC.ENERGY (Energy Use)
│ ├── E.CC.RISK (Climate Risk)
│ └── E.CC.TRANS (Transition Risk)
├── E.NR (Natural Resources)
│ ├── E.NR.WATER (Water)
│ ├── E.NR.BIO (Biodiversity)
│ └── E.NR.LAND (Land Use)
└── E.POL (Pollution & Waste)
├── E.POL.AIR (Air Quality)
├── E.POL.WASTE (Waste)
└── E.POL.HAZ (Hazardous Materials)
S (Social)
├── S.WF (Workforce)
│ ├── S.WF.HS (Health & Safety)
│ ├── S.WF.DIV (Diversity)
│ └── S.WF.TRAIN (Training)
├── S.HR (Human Rights)
├── S.COM (Communities)
└── S.CUST (Customers)
G (Governance)
├── G.CG (Corporate Governance)
├── G.BE (Business Ethics)
├── G.RM (Risk Management)
└── G.TR (Transparency)
Every framework metric is mapped to the unified taxonomy:
const { frameworks } = require('esg-taxonomy');
// GRI 305-1 → E.CC.GHG
console.log(frameworks.GRI.metrics['GRI 305-1'].taxonomyId);
// ESRS E1-4 → E.CC.GHG
console.log(frameworks.CSRD.metrics['ESRS-E1-4'].taxonomyId);
// Same taxonomy ID = equivalent metricsNormalize raw ESG data regardless of source:
const normalizer = new ESGNormalizer();
// Normalize company-wide ESG data
const result = normalizer.normalizeCompanyData({
company: 'Acme Corp',
period: 'FY2024',
sourceFramework: 'GRI',
metrics: {
'GRI 305-1': { value: 125000, unit: 'tCO2e' },
'GRI 305-2': { value: 50000, unit: 'tCO2e' },
'GRI 302-1': { value: 500000, unit: 'GJ' },
'GRI 403-9': { value: 2.5, unit: 'rate' }
}
});
// Get normalized profile
const profile = normalizer.createProfile(result);
console.log(profile.keyMetrics);
// { scope1Emissions: 125000, scope2Emissions: 50000, ... }Identify financially material ESG issues by industry (based on SASB):
const { MaterialityMatrix } = require('esg-taxonomy');
const matrix = new MaterialityMatrix();
// Get material issues for Asset Management
const issues = matrix.getMaterialIssues('FN-AC');
// [
// { taxonomyId: 'G.RM.ESG', level: 'HIGH', note: 'ESG integration' },
// { taxonomyId: 'E.CC.RISK', level: 'HIGH', note: 'Climate risk' },
// ...
// ]
// Check if an issue is material
matrix.isMaterial('FN-AC', 'E.CC.GHG', 'MEDIUM'); // true
// Find all industries where an issue is material
matrix.getIndustriesForIssue('E.CC.GHG', 'HIGH');
// [{ industryCode: 'EM-EP', industry: 'Oil & Gas', ... }, ...]Handle the mess of ESG units:
const { UnitConverter } = require('esg-taxonomy');
const converter = new UnitConverter();
// Convert energy units
converter.convert(500000, 'GJ', 'MWh');
// { value: 138890, converted: true, ... }
// Convert emissions units
converter.convert(125, 'MtCO2e', 'tCO2e');
// { value: 125000000, converted: true, ... }
// Convert water units
converter.convert(50, 'ML', 'm³');
// { value: 50000, converted: true, ... }- 300 series: Environmental
- 400 series: Social
- 200 series: Economic
- Full metric mapping with taxonomy IDs
- 77 industry standards
- General issue categories mapped
- Sample metrics for key industries
- Four pillars: Governance, Strategy, Risk Management, Metrics
- Climate risk categories (transition, physical)
- Cross-industry metrics
- Climate Change questionnaire
- Water Security questionnaire
- Forests questionnaire
- Scope 3 categories
- All ESRS standards (E1-E5, S1-S4, G1)
- Mandatory metrics flagged
- Double materiality support
- Principal Adverse Impact (PAI) indicators
- Article 6/8/9 classifications
- EU Taxonomy alignment metrics
// Ingest data from multiple sources
const griData = parseGRIReport(companyReport);
const cdpData = parseCDPResponse(cdpSubmission);
// Normalize all data to unified format
const normalizer = new ESGNormalizer();
const normalizedGRI = normalizer.normalizeCompanyData({ ...griData, sourceFramework: 'GRI' });
const normalizedCDP = normalizer.normalizeCompanyData({ ...cdpData, sourceFramework: 'CDP' });
// Now data is comparable regardless of source// Check materiality for each holding
const matrix = new MaterialityMatrix();
for (const holding of portfolio) {
const materialIssues = matrix.getMaterialIssues(holding.sasbIndustry);
// Focus analysis on material issues
}const { ValidationUtils } = require('esg-taxonomy');
// Validate emissions data
ValidationUtils.validateEmissions(scope1Value);
ValidationUtils.validateScopeConsistency(scope1, scope2, scope3, total);
ValidationUtils.checkDataQuality(esgData);getPillar(categoryId)- Get pillar (E/S/G) for a categorygetCategory(categoryId)- Get category detailsgetSubcategory(subcategoryId)- Get subcategory detailsclassify(metricName)- Auto-classify a metric name to taxonomysearch(keyword)- Search taxonomy by keyword
findEquivalents(sourceFramework, sourceMetricId)- Find equivalent metricsmapMetric(value, sourceFramework, sourceMetricId, targetFramework)- Map a valuemapData(data, sourceFramework, targetFramework)- Map entire datasetsuggestMetric(dataName, value)- Suggest framework metric for raw data
normalizeDataPoint(dataPoint)- Normalize single data pointnormalizeBatch(dataPoints)- Normalize multiple data pointsnormalizeCompanyData(companyData)- Normalize full company ESG datacreateProfile(normalizedData)- Create structured ESG profile
forIndustry(industryCode)- Get materiality for an industrygetMaterialIssues(industryCode, options)- Get material issues (HIGH/MEDIUM)isMaterial(industryCode, taxonomyId, level)- Check if issue is materialgetIndustriesForIssue(taxonomyId, level)- Find industries for an issue
convert(value, fromUnit, toUnit)- Convert between unitstoBase(value, unit)- Convert to base unitgetCompatibleUnits(unit)- Get all compatible unitsareCompatible(unit1, unit2)- Check if units can be converted
Contributions welcome! Areas that need work:
- More complete SASB industry mappings
- Additional framework support (ISSB, TNFD)
- More comprehensive unit conversions
- Industry keyword classifiers
MIT License - see LICENSE for details.
Built with insights from:
- SASB Materiality Map
- GRI Standards
- TCFD Recommendations
- EU CSRD/ESRS Technical Standards
- CDP Disclosure Framework