Annex IV XML Schema Explained for Humans

AIFMReporting
├── AIFMRecordInfo          ← Manager-level data
│   ├── AIFMNationalCode
│   ├── AIFMName
│   ├── AIFMContentType
│   ├── AIFMCompleteDescription   ← Full manager report (24(1))
│   └── AIFMBaseCurrencyDescription
│
├── AIFRecordInfo[]         ← One per fund
│   ├── AIFNationalCode
│   ├── AIFName
│   ├── AIFContentType
│   ├── AIFCompleteDescription
│   │   ├── AIFPrincipalInfo
│   │   │   ├── AIFIdentification
│   │   │   ├── ShareClassIdentification[]
│   │   │   ├── AIFDescription
│   │   │   └── MainInstrumentsTraded[]
│   │   ├── AIFLeverageInfo
│   │   ├── AIFIndividualInfo   ← Only for large funds (>€500M)
│   │   └── ...
│   └── AIFMCompleteDescription
│
└── CancellationAIFMRecordInfo[]  ← Optional cancellations

<FiveRangePercentageType>
  <enumeration value="0%"/>
  <enumeration value="0%-10%"/>
  <enumeration value="10%-25%"/>
  <enumeration value="25%-50%"/>
  <enumeration value="50%-100%"/>
</FiveRangePercentageType>

1. Wrong Content Type for the Reporting Obligation

Cause: You included AIFIndividualInfo (the detailed risk section) but set AIFContentType to 4 instead of 5.

Fix: Match your content type to the actual data you are providing. Content type 5 = 24(2) + 24(4) = full fund-level report including individual info.

2. Invalid Enumeration Values

Cause: Using an ISO country code where the schema expects a custom regional grouping.

Fix: Check the exact enumeration in the XSD. ESMA uses custom geographic groupings (EEA, EUR, AsiaPacific, etc.) in some fields, not ISO country codes.

3. Missing Required Elements

Cause: A required child element is missing. Common culprits: AIFBaseCurrencyDescription, MainInstrumentsTraded, AIFLeverageInfo.

Fix: Cross-reference the XSD to ensure every required element for your content type is present.

4. Decimal Precision Issues

Cause: The schema restricts many monetary values to 2 decimal places.

Fix: Round all monetary values to 2 decimal places before serialization.

5. Empty Optional Blocks

Cause: You included an empty <PrimeBrokers/> element. If you have no prime brokers, omit the element entirely.

Fix: Do not include optional parent elements unless you have data to put in them.

6. LEI Checksum Failures

Cause: LEI has an invalid format or checksum.

Fix: Validate LEIs against the GLEIF database before including them. The last 2 digits are a MOD 97-10 checksum.

curl -X POST https://api.caelith.tech/v1/reports/annex-iv/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reportingPeriod": "2025-Q4",
    "aifm": {
      "name": "Example Capital GmbH",
      "lei": "5493001KJTIIGC8Y1R12",
      "nationalCode": "DE000001234",
      "memberState": "DE"
    },
    "funds": [
      {
        "name": "Example Equity Fund I",
        "nationalCode": "DE000099999",
        "aifType": "PEQF",
        "contentType": 4,
        "baseCurrency": "EUR",
        "nav": 150000000,
        "aum": 180000000,
        "leverage": {
          "grossMethod": 105.5,
          "commitmentMethod": 102.3
        },
        "strategy": {
          "type": "PEQF_VENT",
          "predominant": true
        }
      }
    ]
  }'

import requests

API_KEY = "your_api_key"
BASE_URL = "https://api.caelith.tech/v1"

payload = {
    "reportingPeriod": "2025-Q4",
    "aifm": {
        "name": "Example Capital GmbH",
        "lei": "5493001KJTIIGC8Y1R12",
        "nationalCode": "DE000001234",
        "memberState": "DE"
    },
    "funds": [
        {
            "name": "Example Equity Fund I",
            "nationalCode": "DE000099999",
            "aifType": "PEQF",
            "contentType": 4,
            "baseCurrency": "EUR",
            "nav": 150_000_000,
            "aum": 180_000_000,
            "leverage": {
                "grossMethod": 105.5,
                "commitmentMethod": 102.3
            },
            "strategy": {
                "type": "PEQF_VENT",
                "predominant": True
            }
        }
    ]
}

response = requests.post(
    f"{BASE_URL}/reports/annex-iv/generate",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json=payload
)

result = response.json()

if result["status"] == "valid":
    xml_content = result["xml"]
    with open("annex_iv_2025_q4.xml", "w") as f:
        f.write(xml_content)
    print(f"Valid XML generated - {len(result['validation']['warnings'])} warnings")
else:
    for error in result["validation"]["errors"]:
        print(f"Error: {error}")

const API_KEY = process.env.CAELITH_API_KEY!;
const BASE_URL = "https://api.caelith.tech/v1";

async function generateAnnexIV(payload: AnnexIVRequest) {
  const response = await fetch(
    `${BASE_URL}/reports/annex-iv/generate`,
    {
      method: "POST",
      headers: {
        Authorization: `Bearer ${API_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(payload),
    }
  );

  const result = await response.json();

  if (result.status === "valid") {
    console.log("Valid XML generated");
    return result.xml;
  } else {
    console.error("Validation errors:", result.validation.errors);
    throw new Error("XML validation failed");
  }
}