Using OpenChainGraph with ISO 20022

{
  "@context": [
    "https://ainumbers.co/chaingraph/context/v0.3/context.jsonld",
    "https://ainumbers.co/chaingraph/context/v0.3/iso20022-context.jsonld"  /* v0.3 overlay */
  ],
  "ocg:semantic_profile": "iso20022:pacs.008-subset",        /* discovery marker */
  "tool_id":        "T290",
  "tool_version":   "1.0.0",
  "ap2_version":    "v0.3",
  "mandate_type":   "settlement_mandate",
  "generated_at":   "2026-06-18T14:22:00Z",
  "execution_hash": "a3f7e2c1d9b04856f31a2e7c5d8b09f6e14c2a3d7b05894e2f1c6a8d3e09b47",
  "parent_hashes":  ["c8d12f9e3a74b056e28f3c1a5d9e07b2f46a1c8d3e05792b1f4c7a9e2d08b35"],

  "output_payload": {
    /* ISO 20022 InstructedAmount — amount + currency (ISO 4217) */
    "instructed_amount": {
      "amount":   "15000.00",   /* ActiveCurrencyAndAmount */
      "currency": "EUR"          /* Ccy / CurrencyCode — ISO 4217 */
    },

    /* ISO 20022 Debtor — PartyIdentification */
    "debtor": {
      "party_name": "Acme Payments GmbH",          /* Nm */
      "lei":        "549300TRUWO2CD2G5692",         /* OrganisationIdentification/LEI — ISO 17442 */
      "country":    "DE"                            /* CountryCode — ISO 3166-1 alpha-2 */
    },

    /* ISO 20022 Creditor — PartyIdentification */
    "creditor": {
      "party_name": "Northern Trust Corp",          /* Nm */
      "lei":        "5493008IOANM4MK63B46",         /* OrganisationIdentification/LEI — ISO 17442 */
      "country":    "US"                            /* CountryCode — ISO 3166-1 alpha-2 */
    },

    /* ISO 20022 DebtorAgent — BranchAndFinancialInstitutionIdentification */
    "debtor_agent": {
      "bicfi": "DEUTDEDBFRA"                       /* BICFI — ISO 9362 */
    },

    /* ISO 20022 CreditorAgent — BranchAndFinancialInstitutionIdentification */
    "creditor_agent": {
      "bicfi": "NTRSUS33XXX"                       /* BICFI — ISO 9362 */
    },

    "settlement_date":        "2026-06-20",           /* IntrBkSttlmDt — ISO 8601 date */
    "remittance_information": "INV-2026-00847"         /* RmtInf */
  },

  "compliance_flags": [
    { "framework": "CBPR+", "status": "PASS" },
    { "framework": "LEI_VALID", "status": "PASS" }
  ],

  "audit_signature": {
    "zero_pii_verified": true,
    "signatures": [{
      "keyid": "ocg-signer-v1",
      "sig":   "base64url-ed25519-signature-here"
    }]
  }
}

{
  "@context": {
    "ocg":      "https://ainumbers.co/chaingraph/context/v0.3#",
    "iso20022": "https://ainumbers.co/chaingraph/vocab/iso20022#",
    "xsd":      "http://www.w3.org/2001/XMLSchema#",

    "instructed_amount":      { "@id": "iso20022:InstructedAmount" },
    "amount":                 { "@id": "iso20022:ActiveCurrencyAndAmount" },
    "currency":               { "@id": "iso20022:CurrencyCode",            "@type": "xsd:string" },
    "country":                { "@id": "iso20022:CountryCode",             "@type": "xsd:string" },
    "debtor":                 { "@id": "iso20022:Debtor" },
    "creditor":               { "@id": "iso20022:Creditor" },
    "party_name":             { "@id": "iso20022:Name",                    "@type": "xsd:string" },
    "lei":                    { "@id": "iso20022:LEI",                     "@type": "xsd:string" },
    "debtor_agent":           { "@id": "iso20022:DebtorAgent" },
    "creditor_agent":         { "@id": "iso20022:CreditorAgent" },
    "bicfi":                  { "@id": "iso20022:BICFI",                   "@type": "xsd:string" },
    "iban":                   { "@id": "iso20022:IBAN",                    "@type": "xsd:string" },
    "settlement_date":        { "@id": "iso20022:InterbankSettlementDate", "@type": "xsd:date" },
    "remittance_information": { "@id": "iso20022:RemittanceInformation",   "@type": "xsd:string" }
  }
}

/**
 * ISO 4217 — alphabetic currency codes.
 * Full list: https://www.iso.org/iso-4217-currency-codes.html
 * Representative set for validation; expand from the ISO 4217 XML publication.
 */
const ISO_4217 = new Set([
  // Major currencies
  "AED","AUD","BRL","CAD","CHF","CNY","CZK","DKK","EUR",
  "GBP","HKD","HUF","IDR","ILS","INR","JPY","KRW","MXN",
  "MYR","NOK","NZD","PHP","PLN","RON","RUB","SAR","SEK",
  "SGD","THB","TRY","TWD","USD","ZAR",
  // Additional ISO 4217 codes — extend from full publication as needed
  "AFN","ALL","AMD","ANG","AOA","ARS","AWG","AZN","BAM",
  "BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BSD",
  "BTN","BWP","BYN","BZD","CDF","CLP","COP","CRC","CUP",
  "CVE","DJF","DOP","DZD","EGP","ERN","ETB","FJD","FKP",
  "GEL","GHS","GIP","GMD","GNF","GTQ","GYD","HNL","HTG",
  "IQD","IRR","ISK","JMD","JOD","KES","KGS","KHR","KMF",
  "KPW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL",
  "LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU",
  "MUR","MVR","MWK","MZN","NAD","NGN","NIO","NPR","OMR",
  "PAB","PEN","PGK","PKR","PYG","QAR","RSD","RWF","SBD",
  "SCR","SDG","SHP","SLL","SOS","SRD","SSP","STN","SVC",
  "SYP","SZL","TJS","TMT","TND","TOP","TTD","TZS","UAH",
  "UGX","UYU","UZS","VES","VND","VUV","WST","XAF","XCD",
  "XOF","XPF","YER","ZMW","ZWL"
]);

/**
 * validateISO4217(code) — returns true if code is a known ISO 4217 alphabetic currency code.
 * Production use: replace/supplement this set with the authoritative ISO 4217 XML publication.
 */
function validateISO4217(code) {
  if (typeof code !== "string") return false;
  const upper = code.trim().toUpperCase();
  return /^[A-Z]{3}$/.test(upper) && ISO_4217.has(upper);
}

// Examples:
console.log(validateISO4217("EUR"));  // true
console.log(validateISO4217("XYZ"));  // false — not a valid ISO 4217 code
console.log(validateISO4217("usd"));  // true — case-normalised

/**
 * validateISO3166Alpha2(code)
 * ISO 3166-1 alpha-2 codes are exactly 2 uppercase ASCII letters.
 * A full membership check requires the ISO 3166 Maintenance Agency publication.
 * This implementation validates the format constraint; augment with a Set of
 * valid codes for strict membership validation in regulated contexts.
 */
function validateISO3166Alpha2(code) {
  if (typeof code !== "string") return false;
  return /^[A-Z]{2}$/.test(code.trim().toUpperCase());
}

console.log(validateISO3166Alpha2("DE"));  // true
console.log(validateISO3166Alpha2("US"));  // true
console.log(validateISO3166Alpha2("ZZZ")); // false — 3 chars
console.log(validateISO3166Alpha2("12"));  // false — not alpha

/**
 * validateBICFI(bic)
 * ISO 9362 Business Identifier Code (BIC / BICFI):
 *   [A-Z]{4}  — institution code (4 letters)
 *   [A-Z]{2}  — country code (2 letters, ISO 3166-1 alpha-2)
 *   [A-Z0-9]{2} — location code (2 alphanumeric)
 *   ([A-Z0-9]{3})? — optional branch code (3 alphanumeric)
 * Total: 8 chars (no branch) or 11 chars (with branch).
 */
const BIC_REGEX = /^[A-Z]{6}[A-Z0-9]{2}([A-Z0-9]{3})?$/;

function validateBICFI(bic) {
  if (typeof bic !== "string") return false;
  return BIC_REGEX.test(bic.trim().toUpperCase());
}

console.log(validateBICFI("DEUTDEDBFRA"));  // true — 11-char with branch
console.log(validateBICFI("NTRSUS33XXX"));  // true — 11-char with branch XXX
console.log(validateBICFI("CHASUS33"));     // true — 8-char, no branch
console.log(validateBICFI("BAD"));          // false — too short

/**
 * validateIBAN(iban)
 * ISO 13616 algorithm:
 *   1. Remove spaces, uppercase.
 *   2. Move first 4 characters to the end.
 *   3. Replace each letter with its numeric equivalent: A=10, B=11, …, Z=35.
 *   4. Compute the numeric string mod 97.
 *   5. Valid IBAN → remainder === 1.
 *
 * Country-specific length rules are not enforced here; add a lookup table
 * if strict per-country length validation is required.
 */
function validateIBAN(iban) {
  if (typeof iban !== "string") return false;

  // Step 1: Normalise — remove spaces, uppercase
  const normalized = iban.replace(/\s+/g, "").toUpperCase();

  // Basic structural check: 2 alpha country + 2 digit check + up to 30 alphanum
  if (!/^[A-Z]{2}[0-9]{2}[A-Z0-9]{1,30}$/.test(normalized)) return false;

  // Step 2: Rearrange — move first 4 chars to end
  const rearranged = normalized.slice(4) + normalized.slice(0, 4);

  // Step 3: Convert letters to digits (A=10 … Z=35)
  const numeric = rearranged.replace(/[A-Z]/g, ch => ch.charCodeAt(0) - 55);

  // Step 4 & 5: Compute mod 97 using chunk arithmetic (BigInt avoids precision loss)
  let remainder = BigInt(numeric) % 97n;
  return remainder === 1n;
}

console.log(validateIBAN("GB82 WEST 1234 5698 7654 32"));  // true — canonical IBAN test vector
console.log(validateIBAN("DE89370400440532013000"));       // true — Deutsche Bank DE
console.log(validateIBAN("DE89370400440532013001"));       // false — bad check digit
console.log(validateIBAN("NOTANIBAN"));                   // false — fails structural check

/**
 * validateLEI(lei)
 * ISO 17442 Legal Entity Identifier — 20 characters:
 *   Chars 1–18:  alphanumeric entity identifier (issued by an LOU)
 *   Chars 19–20: 2-digit check digits, computed via ISO 7064 MOD 97-10
 *                (same algorithm as IBAN mod-97).
 *
 * Algorithm:
 *   1. Convert letters to digits: A=10, B=11, …, Z=35 (same mapping as IBAN).
 *   2. Compute the resulting numeric string mod 97.
 *   3. Valid LEI → remainder === 1.
 */
function validateLEI(lei) {
  if (typeof lei !== "string") return false;

  // Normalise and structural check: exactly 20 uppercase alphanumeric chars
  const normalized = lei.trim().toUpperCase();
  if (!/^[A-Z0-9]{18}[0-9]{2}$/.test(normalized)) return false;

  // Convert letters to digits (A=10 … Z=35), digits stay as-is
  const numeric = normalized.replace(/[A-Z]/g, ch => ch.charCodeAt(0) - 55);

  // MOD 97-10 check: remainder must equal 1
  let remainder = BigInt(numeric) % 97n;
  return remainder === 1n;
}

console.log(validateLEI("549300TRUWO2CD2G5692"));  // true — valid LEI test vector
console.log(validateLEI("5493008IOANM4MK63B46"));  // true — Northern Trust LEI
console.log(validateLEI("549300TRUWO2CD2G5691"));  // false — bad check digit
console.log(validateLEI("TOOSHORT"));              // false — not 20 chars

/**
 * validateISO20022Payload(payload)
 * Convenience wrapper — validates all applicable code-list fields in an OCG
 * output_payload that carries the ISO 20022 profile.
 * Returns { valid: bool, errors: string[] }.
 */
function validateISO20022Payload(payload) {
  const errors = [];

  const currency = payload?.instructed_amount?.currency;
  if (currency && !validateISO4217(currency))
    errors.push(`instructed_amount.currency "${currency}" is not a valid ISO 4217 code`);

  for (const role of ["debtor", "creditor"]) {
    const party = payload?.[role];
    if (party?.country && !validateISO3166Alpha2(party.country))
      errors.push(`${role}.country "${party.country}" is not a valid ISO 3166-1 alpha-2 code`);
    if (party?.lei && !validateLEI(party.lei))
      errors.push(`${role}.lei "${party.lei}" fails ISO 17442 MOD 97-10 check`);
  }

  for (const role of ["debtor_agent", "creditor_agent"]) {
    const agent = payload?.[role];
    if (agent?.bicfi && !validateBICFI(agent.bicfi))
      errors.push(`${role}.bicfi "${agent.bicfi}" fails ISO 9362 BIC validation`);
  }

  for (const role of ["debtor_account", "creditor_account"]) {
    const account = payload?.[role];
    if (account?.iban && !validateIBAN(account.iban))
      errors.push(`${role}.iban "${account.iban}" fails ISO 13616 mod-97 check`);
  }

  return { valid: errors.length === 0, errors };
}

{
  "nodes": [
    {
      "tool_id":                "T290",
      "name":                   "Settlement Mandate Validator",
      "mandate_type":           "settlement_mandate",
      "tool_version":           "1.0.0",
      "ap2_version":            "v0.3",
      "ocg:semantic_profile":   "iso20022:pacs.008-subset",   /* ISO 20022 discovery marker */
      "href":                   "tools/T290-settlement-mandate-validator.html",
      "compliance_frameworks":  ["CBPR+", "LEI_VALID"]
    },
    {
      "tool_id":                "T291",
      "name":                   "CBPR+ Address Validator",
      "mandate_type":           "compliance_control",
      "tool_version":           "1.0.0",
      "ap2_version":            "v0.3",
      "ocg:semantic_profile":   "iso20022:pacs.008-subset",   /* same marker */
      "href":                   "tools/T291-cbpr-address-validator.html",
      "compliance_frameworks":  ["CBPR+"]
    }
  ]
}

/**
 * findISO20022Tools(chaingraphJson)
 * Given the parsed chaingraph.json object, returns all nodes that declare
 * an ISO 20022 semantic profile. Filters on the ocg:semantic_profile field.
 */
function findISO20022Tools(chaingraphJson) {
  const nodes = chaingraphJson?.nodes ?? [];
  return nodes.filter(node =>
    typeof node["ocg:semantic_profile"] === "string" &&
    node["ocg:semantic_profile"].startsWith("iso20022:")
  );
}

// Usage — fetch the live graph index and find ISO 20022-aligned tools:
const resp = await fetch("/chaingraph/chaingraph.json");
const index = await resp.json();
const iso20022Tools = findISO20022Tools(index);

console.log(iso20022Tools.map(t => `${t.tool_id}: ${t.name}`));
// ["T290: Settlement Mandate Validator", "T291: CBPR+ Address Validator"]

// Narrower filter — only pacs.008-subset profile:
const pacs008Tools = iso20022Tools.filter(
  t => t["ocg:semantic_profile"] === "iso20022:pacs.008-subset"
);