GLEIF Data Consumer's Quick Guide This guide serves as a summary of the data and interfaces that GLEIF provides and how they were affected by the new CDF versions introduced on March 1st 2022. It includes concrete technical instructions and examples to help you make your automated systems compatible with the new CDF formats. Be sure to read the "How To Use This Guide" section before delving into the details. This document focuses on technical changes to the data formats published by GLEIF relevant for automated data processing to be capable of processing the new CDF formats. We omit details about deprecated fields/values, new Enum values and state transition rules relevant for interpreting the data correctly. Be sure to check the extensive information about the latest CDF formats published on the GLEIF website: Current Versions. Contents ¢ How To Use This Guide ¢ XML: Golden Copy & Concatenated Files o LEICDF 31 o RRCDF 2.1 o REPEX CDF 2.1 ¢ Concatenated Files o Website o XML Files o Download API ¢ Golden Copy o Website o XML Files o Download API o Export Formats = JSON = CSV e GLEIF API
How To Use This Guide e Be sure to check the section "XML: Golden Copy & Concatenated Files" to get an overview of relevant technical changes introduced by the new formats e Check the table of contents and read the sections corresponding to the GLEIF data sources you use ¢ Pay special attention to the “@ Instructions" provided at the beginning of most sections to understand the minimal adjustments you should make to your systems to be able to consume the latest CDF files
Only the lei-records API resource structure changed. While existing attributes remained unchanged, new attributes, relationships and filters were added. @ Instructions: ¢ Ignore unexpected JSON fields and values or add support for them ¢ In case you rely on successor entity information o use the new successorEntities attribute (plural; array) instead of the deprecated successorEntity attribute (singluar). The old attribute remains but only contains the first occurrence, in case multiple successors were reported. o usethe new successor-entities relationship (plural; one-to-many) instead of the deprecated successor—-entity relationship (singluar; one-to-one). The old relationship remains but only links the first successor entity occurrence, in case multiple successors were reported. For details, see the documentation on GLEIF API Changes here or find it on the GLEIF web page for Supporting Documents. Example files: ¢ Download LEI 3.1 JSON:API response example ¢ See the "Example Files - GLEIF APl Response" on the GLEIF web page about Supporting Documents ¢ Visit the official download page for the Golden Copy files, which are published in the new formats since March 1st 2022.
XML: Golden Copy & Concatenated Files The new formats only introduced new optional fields and Enum values. This means the new XML schemas also validate historical files published prior to March 1st 2022. But validation could fail if you attempt to validate a file in the new version with an old XML schema. Furthermore, your automated data processing tools need to be able to deal with the new fields and Enum values introduced. Instructions: ¢ Use the new XML Schemas (they also work on the historical files), in case you run XML schema validators against any published XML files e Ignore unexpected fields and values or add support for them New XML schemas: CDF Version XML Schema LEI CDF 31 2021-03-04_lei-cdf-v3-1.xsd RR CDF 21 2021-03-04_rr-cdf-v2-1.xsd Reporting Exceptions format 2.1 =~ 2021-07-20_reporting-exceptions-format-v2-1.xsd The GLEIF Concatenated files and Golden Copy files are both be published in the new formats and all information about the XML changes apply to both and took effect on March 1st 2022. LEI CDF 3.1 The LEI CDF 3.1 format introduced new (optional) fields and additional Enum values for the fields EntityCategory, EntityStatus, RegistrationStatus . Instructions: e Use the new XML Schemas (they also work on the historical files), in case you run XML schema validators against any published XML files ¢ Ignore unexpected new fields or add support for them e |n case you use any of previously existing XML fields with new enums, ignore unexpected Enums or add support for them In the following, we show all new (optional) XML elements introduced in LEI CDF 3.1. Additional details on deprecations and new Enum fields are omitted and can be found on the website: ¢ Release Notes / Change Log ¢ Diagram with highlighted changes New XML Elements: ¢ The concatenated file now contains the GLEIF LEI code in the LEIData header: lei:LEIData/lei:LEIHeader/lei:Originator e New optional EntitySubCategory element ¢ New optional LegalEntityEvents container element e New optional EntityCreationDate element e Existing SuccessorEntity container element can now occur multiple times
Below snippet highlights the new (optional) fields that the new LEI CDF 3.1 format introduced. Check the Supporting Documents page for example files for GLEIF Concatenated files and Golden Copy files. Or go directly to the official download pages for the Concatenated files and Golden Copy files, which are published in the new formats since March 1st 2022. ? ml ers on @ encod ng U 87 le Data mlns gle f http gle f org concatenated f le header e tens on 2 @ mlns le le eader le ContentDate 2022 03 0 09 00 00 00 00 1le ContentDate le Or g nator 506 00G G29325Q 363 1le Or g nator le leContent G u PUB S D Lle leContent le RecordCount le RecordCount le tens on gle f Sources gle f Sources le tens on le eader le Records le Record mlns le http gle f org data schema le data 20 6 le 506 900G G29325Q 363 le le nt ty le egaldur sd ct on D le egalJur sd ct on le nt tyCategory G R le nt tyCategory le nt tySubCategory C R GO R le nt tySubCategory le nt tyCreat onDate 2020 06 30 00 00 00 000 02 00 le nt tyCreat onDate le Successor nt ty le Successor nt ty le Successor nt ty le Successor nt ty le Successor nt ty le Successor nt ty le egal nt ty ents le egal nt ty ents le nt ty le Record le Records le Data . ________________________________________________________________________________________________J RR CDF 2.1 The RR CDF 2.1 format does only include additional Enum values for the fields RelationshipType , RelationshipStatus , QualifierCategory . @ Instructions: e Use the new XML Schemas (they also work on the historical files), in case you run XML schema validators against any published XML files ¢ |n case you use any of the affected fields, ignore unexpected Enums or add support for them Additional details on deprecations and new Enum fields can be found on the website: ¢ Release Notes / Change Log ¢ Diagram with highlighted changes Check the Supporting Documents page for example files for GLEIF Concatenated files and Golden Copy files. Or go directly to the official download pages for the Concatenated files and Golden Copy files, which are published in the new formats since March 1st 2022.
REPEX CDF 2.1 The Reporting Excepions format 2.1 format does only include additional Enum values for the ExceptionReason field. Instructions: e Use the new XML Schemas (they also work on the historical files), in case you run XML schema validators against any published XML files e |n case you use any of the affected fields, ignore unexpected Enums or add support for them Additional details on deprecations and new Enum fields can be found on the website: ¢ Release Notes / Change Log ¢ Diagram with highlighted changes Check the Supporting Documents page for example files for GLEIF Concatenated files and Golden Copy files. Or go directly to the official download pages for the Concatenated files and Golden Copy files, which are published in the new formats since March 1st 2022.
Concatenated Files The concatenated files are still published via the GLEIF website and the API without any changes, except for the new XML formats that need to be expected after March 1st 2022. Website Other than the displayed CDF version labels, the Concatenated file download pages remained unchanged. In case you are processing the files automatically, see the main section "XML: Golden Copy & Concatenated Files" and corresponding XML CDF type sections for instructions. XML Files Instructions: ¢ Use the new XML Schemas (they also work on the historical files), in case you run XML schema validators against any published XML files e Ignore unexpected fields and values or add support for them See the main section "XML: Golden Copy & Concatenated Files" for a technical summary of the changes introduced in the new version. See "Example Files - Concatenated Files (XML)" on Supporting Documents for example files. Or go directly to the official download page for the Concatenated files, which are published in the new formats since March 1st 2022. Download API Everything stayed the same and all processes that were using the API before can expect the same URLs and JSON attributes. Instructions: * No need to change any API requests or the processing of the JSON responses e If you use the XML file downloads, ensure to prepare your system by checking the corresponding XML sections above. To ensure backwards-compatibility of the API with consuming systems, the lei2 keyword used in the APl URLs and JSON response attributes remained; there was no 1lei3 introduced. To indicate the CDF version, the API recently introduced a new cdf_version field that contains the new version identifiers since March 1st 2022: LEI_3_1, RR_2_1, REPEX_2_ 1 The following API request still looks identical since March 1st 2022, with the exception of the cdf_version : https://leidata.gleif.org/api/v1/concatenated-files/lei2/latest
{ / "data": { "id": 12, "type": "lei2", I VLD Ouain M “cdf_wversion® will change, according to the “type’: "content_date”: "2822-82-0L 89:08:01", leiz : LEI.3.1 "necond_count: 2064215, / - 1 RR_Z_1 "edg_venaion™: "LEI_2.1", repex : REPEX_2_1 XML file downloads "§ile": "https://leidata,gle:i_f.orgapi.r1ccncatenated-filesleiZ/get/HBlZ/zip",z«‘f_’;‘fLW" will be in the new "gilesize": | 4 formats "signatune": "https://leidata.gleif.org/api/vl/concatenated-files/leil/get/27012/signature", "sources”: [ oy o ; "i4_galfback": s, "Pou_gife": { "id" : ¢ "type™: "lei2", "upfoaded_at": "2822-82-0L 88:33:85", "oniginaton": "©29280067ATKECHAHEES", "content_date": "2022-02-04L ©8:11:28", "necond_count": 5 "edf_wvendion": "LEI_2.1", "file": "https://leidata.gleif.org/api/vi/source-files/leid/get/2202518/zip", "gilesize": 7 "signatune": "https://leidata.gleif.org/api/vl/source-files/lei2/get/2262518/signature"” 3 J }
Golden Copy Except for the new (optional) elements and enum values, the Golden Copy files remained the same. The XML and JSON files continue to have the GeoCoding data. Website Other than the displayed CDF version labels, the Golden Copy download page will remained unchanged. In case you are processing the files automatically, see the main section "XML: Golden Copy & Concatenated Files" and corresponding XML CDF type sections for instructions. XML Files See the main section "XML: Golden Copy & Concatenated Files" for further instructions and technical summary of the changes introduced in the new version. See "Example Files - Golden Copy (XML,JSON, CSV)" on Supporting Documents for example files. Or go directly to the official download page for the Golden Copy files, which are published in the new formats since March 1st 2022. Instructions: ¢ Use the new XML Schemas (they also work on the historical files), in case you run XML schema validators against any published XML files e Ignore unexpected fields and values or add support for them Download API Everything stayed the same and all processes that use the API can expect the same URLs and JSON attributes. Instructions: * No need to change any API requests or the processing of the JSON responses e If you use the XML file downloads, ensure system can handle the new formats by checking the corresponding XML sections above. * If you use the CSV/JSON file downloads, ensure to your system can handle the new fromats by checking the corresponding Golden Copy CSV/JSON export sections below. To ensure backwards-compatibility of the API with consuming systems, the lei2 keyword used in the APl URLs and JSON response attributes remained; there was be no 1lei3 introduced. To indicate the CDF version, the API recently introduced a new cdf_version field that will contain the new version identifiers starting March 1st 2022: LEI_3_1, RR_2_1, REPEX_2 1 The following API request still looks identical after March 1st 2022, with the exception of the cdf_version : https://goldencopy.gleif.org/api/v2/golden-copies/publishes/lei2/latest
L f "data”s { "type": "leid", *—'—— Type remains “lei2 "pub@ish_date": "2022-82-8L 88:00708", "Guel_gite": Ytype": "lei2", "gonmat™: “ecsv", “necond_count": 5 "size": f €SV downloads will be i "size_human_neadab@e”: “214.57 MB", Afi,/ the new format "delta_type”: "GoldenCopy", £ "une": "https://leidata-preview.gleif.org/storage/golden-copy-files/2822/082/04/595266/208226284-0808-gleif-goldencopy-lei2-golden-copy.csv.zip", Yedf_vension”: "LEI_2.1" }f & cdf_version® will change, according to the “type : TaonT: £ lei2 : LEI_3.1 "type": "lei2", rr D RR_Z_1 "gonmat": "json", repex : REPEX_Z_1 "necond_count": 4 » JSON downloads will be in "size": f the new format "size_human_neadabfe™”: "386.L6 MB", 4 ;,:’ "defta_type”: "GoldenCopy", fi "ung": "https://leidata-preview.gleif.org/storage/golden-copy-files/2022/02/04/595257/2022020L-0800-gleif-goldencopy-lei2-golden-copy.json.zip", "cd§vension”: "LEI_2.1" 1 Txme": { "type": "lei2", "gonmat": “xml", ::fl%\ia:d,count": = XML downloads will be i ";i:‘c,r.mmfl;i,1r’c1dq£'£'e”: "415.63 NB", ,:_.;-fr" o "defta_type”: "GoldenCopy", o "un€": "https://leidata-preview.gleif.org/storage/golden-copy-files/2022/02/04/595254/20220204-0800-gleif-goldencopy-lei2-golden-copy.xml.zip", "cd§_vension”: "LEI_2.1" 3 ":feum,gwf;”: "IntnaDay™: § e "Lastbay": { 3, “LastMonth": § i "Lastheek”: { 3 ; Note that the Golden Copy APl is available via two domains goldencopy.gleif.org and leidata- preview.gleif.org (legacy). This could lead to differing download URLs, but does not pose any problems as the behavior did not change. Export Formats JSON The JSON exports was be extended with the additionally introduced fields, where present. Additionally, the Entity.SuccessorEntity field now holds an array of potentially multiple successor entity entries and certain fields are ensured to always be returned as an array. @ Instructions: LEI: e If you use the Entity.SuccessorEntity field, your system must expect an array of object s (the Successor Entity is now a repeatable field) e If you use the AdditionalAddressLine in any of the addresses, your system must expect an array of string s. Since March 1st 2022 this field is always an array, even if only one additional address line is present. e If you use the OtherValidationAuthority field, your system must expect either an array of objects . Since March 1st 2022 this field is always an array. RR: e |f you use the RelationshipQualifier or RelationshipQuantifier field, your system must expect an array of obje
ct s. Since March 1st 2022 this field is always be an array. REPEX: e |If you use the ExceptionReason or ExceptionReference field, your system must expect an array of string s. Since March 1st 2022 this field is always be an array.
For details, see the JSON Export section of the document "(Breaking) Changes in Golden Copy Exports" published on the GLEIF website under Supporting Documents. Example Files: ¢ Download LEI 3.1, RR 2.1, REPEX 2.1 JSON Export Example ¢ See "Example Files - Golden Copy (XML, JSON, CSV)" on Supporting Documents ¢ Visit the official download page for the Golden Copy files, which are published in the new formats since March 1st 2022. Csv Only the CSV export for LEI data changed in structure, due to additional columns that were added and the now- repeating SuccessorEntity field. @ Instructions: e Ensure your system does not rely on the exact order of the columns (e.g. by parsing the CSV into an unordered mapping of column names to values, instead of ordered listes of values) e If yourely onany Entity.SuccessorEntity.x* field, ensure to support the indexed 1-5 column names (Entity.SuccessorEntity.1.x ) For details, see the CSV Export section of the document "(Breaking) Changes in Golden Copy Exports" published on the GLEIF website under Supporting Documents. Example files: ¢ Download LEI 3.1, RR 2.1, REPEX 2.1 CSV Export Example ¢ See "Example Files - Golden Copy (XML, JSON, CSV)" on Supporting Documents ¢ Visit the official download page for the Golden Copy files, which are published in the new formats since March 1st 2022.