Permanent Security Identifier Mapping

Scoped, Effective-Dated Crosswalks

Install and import

bash

npm install fintech-algorithms

import { resolveIdentifier } from "fintech-algorithms/corporate-actions-and-security-master-data/identity-continuity/permanent-security-identifier-mapping";

Signature

resolveIdentifier(data)

Worked example

executed Captured by running this function on the input its own test provides. Real output of real code — but not asserted against a published figure.

Input

data

{
  "query": {
    "source": {
      "scheme": "TICKER",
      "value": "alp",
      "entityLevel": "trading_line",
      "venueMic": "xnas"
    },
    "validAt": "2024-06-15T14:30:00Z",
    "knowledgeAt": "2024-06-20T12:00:00Z"
  },
  "assertions": [
    {
      "assertionId": "SYN-MAP-001",
      "revision": 1,
      "source": {
        "scheme": "TICKER",
        "value": "ALP",
        "entityLevel": "trading_line",
        "venueMic": "XNAS"
      },
      "target": {
        "canonicalId": "SYN-LINE-ALPHA-XNAS-USD",
        "entityLevel": "trading_line"
      },
      "validFrom": "2024-01-02T14:30:00Z",
      "validTo": "2024-07-01T13:30:00Z",
      "observedAt": "2023-12-20T18:00:00Z",
      "availableAt": "2023-12-20T18:05:00Z",
      "status": "active",
      "confidence": "authoritative",
      "checkDigitStatus": "not_applicable",
      "assignmentAuthority": "SYNTHETIC EXCHANGE NOTICE SERVICE",
      "sourceDocumentId": "SYN-NOTICE-100-R1"
    },
    {
      "assertionId": "SYN-MAP-001",
      "revision": 2,
      "source": {
        "scheme": "TICKER",
        "value": "ALP",
        "entityLevel": "trading_line",
        "venueMic": "XNAS"
      },
      "target": {
        "canonicalId": "SYN-LINE-BETA-XNAS-USD",
        "entityLevel": "trading_line"
      },
      "validFrom": "2024-01-02T14:30:00Z",
      "validTo": "2024-07-01T13:30:00Z",
      "observedAt": "2024-06-25T09:00:00Z",
      "availableAt": "2024-06-25T09:05:00Z",
      "status": "active",
      "confidence": "authoritative",
      "checkDigitStatus": "not_applicable",
      "assignmentAuthority": "SYNTHETIC EXCHANGE NOTICE SERVICE",
      "sourceDocumentId": "SYN-CORRECTION-100-R2"
    },
    {
      "assertionId": "SYN-MAP-002",
      "revision": 1,
      "source": {
        "scheme": "TICKER",
        "value": "ALP",
        "entityLevel": "trading_line",
        "venueMic": "XNAS"
      },
      "target": {
        "canonicalId": "SYN-LINE-GAMMA-XNAS-USD",
        "entityLevel": "trading_line"
      },
      "validFrom": "2024-07-01T13:30:00Z",
      "validTo": null,
      "observedAt": "2024-06-10T16:00:00Z",
      "availableAt": "2024-06-10T16:03:00Z",
      "status": "active",
      "confidence": "authoritative",
      "checkDigitStatus": "not_applicable",
      "assignmentAuthority": "SYNTHETIC EXCHANGE NOTICE SERVICE",
      "sourceDocumentId": "SYN-NOTICE-101-R1"
    }
  ]
}

Call

resolveIdentifier(data)

Returns

object with 9 fields: status, source, validAt, knowledgeAt, canonicalId, candidateCanonicalIds, confidence, evidence, …

{
  "status": "resolved",
  "source": {
    "scheme": "TICKER",
    "value": "ALP",
    "entityLevel": "trading_line",
    "venueMic": "XNAS"
  },
  "validAt": "2024-06-15T14:30:00Z",
  "knowledgeAt": "2024-06-20T12:00:00Z",
  "canonicalId": "SYN-LINE-ALPHA-XNAS-USD",
  "candidateCanonicalIds": ["SYN-LINE-ALPHA-XNAS-USD"],
  "confidence": "authoritative",
  "evidence": [
    {
      "assertionId": "SYN-MAP-001",
      "revision": 1,
      "availableAt": "2023-12-20T18:05:00Z",
      "assignmentAuthority": "SYNTHETIC EXCHANGE NOTICE SERVICE",
      "sourceDocumentId": "SYN-NOTICE-100-R1",
      "confidence": "authoritative",
      "checkDigitStatus": "not_applicable"
    }
  ],
  "reason": "Exactly one canonical entity is supported at both requested clocks."
}

Diagrams

Permanent Security Identifier Mapping — article hero

Permanent Security Identifier Mapping — failure guard

Permanent Security Identifier Mapping — worked example

Calculation flow

Identity layers

flowchart TB
    LE["Legal entity"] -->|acts as| ISS["Issuer"]
    ISS -->|issues| INS["Instrument or security"]
    INS -->|may define| CLS["Share class"]
    CLS -->|admitted as| LST["Listing"]
    LST -->|exposed through| LIN["Trading line"]
    VEN["Venue"] -->|hosts| LIN
    SYM["Quote-symbol assignment"] -->|names in venue context| LIN

Two-clock resolution flow

flowchart LR
    Q["Scoped source + validAt + knowledgeAt"] --> V["Validate layer, venue, time, lineage"]
    V --> R["Group by assertion ID"]
    R --> K["Select latest revision available by knowledgeAt"]
    K --> B["Apply active status and validity at validAt"]
    B --> C["Count distinct same-layer targets"]
    C -->|0| U["Unmapped"]
    C -->|1| S["Resolved with evidence"]
    C -->|More than 1| A["Ambiguous with candidates"]

How it works

This page states the contract — how to call it correctly. The article explains the concept: why it works, and where it breaks.

Read the article →

References

ISO 6166:2021, International securities identification number
ANNA ISIN Uniform Guidelines relating to ISO 6166
The Legal Entity Identifier: Questions and Answers
LEI Common Data File format 3.1
About CGS Identifiers
CGS identifier request terms
Financial Instrument Global Identifier Specification
ISO 10383:2012 and MIC Registration Authority
Corporate Actions by Public Companies
Nasdaq Symbol Directory Definitions