The FATCA XML schema is based on business requirements collected by a multilateral working group. The schema uses elements from existing reporting schemas used by the OECD and the European Union (EU) to reduce burden on reporting entities. The links below provide guidance on how to validate schemas.
XML resources
The .xsd and sample .xml files can be viewed with a web browser, such as Internet Explorer or Chrome and a text editor such as Microsoft Notepad, or an XML tool such as XMLSpy or XML Notepad.
Data preparation sample packet
Review the sample FATCA data packet that includes all data files used to create a test transmission to the IRS.
Important: In January 2017, the FATCA XML schema v2.0 replaced v1.1 and the FATCA notification XML schema v2.3 replaced v2.2. All International Data Exchange Service (IDES) users are required to submit FATCA reports using version 2.0 because version 1.1 is not supported.
| Resources | Description |
|---|---|
| FATCA XML v2.0 ZIP updated 08-31-2016 effective 01-2017 |
FATCAXML_v2.0 (25KB) - Main schema for FATCA reporting. ISOFATCATypes-v1.1 (72 KB) - Two-letter country codes defined in ISO 3166-1 standard and the three-letter currency codes defined in ISO 4217 standard. Referenced by main schema. OECDTypes-v4.1 (37KB) - Defines different types for a name and legal character of an address. Referenced by STF FATCA schema. STFFATCATypes-v2.0 (24KB) - Common data types specific for FATCA based on the Standard Transmission Format (STF) from the OECD. Referenced by main schema. |
| AmendedNilFIReport (XML) Updated 02-08-2017 |
(2KB) - Sample amended Nil FI report |
| NewNilFIReport (XML) Updated 08-31-2016 |
2KB) - Sample Nil FI report |
| VoidNilFIReport (XML) Updated 08-31-2016 |
(2KB) - Sample void Nil FI report |
| CARResponse ZIP Updated 12-07-2016 |
(7KB) - Sample CAR response and filing scenario. |
| OptionalElements ZIP Updated 12-07-2016 |
(4KB) - Sample with optional elements, attributes and all available choices. |
| NFFE ZIP Updated 01-10-2017 |
(17KB) - Sample for a direct reporting non-financial foreign entity (DRNFFE) with substantial U.S. owners.
|
| Sender Metadata XML v1.3 Effective 07-2020 |
FATCA-IDES-SenderFileMetadata-1.3 (17 KB)- Main schema used to generate sender metadata file FATCA Sender File Metadata XML Samples v1.3 :
|
| FATCA Notification XML v2.5 ZIP Effective 08-2020 |
BASE-FATCA-NOTIFICATION-2.5 (100 KB) - Base schema for common data elements and data types related to FATCA notifications. Referenced by all main notifications schemas.
FATCA-FILE-ERROR-NOTIFICATION-2.5 (4 KB) -Main schema that describes various types of file level error notifications.
|
| FATCA Wrapper for Non-XML v1.1 ZIP Effective 8-21-2015 |
FATCA-IDES-FileWrapper-1.1 (135 KB) - Base schema for common data elements and data types for converting non-XML formatted files into an XML format. The only allowable non-XML file types are TXT, PDF, RTF and JPG. FATCA IDES File Wrapper Non-XML Samples:
To Convert to XML:
|
User guides
| Publication | Description |
|---|---|
| Publication 5124, FATCA XML Schema v2.0 User Guide PDF (Rev. 04-2017) | This guide outlines the business and validation rules to support a Form 8966, FATCA report filed electronically through the International Data Exchange Service (IDES). |
| Publication 5188, FATCA Metadata XML Schema v1.2 User Guide PDF (Rev. 07-2020) | This guide serves as a tool for FIs, direct reporting NFFEs, sponsoring entities, non-GIIN filers, and Host Country Tax Authorities (HCTAs) who transmit data through the International Data Exchange Service (IDES). It explains how to prepare and validate the IDES metadata file used in FATCA reporting. |
| Publication 5189, ICMM Notifications User Guide PDF (Rev. 08-2020) | This guide includes detailed explanations about the potential notification filers will receive in response to the files they submit via the International Data Exchange System (IDES). |
| Publication 5216, ICMM Notification XML Schema User Guide PDF (Rev. 08-2020) |
This guide provides a general description of the FATCA notification schema V2.5 that will be the basis for all electronic notifications from the Internal Revenue Service (IRS) to FATCA filers – Foreign Financial Institutions (FFIs), direct reporting non-financial foreign entities (direct reporting NFFEs), sponsoring entities, trustees of trustee-documented trusts, non-GIIN filers, and Host Country Tax Authorities (HCTAs) -- using the International Data Exchange Service (IDES). |