@lsbjordao/iucn-red-list-criteria-validator.js

TypeScript validator and normalization engine for IUCN Red List criteria payloads.

The package validates criteria declarations against the evidence provided in the input and also performs criteria reconciliation:

• what was declared
• what is supported by the data
• what is missing
• what is unsupported
• what the normalized canonical clause set looks like

It returns both machine-friendly JSON and a console-friendly colored report.

Features

• Validation for criteria A, B, C, D, and E
• Multilanguage output via lang
• Structured JSON output for apps and pipelines
• Criteria inference and normalization
• Reconciliation fields for QA and bulk review
• Colored terminal report via consoleReport
• Example scenarios in src/test/check.ts

Installation

npm install @lsbjordao/iucn-red-list-criteria-validator.js

Basic Usage

import { IUCN_Red_List_Criteria_Validator, CheckInput } from '@lsbjordao/iucn-red-list-criteria-validator.js';

const validator = new IUCN_Red_List_Criteria_Validator();

const input = new CheckInput('EN');
input.taxon = 'Mimosa_validata';
input.lang = 'en';
input.eoo = 3200;
input.aoo = 120;
input.nLocations = 3;
input.continuingDecline = true;

const result = validator.check(input);

console.log(result.valid);
console.log(result.message);
console.log(result.suggestedCriteriaClauses);
console.log(result.normalizedCriteriaClauses);
console.log(result.consoleReport);

Example Inference

Input:

const input = new CheckInput('EN');
input.eoo = 3200;
input.aoo = 120;
input.nLocations = 3;
input.continuingDecline = true;

Typical inferred output:

{
  "suggestedCriteriaClauses": [
    "B1a",
    "B1b(ii)",
    "B2a",
    "B2b(ii)"
  ]
}

Input Class

CheckInput is an instantiable class. The constructor requires category:

class CheckInput {
  taxon?: string;
  lang?: 'en' | 'pt' | 'es';
  inferCriteria?: boolean;
  category: 'CR' | 'EN' | 'VU' | 'NT' | 'LC' | 'DD' | 'NE';
  criteriaClauses?: Criteria[];
  notes?: string;

  reductionPercent?: number;

  eoo?: number;
  aoo?: number;
  nLocations?: number;
  severe_fragmentation?: boolean;
  continuingDecline?: boolean;
  extremeFluctuations?: boolean;
  conditionMatrix?: {
    a?: {
      severe_fragmentation?: boolean;
      nLocations?: number;
    };
    b?: {
      i?: boolean;
      ii?: boolean;
      iii?: boolean;
      iv?: boolean;
      v?: boolean;
    };
    c?: {
      i?: boolean;
      ii?: boolean;
      iii?: boolean;
      iv?: boolean;
    };
  };

  matureIndividuals?: number;
  c1DeclinePercent?: number;
  maxIndividualsPerSubpop?: number;
  pctMatureInLargestSubpop?: number;

  plausibleThreat?: boolean;
  extinctionProbabilityPercent?: number;

  constructor(category: Category) { ... }
}

Output Shape

type CheckResult = {
  valid: boolean;
  lang: 'en' | 'pt' | 'es';
  taxon: string;
  category: string;

  criteriaClauses: string[];
  declaredCriteriaClauses: string[];
  inferredCriteriaClauses: string[];
  normalizedCriteriaClauses: string[];
  missingCriteriaClauses: string[];
  unsupportedCriteriaClauses: string[];
  undeclaredButSupportedCriteriaClauses: string[];
  suggestedCriteriaClauses: string[];

  criteria: Array<'A' | 'B' | 'C' | 'D' | 'E'> | null;

  message: string;
  summary: string[];
  warnings: string[];
  issues: string[];

  consoleReport: string;

  data: {
    category: string;
    criteriaClauses?: string[];
    notes?: string;
    reductionPercent?: number;
    eoo?: number;
    aoo?: number;
    nLocations?: number;
    severe_fragmentation?: boolean;
    continuingDecline?: boolean;
    extremeFluctuations?: boolean;
    conditionMatrix?: object;
    matureIndividuals?: number;
    c1DeclinePercent?: number;
    maxIndividualsPerSubpop?: number;
    pctMatureInLargestSubpop?: number;
    plausibleThreat?: boolean;
    extinctionProbabilityPercent?: number;
  };
};

Reconciliation Semantics

This package separates validation from reconciliation.

declaredCriteriaClauses

The clauses explicitly passed by the user in criteriaClauses.

inferredCriteriaClauses

The clauses the engine considers supported by the input data.

This is the supported set derived from the evidence, not merely a copy of what the user declared.

normalizedCriteriaClauses

The reconciled canonical set of criteria clauses supported by the data after comparing declaration and evidence.

In the current implementation, this is effectively the supported canonical set produced by inference.

missingCriteriaClauses

Clauses that are supported by the data but absent from the user declaration.

This field is oriented to the difference between the declared set and the normalized set.

unsupportedCriteriaClauses

Clauses declared by the user but not supported by the data.

undeclaredButSupportedCriteriaClauses

Semantic alias for missingCriteriaClauses.

This field currently coexists because it is often easier to interpret in QA pipelines and spreadsheets, even though it can be derived from the other sets.

In practice, missingCriteriaClauses and undeclaredButSupportedCriteriaClauses may often contain the same values.

The intended distinction is:

• missingCriteriaClauses focuses on declared-vs-normalized difference
• undeclaredButSupportedCriteriaClauses focuses on evidence-supported clauses that were never explicitly declared

suggestedCriteriaClauses

The subset of supported clauses that are missing from the declaration.

This field is intentionally non-redundant. If the input already declares every supported clause, suggestedCriteriaClauses will be empty.

Validation vs Inference vs Normalization

The current engine supports three conceptually distinct operations:

• validation Checks whether the declared combination is coherent with the evidence.
• inference Reconstructs which clauses are supported by the evidence, even if not declared.
• normalization Produces the reconciled canonical clause set.

This is why the package should be thought of as more than a syntax checker.

Current Scope

The current implementation validates:

• criterion A using reductionPercent
• criterion B using EOO, AOO, locations, fragmentation, decline/fluctuation flags, and conditionMatrix
• criterion C using matureIndividuals, decline, subpopulation size, concentration, and extreme fluctuations
• criterion D using very small population or restricted distribution rules
• criterion E using extinction probability thresholds

Current Criterion B Rules

The criterion B implementation validates:

• category thresholds for CR, EN, and VU
• B1 against EOO
• B2 against AOO
• at least two conditions among a, b, and c
• a using severe_fragmentation or nLocations
• b using declared subitems plus continuingDecline=true
• c using declared subitems plus extremeFluctuations=true
• strict consistency between declared subitems and conditionMatrix

Examples of criterion B clauses:

• B1a
• B1b(ii)
• B2a
• B2c(iv)

Languages

Supported values for lang:

• en
• pt
• es

Default:

lang: 'en'

How To Read valid

valid means that the declared combination is internally coherent according to the implemented rule set.

It does not mean:

• that every possible criterion supported by the data was declared
• that the payload is a perfect narrative IUCN assessment
• that no expert judgment would still be required

For that reason, reconciliation fields such as missingCriteriaClauses and unsupportedCriteriaClauses should be interpreted alongside valid.

Project Files

• Types and input class: src/types.ts
• Thresholds: src/thresholds.ts
• i18n / translations: src/i18n.ts
• Inference engine: src/inference.ts
• Console reporter: src/console-reporter.ts
• Criterion validators: src/validators/
• Orchestrator: src/iucn_red_list_criteria_validator.ts
• Public exports: src/index.ts
• Example scenarios: src/test/check.ts

Next Steps

Recommended next improvements:

1. Add a larger automated test suite with assertions, not only console output
2. Decide whether missingCriteriaClauses and undeclaredButSupportedCriteriaClauses should continue to coexist or whether one should be derived
3. Consider an optional convenience field like:

reconciliationStatus:
  | 'exact_match'
  | 'missing_supported'
  | 'unsupported_declared'
  | 'mixed'

That field would make UI, spreadsheets, QA dashboards, and bulk review pipelines easier to build.