Edition and the 2027 schema migration
This article follows IRAS’s fourth-edition CRS XML user guide, version 4.0.1 published 8 July 2026. From 1 January 2027 every XML CRS submission, including past-year returns and corrections, uses OECD CRS schema v3.0. Before that date use v2.0 and IRAS’s third edition. The submission date selects the schema; the reporting year separately determines transitional values for the new fields. The guide supplements the CRS Regulations and substantive due-diligence guidance rather than deciding which accounts are reportable.
Submission channel, size and sequence
All returns, including nil returns, are electronic through myTax Portal. Combine all reportable jurisdictions in one return if desired. XML needs no digital signature, encryption or compression. From 1 January 2027 each uncompressed file can be up to 50MB, increased from 5MB. Split larger files and wait for IRAS to accept the first before submitting subsequent files. A correction/void must be submitted no earlier than the day after the erroneous initial submission; a correction of a correction also waits for acceptance of its predecessor. No filename rule applies, but the MessageRefID is recommended. A fillable PDF return is an alternative for institutions not generating XML.
Nil returns and Trustee-Documented Trusts
An ordinary SGFI without reportable accounts uses “Submit Nil Data” in the AEOI digital service, not an XML nil return. A trustee can submit nil returns for up to 50 Trustee-Documented Trusts (TDTs) in one digital-service submission or use XML for the trusts under its care. CRS703 is restricted to that trustee XML nil-reporting scenario and omits AccountReport. The XML ReportingFI identifies the trust, not the trustee that sent the file.
Encoding, escaping and forbidden content
Start with an XML declaration, encode UTF-8 and omit the byte order mark. Escape ampersand, apostrophe, angle brackets and double quotes as &, ', <, > and ". IRAS additionally rejects data containing #, --, /* or &#; the guide gives no acceptable equivalent for those sequences. Do not substitute an empty string in a mandatory field. String elements have minimum length one, and optional fields with no value should be omitted. Validate the file with the schema and the Singapore business rules before sending.
Schema optional does not always mean optional reporting
“Validation” fields must be present and pass automated checks; “Validation (choice)” means one permitted alternative under the required parent is needed. A schema-optional element can still be mandatory under CRS unless unavailable for a legal/permitted reason, for example a preexisting-account TIN not previously collected. Ordinary optional information is recommended where held; “Optional (non-CRS)” is not used for CRS. Apply business obligations as well as the XSD’s technical acceptance.
Message header and sender identification
SendingCompanyIN identifies the sender, which may be the SGFI or its service provider. Use “Entity ID Type”, one space and the Singapore tax number, for example ASGD A1234567D. Allowed types are UEN-Business, UEN-Local Co, UEN-Others, ASGD and ITR. TransmittingCountry and ReceivingCountry both use SG, and MessageType uses CRS. Warning and Contact must be blank for IRAS’s automated processing; reporting correspondence uses [email protected] with the submission acknowledgement ID, and IRAS liaises with the registered point of contact/authorised users.
Create a unique 25-character MessageRefID
The Singapore identifier is reporting year YYYY + sender tax number padded on the right with hyphens to ten characters + file creation date YYYYMMDD + three-digit daily increment. Do not include the entity-ID-type prefix. The increment ranges 000–999 and must preserve uniqueness across all files that sender creates that day, including different funds. The guide’s historical example uses 201701234567L-20180521001 and then suffix 002. The schema allows a longer general identifier, but Singapore’s required format is the 25-character structure. Each correction has its own new MessageRefID.
Message type, reporting period and timestamp
CRS701 means new data; CRS702 means correction/deletion; CRS703 means permitted TDT nil data. Do not mix new and correction/deletion records in one file, and match the portal’s “Submit New Data” or “Correct/Void Past Data” choice. CorrMessageRefID is not used for CRS. ReportingPeriod is the last day of the reporting year, e.g. 2017-12-31. Timestamp is compilation time in YYYY-MM-DDThh:mm:ss, optionally with three-digit milliseconds. Neither a creation date nor submission date replaces the reporting period.
Individuals: tax residence and a change of jurisdiction
Individual holders and passive-NFE controlling persons use PersonParty_Type. Report the tax-residence ISO alpha-2 code; separate AccountReports are required for each reportable tax-residence jurisdiction. The residence code is not nationality or address country. If an accepted report’s residence jurisdiction must change, void it first and submit a new AccountReport; do not merely send an ordinary field correction. For an undocumented account use residence SG and the specified undocumented-address treatment. Nationality is a non-CRS field.
TINs, issuing jurisdictions and missing-number reasons
Use the TIN/equivalent recognised by the residence jurisdiction; repeat if multiple recognised numbers exist. Supply issuedBy when known and omit that attribute if not known. Do not use zeros, repeated letters or invented placeholders. If neither a number nor a reason code is provided, omit the TIN element. Reasons are encouraged where available; IRAS104 requires a reasonable explanation and supporting documents where appropriate. The same approach applies to an entity’s IN, including recognised company/EIN/other identifiers.
| Code | Missing TIN/IN reason |
|---|---|
| IRAS101 | Residence jurisdiction does not issue the number |
| IRAS102 | Residence jurisdiction does not require reporting it |
| IRAS103 | Changed circumstances; obtaining new self-certification containing the number |
| IRAS104 | Other explained and appropriately documented reason |
Names, mononyms and optional qualifiers
FirstName and LastName are required. Obtain first, middle where any, and last names and place them in their respective fields. An initial or NFN may be used where a complete first name is unavailable; for a mononym use FirstName NFN and put the single name in LastName. MiddleName, NamePrefix, preceding title, title, generation identifier, suffix/general suffix and xnlNameType qualifiers are optional, typically 1–200 characters. Name-type codes are OECD202 individual, 203 alias, 204 nickname, 205 also-known-as, 206 doing-business-as, 207 legal and 208 birth name. Do not invent unavailable birth/marriage-name information.
Addresses: structured, free-text and undocumented accounts
Prefer AddressFix for the permanent residence address; if unavailable use the mailing address held when compiling the report. CountryCode is required. AddressFix requires City and should include an existing postcode, with street/building/suite/floor/district/POB/state fields where available. A free-text street can accompany fixed city/state/postcode. Use AddressFree alone only when structure cannot be supplied, or for an undocumented account; City is then unnecessary. Free address can use spaces, slashes or line breaks and allows up to 4,000 characters. Undocumented accounts use country SG and AddressFree “Undocumented”. Address legal types OECD301–305 respectively mean residential-or-business, residential, business, registered office and unspecified.
Birth details and entity account holders
Birthdate uses YYYY-MM-DD; for a preexisting account with no recorded birthdate omit it under the stated rule. If reporting birthplace, provide city, optional city subentity, and either a current country code or former-country name. Entity holders use OrganisationParty_Type: residence, IN, legal name and address. Multiple tax-residence jurisdictions need separate reports, and jurisdiction changes require void-and-new. Entity IN can repeat recognised numbers; issuedBy and INType identify issuing jurisdiction/type where supplied. Legal name is required, normally 1–200 characters.
CRS body, ReportingFI and TDT identifiers
CrsBody is required for IRAS even if the XSD depicts it as optional. It contains ReportingFI plus exactly one ReportingGroup, repeating AccountReport as needed. ReportingFI identifies the SGFI maintaining the account, not necessarily the sender. Use the one Singapore tax number linked to CRS registration, with type + space + number; do not put its entity-ID type in INType. For a trustee filing for a TDT, identify the trust and use its IRAS-issued reference as “TDT reference-number”. ReportingFI and each AccountReport carry their own DocSpec. Sponsor, Intermediary and PoolReport are non-CRS and not applicable.
Account number and status flags
AccountNumber is required: use the account number, debt/equity ISIN/code, insurance/annuity contract identifier or functional unique equivalent. Only exceptionally when no numbering system exists use NANUM. Prefer an available IBAN/ISIN with its type. AcctNumberType codes OECD601 IBAN, 602 other bank number, 603 ISIN, 604 other securities number, 605 other identifier and 606 specified electronic-money product. UndocumentedAccount, ClosedAccount and DormantAccount boolean attributes are schema-optional but reporting-mandatory when applicable. A closed account has balance zero and the closed flag, not an omitted balance.
Entity-holder classification
Choose Individual, or Organisation plus AcctHolderType, never omit both. Entity codes are CRS101 passive NFE with at least one reportable controlling person; CRS102 a reportable person; CRS103 passive NFE itself a reportable person. Reportable controlling-person data are mandatory where that passive-NFE condition applies. Use separate reports for each distinct reportable controlling person and each reportable residence jurisdiction; a person with multiple relationships can have repeated ControllingPerson role entries within the same report.
All six passive-NFE reporting examples
Residence overlap avoids an unnecessary duplicate entity record but does not combine distinct controlling persons. X, Y and Z are illustrative tax-residence jurisdictions, not nationality codes.
| Example | Residence facts | Reports required |
|---|---|---|
| 1 | Entity X; one CP X | One CRS101 report |
| 2 | Entity X; CP1 X and CP2 X | Two CRS101 reports, one per CP |
| 3 | Entity X; CP1 Y and CP2 Z, all reportable | Two CRS101 CP reports plus one CRS103 entity report |
| 4 | Entity X; CP1 X and CP2 Y | Two CRS101 reports; no duplicate entity-X report |
| 5 | Entity X non-reportable; CP Y reportable | One CRS101 for CP |
| 6 | Entity X reportable; CP Y non-reportable | One CRS103 for entity |
Controlling-person types and the July 2026 clarification
CtrlgPersonType is validation-required. For reporting years 2026 and earlier submitted from 2027, report a known type from records; otherwise use CRS800. For 2027–2028 supply CRS801–813 only where available electronically; otherwise CRS800. From reporting year 2029, identify the actual role(s) and do not use CRS800. Multiple roles can be repeated within the person’s report. This is the rule clarified in version 4.0.1, rather than a blanket omission of all earlier-year types.
| Code | Role |
|---|---|
| CRS801 | Legal person: ownership |
| CRS802 | Legal person: other control |
| CRS803 | Legal person: senior managing official |
| CRS804 | Trust: settlor |
| CRS805 | Trust: trustee |
| CRS806 | Trust: protector |
| CRS807 | Trust: beneficiary |
| CRS808 | Trust: other |
| CRS809 | Other arrangement: settlor-equivalent |
| CRS810 | Other arrangement: trustee-equivalent |
| CRS811 | Other arrangement: protector-equivalent |
| CRS812 | Other arrangement: beneficiary-equivalent |
| CRS813 | Other arrangement: other-equivalent |
| CRS800 | Not reported, transitional only |
Equity-interest holder roles in legal arrangements
EquityInterestType is repeatable for an investment entity that is a legal arrangement. CRS401–405 are trust settlor, trustee, protector, beneficiary and other; CRS406–410 are the corresponding equivalent roles in another legal arrangement. Omit it for reporting years 2026 and earlier even if submitted after the schema change. For 2027–2028 report only if available electronically; otherwise omit. From reporting year 2029 the applicable roles must be reported. This field is distinct from controlling-person role codes.
Self-certification status for holder and controlling person
Both SelfCert elements are validation-required but use different code sets. For reporting years through 2026 use holder CRS900 and controlling person CRS1000 when submitted from 2027. From reporting year 2027 use holder CRS901 true/CRS902 false and controlling person CRS1001 true/CRS1002 false. These values state whether valid self-certification was provided; they do not replace the substantive due-diligence work or allow the transitional not-reported codes for new reporting years.
Account type, due-diligence category and joint holders
AccountType uses CRS1101 depository, 1102 custodial, 1103 cash-value insurance/annuity and 1104 investment-entity debt/equity. DDProcedure uses CRS1201 new account or 1202 preexisting account. For 2026 and prior years submitted from 2027 use CRS1100 and CRS1200; from reporting year 2027 use the substantive codes. Omit JointAccount for 2026 and earlier; from reporting year 2027 report it for joint accounts, with mandatory integer Number giving the number of holders. Do not confuse new submission with new-account due diligence.
Balances, payments and currency codes
Report balance/value for the relevant account class, including insurance cash value and debt/equity interest value. Use numeric amounts with two decimals and ISO 4217 alpha-3 currency, e.g. 1000.00 and SGD. Closed-account balance is zero with its flag. Repeat Payment for distinct categories: CRS501 dividends, 502 interest, 503 gross proceeds/redemptions and 504 other CRS income. Depository accounts report gross credited/paid interest; custody accounts report gross dividends, interest, sale/redemption proceeds and other income; debt/equity and insurance/annuity accounts report gross paid/credited payments including redemptions. Each payment contains type, amount and currency.
ReportingFI DocRefID and account-record DocRefID
ReportingFI DocRefID is year + FI tax number right-padded to ten characters + FI + three-digit increment, e.g. 201712345678C-FI001. Resending unchanged FI uses the same ID; changing particulars gives a new increment and references the preceding ID. AccountReport DocRefID is year + the maintaining FI’s padded number (or TDT reference) + an FI-assigned unique suffix of up to 30 characters. It uses the FI, not service-provider sender number. Each correction/deletion needs a new unique ID. General XSD maximums do not replace these Singapore formats. Retain the complete chain of accepted identifiers.
Document types: live versus test data
OECD1 is new, OECD2 corrected and OECD3 deleted data. OECD0 only resends ReportingFI for the same reporting year; a new year’s initial FI is OECD1. OECD10, 11, 12 and 13 are resent/new/corrected/deleted test data only during testing, not live submissions. A new-data message cannot mix OECD1 with OECD2/3; a correction message can combine corrections/deletions and an unchanged FI OECD0. Message and record indicators must agree.
Correct whole records and reference the latest accepted version
Only ReportingFI and AccountReport are independently correctable. Changing a child requires the entire relevant parent plus its unchanged children, not a patch containing only the changed field. CorrDocRefID points to the latest accepted DocRefID being replaced/deleted, with a new DocRefID for the replacement. Corrections of corrections point to the preceding correction, not always the original record. Each correction file has a new MessageRefID and CRS702. To cancel a message, delete its records individually; do not use CorrMessageRefID. Tax-residence changes remain the special void-and-new procedure.
Permitted correction combinations and FI deletion
The rendered correction matrix permits the combinations below. No correction message includes an OECD1 account or an OECD0 account. An FI cannot be deleted while any associated AccountReport remains; delete all associated accounts in the same message or beforehand. A correction affecting only FI can omit unchanged accounts.
| FI document type | Permitted associated account data |
|---|---|
| OECD2 corrected FI | No account report, OECD2 accounts or OECD3 accounts |
| OECD3 deleted FI | No account report only if all related accounts already deleted; or OECD3 accounts deleted together |
| OECD0 unchanged FI | OECD2 accounts or OECD3 accounts |
All ten correction scenarios
Adding a child to an existing account is a correction; adding a new account is new data. Child removal is a corrected parent, not deletion of the whole account. The last two examples cover late reporting/split files and do not justify mixing new records into a correction file.
| Example | Change | Required submission |
|---|---|---|
| 1 | Correct payment, then balance of the same account | Each full account replacement points to latest ID; resend unchanged FI OECD0; omit unaffected second account. |
| 2 | Correct FI address, then account payment | First correct FI alone; next resend that latest FI unchanged and correct only affected account. |
| 3 | Change controlling-person address | Replace whole account with number, holder, CP and balance; resend FI. |
| 4 | Change FI address and first account balance | Correct both full records independently; omit untouched second account. |
| 5 | Remove one controlling-person child | OECD2 account retains other CP and all remaining account data; resend FI. |
| 6 | Remove second FI address | OECD2 FI retains name/first address; omit unchanged accounts. |
| 7 | Remove one entire account | OECD3 affected account with children; resend FI; omit other unchanged account. |
| 8 | Add payment child | OECD2 full existing account includes new payment and old children; resend FI. |
| 9 | Add account to existing FI | Separate new-data message: new account OECD1 plus unchanged FI OECD0. |
| 10 | Add new FI and its two accounts | Separate new-data message containing only the new FI and new accounts, all OECD1. |
Version attribute and namespaces
Set CRS_OECD version to 3.0, with target namespace urn:oecd:ties:crs:v3. The schema’s complete major/minor version differs from the namespace, which contains the major version. Dependencies use cfc urn:oecd:ties:commontypesfatcacrs:v2, ftc urn:oecd:ties:fatca:v1, stf urn:oecd:ties:crsstf:v5 and iso urn:oecd:ties:isocrstypes:v1. Appendix B maps them to CrsXML_v3.0.xsd, CommonTypesFatcaCrs_v2.0.xsd, FatcaTypes_v1.2.xsd, OECDCrsTypes_v5.0.xsd and isocrstypes_v1.1.xsd respectively. FATCA namespaces in shared dependencies do not make Sponsor/PoolReport applicable to a CRS return.
Appendix diagrams and final validation
Appendix A’s complete diagrams show root/header/body, FI/group/accounts, individual-or-organisation choice, account-number flags, payment currency, person names/birthplace, structured/free addresses and organisation IDs. They also show non-CRS branches, which must not override IRAS’s exclusions. Follow the XSD sequence rather than the explanatory paragraph order: the account diagram places DDProcedure before AccountType and JointAccount. Check IDs/padding, required choice, string lengths, reason-code evidence, residence/CP report splitting, year-specific new-field values, two-decimal currencies, correction chain and portal message choice. Keep the acknowledgement and wait for acceptance before dependent files.
Official source
This article independently explains the substantive contents of the official PDF, including the relevant conditions, procedures and annexes. The linked document remains the authoritative source for its original wording, and later changes should be checked separately.
Read the official PDF ↗