The CARF XML schema defines the standardized format for reporting crypto-asset transactions to tax authorities. This comprehensive technical guide covers schema structure, elements, validation rules, and implementation best practices.

Schema Overview

The CARF XML schema is based on the OECD Common Reporting Standard (CRS) schema with crypto-specific extensions. Key characteristics:

  • XML version: 1.0 compliant
  • Encoding: UTF-8 required
  • Namespace: urn:oecd:ties:carf:v1
  • Elements: Namespace-qualified
  • Validation: Strict XSD validation required
Schema Files

Official CARF XML schema files are available from the OECD. Jurisdictions may provide adapted schemas with local requirements. Always use the schema version specified by your target jurisdiction.

Root Structure

CARF_OECD Element

The top-level container element containing all report data:

<?xml version="1.0" encoding="UTF-8"?>
<CARF_OECD xmlns="urn:oecd:ties:carf:v1"
           xmlns:stf="urn:oecd:ties:stf:v4"
           version="1.0">
    <MessageSpec>...</MessageSpec>
    <CARFBody>...</CARFBody>
</CARF_OECD>

MessageSpec Element

Header information identifying the report:

Element Description Required
SendingCompanyIN Reporting entity identifier Yes
TransmittingCountry ISO 3166-1 alpha-2 code Yes
ReceivingCountry Target jurisdiction code Yes
MessageType CARF (new) or CARF_C (correction) Yes
MessageRefId Unique message identifier Yes
ReportingPeriod Year being reported (YYYY-12-31) Yes
Timestamp Report generation time Yes

User Elements

Individual (Natural Person)

<Individual>
    <Name>
        <FirstName>John</FirstName>
        <MiddleName>William</MiddleName>
        <LastName>Smith</LastName>
    </Name>
    <Address>
        <CountryCode>DE</CountryCode>
        <AddressFree>123 Main Street, Berlin 10115</AddressFree>
    </Address>
    <TIN issuedBy="DE">12345678901</TIN>
    <BirthDate>1985-03-15</BirthDate>
    <BirthPlace>
        <City>Munich</City>
        <CountryInfo>
            <CountryCode>DE</CountryCode>
        </CountryInfo>
    </BirthPlace>
</Individual>

Organisation (Legal Entity)

<Organisation>
    <Name>Crypto Trading GmbH</Name>
    <Address>
        <CountryCode>DE</CountryCode>
        <AddressFree>456 Business Ave, Frankfurt 60311</AddressFree>
    </Address>
    <TIN issuedBy="DE">DE123456789</TIN>
    <OrganisationType>CORP</OrganisationType>
</Organisation>

Transaction Elements

Transaction Types

CARF defines four reportable transaction types:

Type Code Description Example
CARF501 Exchange: Crypto to Fiat Selling BTC for EUR
CARF502 Exchange: Fiat to Crypto Buying ETH with USD
CARF503 Exchange: Crypto to Crypto Trading BTC for ETH
CARF504 Transfer to External Wallet Withdrawal to self-custody
CARF505 Retail Payment Crypto payment for goods

RelevantTransactions Structure

<RelevantTransactions>
    <TransactionType>CARF501</TransactionType>
    <CryptoAsset>
        <CryptoAssetCode>BTC</CryptoAssetCode>
        <CryptoAssetName>Bitcoin</CryptoAssetName>
    </CryptoAsset>
    <AggregateGrossProceeds>
        <Amount currCode="EUR">50000.00</Amount>
    </AggregateGrossProceeds>
    <NumberOfUnits>1.25000000</NumberOfUnits>
    <NumberOfTransactions>15</NumberOfTransactions>
</RelevantTransactions>

Validation Rules

Reports must pass both schema validation and business rule validation:

Schema Validation

  • All mandatory elements must be present
  • Element order must match schema definition
  • Data types must match (string, decimal, date, etc.)
  • Enumeration values must be from allowed lists

Business Rule Validation

  • TIN format: Must match jurisdiction-specific rules
  • Country codes: ISO 3166-1 alpha-2
  • Currency codes: ISO 4217
  • Dates: ISO 8601 format (YYYY-MM-DD)
  • Amounts: Decimal with appropriate precision
  • MessageRefId: Must be globally unique
Common Validation Errors

Most rejections occur due to: invalid TIN formats, incorrect date formats, missing mandatory elements, or invalid enumeration values. Always validate locally before submission.

Correction Reports

When errors are discovered after submission:

Correction Types

  • CARF_C: Correction to previously submitted data
  • DocRefId: Reference to original record
  • CorrDocRefId: ID of the correction record

Correction Codes

Code Meaning
OECD1 Resend (replaces entire record)
OECD2 Delete (removes record)
OECD3 Resend correcting specific data

Implementation Best Practices

  • Use XML libraries with built-in schema validation
  • Test against official OECD schema files
  • Implement pre-submission validation pipeline
  • Handle special characters properly (XML entities)
  • Generate unique MessageRefId and DocRefId values
  • Store original reports for correction reference
  • Log all validation errors for debugging
  • Build automated retry logic for transmission failures

Character Encoding

Properly escape special characters:

  • & → &amp;
  • < → &lt;
  • > → &gt;
  • " → &quot;
  • ' → &apos;

Conclusion

Mastering the CARF XML schema is essential for successful reporting. Use official schema files, implement thorough validation, and test extensively before production submission. Schema compliance is the foundation of successful CARF reporting.

Automate CARF Compliance

Self-certification, TIN validation, transaction reporting, and XML generation for 76 jurisdictions.

Expert Consulting