Kutengeneza XML kwa XSD v5 ya goAML: mwongozo kamili wa kiufundi

Ikiwa umewahi kujaribu kujenga ripoti ya XML ya goAML kuanzia mwanzo kabisa, tayari unajua kwamba mchakato huo ni mgumu zaidi kuliko unavyoonekana mwanzoni. Skima ya goAML ya Ofisi ya Umoja wa Mataifa ya Kupambana na Dawa za Kulevya na Uhalifu (UNODC), toleo la 5.0.2, inafafanua zaidi ya elementi 200, nyingi zikiwa na masharti makali ya orodha za thamani zinazoruhusiwa (enumeration), zote zikiwa zimepangwa katika mfumo wa kidaraja wa elementi nyingi zilizo ndani ya nyingine, na seti tofauti za elementi za lazima kutegemea kama unatengeneza taarifa ya miamala ya fedha taslimu (CTR) au taarifa ya miamala yenye mashaka (STR). Kisha vitengo vya taarifa za kifedha (FIU) vya kila nchi huongeza masharti ya ziada ya uthibitishaji juu ya skima ya msingi — na masharti hayo hubadilika.

Majaribio mengi ya kwanza ya kutengeneza XML ya goAML hushindwa wakati wa kuwasilisha. Ripoti inaonekana sahihi katika kihariri cha maandishi. XML ina muundo sahihi (well-formed). Lakini lango la FIU hurudisha kosa la uthibitishaji kwa sehemu iliyo ngazi tatu ndani ya mpangilio wa wahusika, iliyoandikwa kwa muundo sahihi kwa kila nchi nyingine isipokuwa hii. Msanidi programu hufanya marekebisho, hutengeneza faili upya, huwasilisha upya, na hukutana na kosa jingine. Mzunguko huu wa kurudia unaweza kuchukua siku kadhaa.

Mwongozo huu umeandikwa kwa ajili ya mameneja wa TEHAMA, wasanidi programu na wasanifu wa mifumo wanaohusika na kujenga au kutathmini uwezo wa kutengeneza XML ya goAML. Unashughulikia muundo wa skima, maeneo ya kawaida ya kushindwa, nyongeza mahususi za nchi, na usanifu wa mchakato imara wa kutengeneza XML (pipeline).

---

Muhtasari wa skima ya XML ya goAML v5.0.2

Historia ya skima ya goAML

Programu ya goAML ya UNODC imepitia marekebisho kadhaa makubwa ya skima tangu ilipoanza kusimikwa katikati ya miaka ya 2000. Toleo la 3 la skima ndilo lililotumika zaidi miongoni mwa waliotangulia kuitumia, na bado linapatikana katika usimikaji wa zamani wa baadhi ya FIU. Toleo la 4 lilileta mabadiliko makubwa ya kimuundo katika elementi za miamala na za wahusika, likiboresha uwezo wa kushughulikia miundo tata ya umiliki na miamala ya kuvuka mipaka.

Toleo la 5.0.2 — toleo la sasa lililosimikwa katika FIU za nchi zote tano wanachama wa ESAAMLG (Kundi la Mashariki na Kusini mwa Afrika la Kupambana na Utakatishaji Fedha Haramu) — lilileta maboresho zaidi ya kimuundo, likapanua orodha za thamani zinazoruhusiwa kwa aina za miamala na aina za hati za utambulisho, na likarasimisha utaratibu wa nyongeza ambao FIU za nchi huutumia kuweka masharti ya ziada ya uthibitishaji zaidi ya skima ya msingi ya UNODC.

Jambo la msingi ni kwamba UNODC inapotoa sasisho la XSD, si kila mara mabadiliko hayo yanaendana na matoleo ya awali (backward-compatible). Msimbo uliotengeneza XML halali ya v4 unaweza kutengeneza XML isiyo halali ya v5 kwa michanganyiko fulani ya elementi. Utekelezaji wowote wa kutengeneza XML lazima ufungamanishwe na toleo halisi la skima lililosimikwa na FIU lengwa, na usasishwe FIU hiyo inapohamia toleo jipya.

Muundo wa skima: Report → Transaction → Party → Account → ID Document → Address

Mpangilio wa kidaraja wa hati ya XML ya goAML unafuata muundo wa kimantiki unaoakisi ripoti halisi ya taarifa za kiintelijensia za kifedha:

Report (ripoti) ndiyo elementi ya msingi. Ina utambulisho wa taasisi inayoripoti, metadata ya uwasilishaji (data kuhusu uwasilishaji wenyewe), taarifa za mtu anayeripoti, na rekodi moja au zaidi za miamala.

Elementi za Transaction (muamala) ziko moja kwa moja chini ya Report. Kila muamala una aina, kiasi, sarafu, tarehe na maelezo. Ripoti moja inaweza kuwa na miamala kadhaa — jambo la kawaida katika ripoti za CTR ambapo mteja amefanya miamala kadhaa ya fedha taslimu katika kipindi cha kuripoti.

Elementi za Party (mhusika) zinaeleza watu binafsi au taasisi za kisheria zinazohusika katika muamala. Wahusika huunganishwa na miamala kupitia elementi za from_person, to_person, from_entity na to_entity, ambazo kila moja ina rekodi ya mhusika ndani yake. Mhusika anayejitokeza katika miamala kadhaa anaweza kurejelewa kwa kitambulisho (ID) badala ya kurudiwa kikamilifu katika kila muamala.

Elementi za Account (akaunti) hunasa akaunti za kifedha zinazohusika — namba za akaunti za benki, misimbo ya aina, na taasisi ya fedha inayoshikilia akaunti. Akaunti huunganishwa na upande husika wa muamala (from_account, to_account).

Elementi za ID Document (hati ya utambulisho) ziko ndani ya rekodi za watu binafsi na hunasa kitambulisho cha taifa, pasipoti, leseni ya udereva na hati nyingine za kuthibitisha utambulisho. National ID ni ya lazima kwa watu wa Kenya chini ya kanuni za uthibitishaji za Financial Reporting Centre (FRC).

Elementi za Address (anwani) hunasa anwani za makazi au za posta za watu binafsi na taasisi. Kanuni za uthibitishaji wa anwani hutofautiana kati ya nchi — baadhi ya FIU zinahitaji maelezo hadi ngazi ya mtaa; nyingine hukubali nchi pekee kwa wahusika wasio wakazi.

Tofauti za skima kati ya STR na CTR

Ingawa muundo wa msingi wa skima unashirikiwa kati ya taarifa za miamala yenye mashaka na taarifa za miamala ya fedha taslimu, kuna tofauti za maana kuhusu elementi zipi ni za lazima, za hiari au zilizokatazwa:

Ripoti za CTR zinahitaji transaction_amount yenye usahihi kamili wa desimali, CASH kama aina ya muamala, na taarifa kamili za akaunti pande zote mbili za muamala. Kiasi cha kiwango cha CTR na msimbo wa sarafu lazima viendane kikamilifu na kiwango kilichotangazwa katika wasifu wa nchi (country profile). Miamala kadhaa ya fedha taslimu katika kipindi kimoja cha kuripoti inaweza kuunganishwa katika CTR moja.

Ripoti za STR zinahitaji alama ya is_suspicious iwekwe kuwa true, elementi ya reason isiyo tupu inayoeleza kwa nini muamala una mashaka, maandishi ya maelezo yenye urefu na maudhui ya maana, angalau msimbo mmoja wa kiashiria unaorejelea mbinu inayojulikana ya utakatishaji fedha haramu (typology) kutoka kwenye orodha ya viashiria ya FIU, na taarifa za reporting_person. Elementi za miamala katika STR zinaweza kujumuisha miamala isiyo ya fedha taslimu na mienendo ya kugawanya miamala (structuring) ambamo kila muamala, ukichukuliwa peke yake, uko chini ya viwango vya CTR.

Kupakua XSD rasmi kutoka UNODC

UNODC hutoa faili za skima ya XSD ya goAML kupitia lango lake rasmi la nyaraka za goAML. Chanzo rasmi cha faili za XSD, maelezo ya matoleo (release notes) na miongozo ya uthibitishaji ni ukurasa wa bidhaa ya goAML wa UNODC. Nyaraka za lango la FIU ya kila nchi zinapaswa pia kusomwa, kwa sababu FIU huchapisha nyongeza za skima mahususi za nchi na nyaraka za kanuni za uthibitishaji sambamba na skima ya msingi ya UNODC.

Inapendekezwa sana kupakua XSD moja kwa moja kutoka kwenye lango la FIU ya nchi unayolenga badala ya kutumia chanzo cha mtu mwingine, kwa sababu nyongeza za nchi hubadilisha skima ya msingi kwa njia ambazo si kila mara zinaelezwa katika nyaraka za jumla.

---

Muundo wa hati ya XML ya goAML

Ufuatao ni mfano wenye maelezo wa ripoti ya CTR ya goAML v5.0.2 yenye muundo sahihi, kwa taasisi ya kubuni ya Kenya inayowajibika kuripoti. Data zote za taasisi na za watu ni za kubuni kabisa.

<?xml version="1.0" encoding="UTF-8"?>
<Report xmlns="http://goaml.unodc.org/goaml/en">
  <!-- Reporting entity identification — must match FIU registration exactly -->
  <rentity_id>KE-FRC-12345</rentity_id>
  <rentity_branch>NAIROBI-HQ</rentity_branch>

  <!-- Submission metadata -->
  <submission_code>E</submission_code>          <!-- E = Electronic -->
  <report_code>CTR</report_code>                <!-- CTR or STR -->
  <entity_reference>CTR-2026-0001</entity_reference>  <!-- Internal reference -->
  <fiu_ref_number></fiu_ref_number>             <!-- Blank on first submission; FIU populates on acceptance -->
  <submission_date>2026-03-25</submission_date>  <!-- YYYY-MM-DD strictly required -->
  <currency_code_local>KES</currency_code_local> <!-- ISO 4217 currency code -->

  <!-- Reporting person — the compliance officer or designated MLRO -->
  <reporting_person>
    <gender>M</gender>               <!-- M or F — not Male/Female -->
    <title>Mr</title>
    <first_name>James</first_name>
    <last_name>Mwangi</last_name>
    <birthdate>1980-05-15</birthdate>  <!-- YYYY-MM-DD — not optional for Kenya FRC -->
    <id_number>12345678</id_number>    <!-- National ID of reporting person -->
    <!-- Address and phone elements follow here -->
  </reporting_person>

  <!-- One or more transaction elements -->
  <transaction>
    <transactionnumber>TXN-2026-00123</transactionnumber>
    <transaction_location>NAIROBI-CBD-BRANCH</transaction_location>
    <date_transaction>2026-03-24</date_transaction>  <!-- Date of transaction -->
    <teller>T001</teller>                             <!-- Teller/officer ID -->
    <currency_amount>
      <amount>1250000.00</amount>    <!-- Exactly 2 decimal places required -->
      <currency_code>KES</currency_code>
    </currency_amount>

    <!-- Transaction type — must be valid enumeration value from XSD -->
    <transaction_type>CASH_DEPOSIT</transaction_type>

    <!-- The depositing party (from side) -->
    <from_person>
      <gender>F</gender>
      <title>Ms</title>
      <first_name>Wanjiru</first_name>
      <last_name>Kamau</last_name>
      <birthdate>1985-11-20</birthdate>
      <id_number>87654321</id_number>
      <id_type>NATIONAL_ID</id_type>   <!-- Enumeration — must match XSD allowed values -->
      <address>
        <address_type>HOME</address_type>
        <city>Nairobi</city>
        <country>KE</country>  <!-- ISO 3166-1 alpha-2 -->
      </address>
    </from_person>

    <!-- The receiving account (to side) -->
    <to_account>
      <institution_name>First National Bank Kenya</institution_name>
      <institution_code>KE-FRC-12345</institution_code>
      <account>
        <account_number>1234567890</account_number>
        <account_name>Wanjiru Kamau</account_name>
        <account_type>SAVINGS</account_type>  <!-- Enumeration -->
        <currency_code>KES</currency_code>
        <opened>2022-06-15</opened>
      </account>
    </to_account>
  </transaction>

</Report>

Mfano huu unaonyesha masharti kadhaa muhimu ya muundo yanayojadiliwa kwa kina katika sehemu zinazofuata. Muundo huu ni sahihi kwa CTR ya msingi, lakini ripoti za mazingira halisi ya uendeshaji (production) zinahitaji elementi za ziada kwa mienendo tata ya miamala, wahusika wengi, na ripoti zenye miamala kadhaa.

---

Elementi za lazima na za hiari kwa kila aina ya ripoti

Jedwali lifuatalo linaonyesha elementi kuu na masharti yake kwa aina za ripoti za CTR na STR. Nyongeza mahususi za FIU zimetajwa lakini hazijaorodheshwa zote — daima rejelea nyaraka za sasa za uthibitishaji za nchi husika.

---

Changamoto za kawaida katika kutengeneza XML

Matatizo ya usimbaji: UTF-8 bila BOM

Malango ya goAML yanajulikana kwa ukali wao kuhusu usimbaji wa herufi. Tamko la XML lazima libainishe usimbaji wa UTF-8, na faili lazima ihifadhiwe kama UTF-8 bila alama ya mpangilio wa baiti (Byte Order Mark — BOM). Maktaba za XML zinazolenga Windows mara nyingi huandika BOM ya UTF-8 kwa chaguo-msingi, jambo linalosababisha lango la goAML kukataa uwasilishaji kwa kosa la usimbaji ambalo mara nyingi hutambuliwa vibaya kama kosa la skima.

Ikiwa XML yako inatengenezwa kwenye mfumo wa Windows kwa kutumia XmlWriter ya .NET, hakikisha unaunda writer kwa new UTF8Encoding(false) — kigezo false huzuia waziwazi BOM kuandikwa. Katika Python, tumia encoding='utf-8' bila toleo la utf-8-sig. Hii ni mojawapo ya hitilafu za kimyakimya zinazojitokeza zaidi katika utekelezaji wa mwanzo wa kutengeneza XML.

Ukali wa muundo wa tarehe: YYYY-MM-DD kila mara

Kila sehemu ya tarehe katika skima ya goAML inahitaji muundo wa ISO 8601: YYYY-MM-DD. Mifumo mikuu ya benki (core banking) ya Afrika Mashariki mara nyingi huhifadhi na kuhamisha tarehe katika muundo wa DD/MM/YYYY, ambao ndio muundo unaosomwa na watu unaotumika zaidi katika kanda hii. Tabaka la kubadilisha data lazima lisawazishe data zote za tarehe zinazoingia kabla hazijaingia kwenye mchakato wa kutengeneza XML.

Tarehe zilizohifadhiwa kama namba za mfuatano za Excel (jambo la kawaida katika faili za CSV zinazohamishwa kutoka baadhi ya mifumo mikuu ya benki) zinahitaji ubadilishaji wa aina tofauti. Tarehe 1 Januari 1900 ni namba ya mfuatano 1 katika mfumo wa tarehe wa Excel; tarehe 25 Machi 2026 ni namba ya mfuatano 46106. Mfumo wowote wa kutengeneza XML unaotumia data ya miamala iliyohamishwa kutoka Excel lazima ushughulikie ubadilishaji huu waziwazi.

Usahihi wa desimali: nafasi mbili kamili za desimali

Elementi za kiasi lazima ziandikwe zikiwa na nafasi mbili kamili za desimali. Kiasi cha KES 1,250,000 lazima kionekane kama 1250000.00, si 1250000, si 1,250,000.00 (bila kitenganishi cha maelfu), na si 1250000.0. XSD inafafanua elementi za kiasi kama xs:decimal yenye sharti la fractionDigits la 2. Kiasi kinachotokana na hesabu za kugawanya katika msimbo lazima kikadiriwe (rounded) na kupangwa waziwazi kabla ya kuingizwa kwenye XML.

Sehemu za boolean: true/false kwa herufi ndogo

Elementi ya is_suspicious na sehemu nyingine za boolean katika skima ya goAML hutumia aina ya boolean ya XML Schema, inayokubali true na false (herufi ndogo) au 1 na 0. Wasanidi programu wengi, hasa wale wanaofanya kazi kwa lugha za programu ambazo uwakilishi wa boolean hautofautishi herufi kubwa na ndogo, bila kukusudia hutengeneza True, False, TRUE au FALSE — na zote hizo hushindwa uthibitishaji wa skima. Baadhi ya malango ya goAML hukubali 1/0 lakini hili hutofautiana; daima tumia true/false ili kupata upatanifu wa juu kabisa.

Masharti ya orodha za thamani zinazoruhusiwa: aina za miamala na za vitambulisho

Skima ya goAML inafafanua orodha kali za thamani zinazoruhusiwa (enumeration) kwa elementi zikiwemo transaction_type, id_type, account_type, gender, address_type na submission_code. Kila thamani inayoingizwa katika elementi hizi lazima ilingane kikamilifu na mojawapo ya thamani zinazoruhusiwa zilizofafanuliwa katika XSD. Ikiwa mfumo wako mkuu wa benki unatumia majedwali tofauti ya misimbo — kwa mfano, kuhifadhi aina za miamala kama misimbo ya tarakimu kama 01, 02, 03 — tabaka la kuoanisha misimbo linahitajika ili kuzibadilisha kuwa thamani za enumeration za goAML kabla ya kutengeneza XML.

Uoanishaji huu pia ni mahususi kwa kila nchi. Skima iliyopanuliwa ya FRC ya Kenya inaongeza thamani za ziada za aina za miamala kwa njia za pesa kwa simu (MOBILE_WALLET_MPESA, MOBILE_WALLET_AIRTEL, MOBILE_WALLET_TKASH) ambazo hazimo katika skima ya msingi ya UNODC. Kutengeneza ripoti yenye aina ya muamala ya skima ya msingi kwa muamala wa pesa kwa simu unaowasilishwa kwa FRC ya Kenya kutapita uthibitishaji wa XSD ya msingi lakini kutashindwa uthibitishaji wa ngazi ya nchi.

Nafasi tupu na elementi tupu

Skima ya goAML ina kanuni mahususi kuhusu elementi tupu ikilinganishwa na elementi zisizokuwepo. Kwa elementi za hiari zisizo na thamani, njia sahihi ni kuiacha elementi kabisa nje ya XML inayotengenezwa — si kuweka tagi tupu. <fiu_ref_number></fiu_ref_number> kiufundi ni XML yenye muundo sahihi, lakini baadhi ya malango ya goAML huikataa kama isiyokidhi skima pale elementi imefafanuliwa kuwa na sharti la minLength la 1. Tabia sahihi ni kuacha fiu_ref_number kabisa pale hakuna thamani ya kujaza.

Kwa upande mwingine, elementi za lazima zenye thamani hazipaswi kuwa na nafasi tupu mwanzoni au mwishoni. <institution_code> KE-FRC-12345 </institution_code> itashindwa uthibitishaji katika malango yenye ukali. Thamani zote za maandishi zinapaswa kuondolewa nafasi tupu za mwanzo na mwisho kabla ya kuingizwa.

---

Nyongeza za XML mahususi kwa nchi

Jinsi FRC ya Kenya inavyopanua XSD ya msingi

Financial Reporting Centre ya Kenya huchapisha wasifu wa uthibitishaji (validation profile) unaopanua XSD ya msingi ya UNODC kwa masharti ya ziada ya lazima. Nyongeza muhimu zaidi mahususi kwa Kenya ni:

Sharti la National ID: Kwa raia yeyote wa Kenya anayejitokeza kama from_person au to_person katika ripoti, elementi za id_number na id_type ni za lazima — si za hiari kama zilivyo katika skima ya msingi. Thamani ya id_type lazima iwe NATIONAL_ID kwa raia wa Kenya. Raia wa kigeni lazima watoe PASSPORT.

Uainishaji wa njia za pesa kwa simu: Miamala inayohusisha M-PESA, Airtel Money au T-Kash lazima itumie thamani za enumeration zilizopanuliwa za transaction_type za FRC (MOBILE_WALLET_MPESA, MOBILE_WALLET_AIRTEL, MOBILE_WALLET_TKASH) na lazima ijumuishe elementi ya mobile_money_agent_code pale muamala ulipofanywa kupitia wakala.

Sharti la tarehe ya kuzaliwa ya mtu anayeripoti: Ingawa skima ya msingi ya UNODC huchukulia birthdate kuwa ya hiari kwa elementi ya reporting_person, kanuni za uthibitishaji za FRC ya Kenya huifanya kuwa ya lazima. Ripoti zisizo na tarehe ya kuzaliwa ya mtu anayeripoti hukataliwa.

Kiwango cha CTR: Kiwango cha CTR nchini Kenya ni USD 15,000 au kiasi kinacholingana nacho katika sarafu nyingine yoyote, chini ya kifungu cha 44(6) cha POCAMLA na kanuni ya 40(1) ya POCAMLR 2023 (FRC Circular No. 4 of 2023). Kila muamala mmoja wa fedha taslimu ulio sawa na au zaidi ya kiwango hicho lazima uripotiwe, huku kiasi katika sarafu ya asili, kiwango cha ubadilishaji kilichotumika na kiasi kinacholingana kwa USD vikinaswa katika XML ya CTR. Shughuli za siku moja zilizo chini ya kiwango hazijumlishwi kuwa CTR; pale zinapoonekana kuwa ugawanyaji wa miamala ili kukwepa kiwango (structuring), taasisi huwasilisha STR.

Nyongeza za FIC ya Zambia

Financial Intelligence Centre (FIC) ya Zambia hutumia wasifu wake wa uthibitishaji juu ya skima ya msingi ya UNODC. Tofauti kuu ikilinganishwa na Kenya ni pamoja na msimbo wa sarafu (ZMW), viwango tofauti vya CTR, na orodha za thamani za aina za miamala mahususi kwa Zambia. FIC pia inahitaji Business Registration Number (namba ya usajili wa biashara) kwa wahusika walio taasisi, ambayo huoanishwa na sehemu tofauti na ile inayopendelewa na FRC ya Kenya.

Taasisi zinazopanua shughuli kutoka Kenya kwenda Zambia haziwezi kutumia tena injini ya kutengeneza XML iliyosanidiwa kwa Kenya bila kubadilisha usanidi wa wasifu wa uthibitishaji.

Kwa nini kiolezo kimoja cha XML hakifanyi kazi katika nchi zote

Hii ndiyo sababu kuu inayofanya vitengeneza XML vya goAML vilivyo tayari sokoni (off-the-shelf), vilivyojengwa kwa ajili ya nchi moja, kushindwa vinaposimikwa katika mazingira ya nchi kadhaa. XSD ya msingi ya UNODC hutoa muundo wa jumla. Kisha FIU za nchi hutumia kanuni za uthibitishaji zinazobadilisha elementi zipi ni za lazima, zinazopanua orodha za thamani zinazoruhusiwa, na zinazoongeza elementi mpya kabisa mahususi kwa nchi. Kiolezo kilichoandikwa mahususi kwa ajili ya FRC ya Kenya kitatengeneza XML isiyo halali kwa FIA ya Uganda, na kinyume chake.

Injini ya kutengeneza XML ya nchi nyingi kwa mazingira halisi ya uendeshaji lazima iendeshwe na wasifu wa usanidi mahususi kwa kila nchi, unaotangaza kanuni za uthibitishaji zinazotumika, sehemu za lazima, nyongeza za orodha za thamani, na taarifa za anwani za kuwasilisha (endpoint) za FIU kwa kila nchi lengwa.

---

Uthibitishaji wa XSD ndani ya msimbo

Uthibitishaji wa skima ya XML katika .NET kwa kutumia XmlSchemaSet

Katika .NET, uthibitishaji wa XSD ya goAML hufanywa kwa kutumia darasa la System.Xml.Schema.XmlSchemaSet pamoja na XmlReader iliyosanidiwa kwa mipangilio ya uthibitishaji. Mchakato hupakia faili ya XSD (au faili kadhaa, ikiwa nyongeza ya nchi ni XSD tofauti inayowekwa juu ya ile ya msingi), huiongeza kwenye seti ya skima, na huthibitisha hati ya XML iliyotengenezwa dhidi yake kabla ya kujaribu kuwasilisha.

Makosa ya uthibitishaji huonyeshwa kupitia callback ya ValidationEventHandler, ambayo inapaswa kunasa ujumbe kamili wa kosa, namba ya mstari katika XML chanzo, na njia (path) ya elementi katika skima. Vipande hivi vitatu vya taarifa ni muhimu kwa kutambua ni sehemu gani ya muundo wa ripoti iliyoshindwa uthibitishaji na kwa nini. Utekelezaji wa mazingira halisi ya uendeshaji unapaswa kurekodi makosa yote ya uthibitishaji pamoja na muktadha kamili wa ripoti ili kuwezesha utambuzi na urekebishaji wa haraka.

Hatua ya uthibitishaji lazima ifanyike baada ya utengenezaji wa XML kukamilika lakini kabla hati haijageuzwa (serialise) kuwa maudhui ya uwasilishaji. Kujaribu kuthibitisha katikati ya utengenezaji (wakati hati bado inajengwa) huzalisha makosa ya kupotosha, kwa sababu elementi za lazima zitakazoongezwa baadaye huwekewa alama kuwa hazipo.

Uthibitishaji kwa lxml ya Python

Wasanidi programu wa Python wanaotumia maktaba ya lxml wanaweza kutumia darasa la lxml.etree.XMLSchema kwa uthibitishaji unaotegemea XSD. Utaratibu ni kuchanganua faili ya XSD kuwa kitu (object) cha XMLSchema, kisha kuita .validate() dhidi ya mti wa hati uliotengenezwa. Sifa (attribute) ya XMLSchema.error_log hutoa orodha kamili ya makosa ya uthibitishaji pamoja na taarifa za njia (path).

Jambo moja fiche katika lxml: maktaba hii ni kali kuhusu ushughulikiaji wa namespace (nafasi ya majina). Tamko la xmlns la skima ya goAML lazima lionekane kwenye elementi ya msingi na lilingane kikamilifu na namespace iliyotangazwa katika XSD. Kosa la kawaida ni kutengeneza faili ya XML yenye URI ya namespace inayotofautiana kidogo (kwa mfano, yenye mkwaju mwishoni, au yenye en badala ya EN), jambo linalosababisha skima kushindwa kwa kosa la "no matching global element declaration" badala ya kosa mahususi la ngazi ya sehemu.

Mbinu ya JAXB binding ya Java

Wasanidi programu wa Java wanaofanya kazi na goAML kwa kawaida hutumia JAXB (Java Architecture for XML Binding) kutengeneza madarasa ya Java (class bindings) moja kwa moja kutoka kwenye XSD. Kikusanyaji xjc husoma XSD na kutoa madarasa ya Java yenye maelezo (annotations) kwa kila aina ya skima, pamoja na msimbo wa marshalling na unmarshalling. Kutengeneza ripoti kisha kunakuwa suala la kujenga mitandao ya vitu (object graphs) vya Java na kuvigeuza kuwa XML (marshalling) — marshaller ya JAXB hutumia masharti ya skima kiotomatiki wakati wa kugeuza data kuwa XML (serialisation).

Mbinu ya JAXB ina faida ya usalama wa aina za data wakati wa kukusanya msimbo (compile-time type safety): sehemu zenye aina isiyo sahihi au thamani za lazima zinazokosekana huwa makosa ya kikusanyaji badala ya kushindwa kwa uthibitishaji wakati programu inaendeshwa. Hasara yake ni kwamba kutengeneza upya madarasa ya JAXB pale XSD inapobadilika kunahitaji kukusanya upya na kusimika upya msimbo unaotegemea madarasa hayo.

Zana za mtandaoni za uthibitishaji wa XSD kwa majaribio

Wakati wa uundaji wa programu na majaribio ya masasisho ya skima, zana za mtandaoni za uthibitishaji wa XSD hutoa mrejesho wa haraka bila kuhitaji mazingira ya uundaji kwenye kompyuta yako. Zana kama FreeFormatter.com na XMLValidation.com hupokea faili za XSD na XML zinazopakiwa na hurudisha jumbe za kina za makosa ya uthibitishaji. Zinafaa kwa ukaguzi wa haraka wa awali, lakini hazipaswi kuchukua nafasi ya uthibitishaji wa kiotomatiki katika mchakato wa usimikaji (deployment pipeline) — zana za mtandaoni huenda zisiauni vipengele vyote vya skima ya XSD, na data nyeti za wateja hazipaswi kamwe kupakiwa kwenye vikagua vya umma.

---

Kujenga mchakato imara wa kutengeneza XML

Mchakato wa kutengeneza XML ya goAML wenye ubora wa mazingira halisi ya uendeshaji una matabaka matano tofauti, kila moja likiwa na jukumu mahususi.

1. Tabaka la kusawazisha data

Data ya miamala inayoingia kutoka kwenye mifumo mikuu ya benki huja katika miundo isiyoweza kutumika moja kwa moja katika XML ya goAML. Tabaka la kusawazisha hushughulikia ubadilishaji wa muundo wa tarehe (DD/MM/YYYY → YYYY-MM-DD), kusawazisha usahihi wa kiasi, kuweka usimbaji wa herufi katika kiwango kimoja, na kuondoa herufi maalum zisizoruhusiwa katika XML (baiti tupu — null bytes, baadhi ya herufi za udhibiti). Pia hukata urefu wa sehemu pale data inayoingia inapozidi urefu wa juu uliofafanuliwa katika skima.

2. Tabaka la uthibitishaji wa kanuni za kibiashara

Kabla utengenezaji wa XML haujaanza, tabaka la uthibitishaji wa kanuni za kibiashara hukagua kwamba data ya kesi iliyokusanywa inatimiza masharti yote ya kimaana kwa aina ya ripoti husika. Kwa CTR: je, kiasi cha muamala ni sawa na au zaidi ya kiwango? Je, namba ya akaunti ipo? Je, aina ya muamala ni aina ya muamala wa fedha taslimu? Kwa STR: je, kuna angalau msimbo mmoja wa kiashiria? Je, maelezo si tupu na yana urefu wa kutosha? Je, is_suspicious imewekwa ipasavyo?

Kugundua makosa ya kimaana katika tabaka hili, kabla ya kutengeneza XML, huzalisha jumbe za makosa zenye manufaa zaidi kuliko kuyagundua kama makosa ya uthibitishaji wa XSD baada ya utengenezaji.

3. Tabaka la kutengeneza XML

Tabaka la kutengeneza XML huchukua data iliyosawazishwa na kuthibitishwa kwa kanuni za kibiashara na kujenga hati ya XML ya goAML. Builders zinazozingatia skima — madarasa au vitendakazi (classes au functions) vinavyojenga elementi mahususi za skima kutoka kwenye vitu vya muundo wa data — ndizo mtindo wa usanifu unaopendekezwa. Kila builder huwajibika kwa aina moja ya elementi (PersonBuilder, AccountBuilder, TransactionBuilder) na hutumia mpangilio unaofaa, uoanishaji wa enumeration, na mantiki ya kujumuisha au kuacha elementi kulingana na wasifu wa nchi lengwa.

XML iliyotengenezwa inapaswa kugeuzwa kuwa mfuatano wa maandishi (string) au safu ya baiti (byte array) kwenye kumbukumbu ya kompyuta kabla ya kuandikwa kwenye diski au kuwasilishwa, ili tabaka la uthibitishaji liweze kuikagua kabla haijaondoka kwenye mfumo.

4. Tabaka la uthibitishaji baada ya utengenezaji

Tabaka la uthibitishaji baada ya utengenezaji hutumia XSD mahususi ya nchi iliyopakiwa kwenye hati ya XML iliyotengenezwa. Makosa yote ya uthibitishaji hurekodiwa pamoja na muktadha kamili. Ikiwa kuna kosa lolote la uthibitishaji, ripoti huwekewa alama ili ipitiwe badala ya kuwasilishwa. Timu ya uzingatiaji huona sehemu mahususi iliyoshindwa uthibitishaji na kanuni ya skima iliyokiukwa, jambo linalowezesha utambuzi wa haraka bila kuhitaji msanidi programu kuhusika.

5. Tabaka la uwasilishaji na ufuatiliaji

Hati ya XML inapopita uthibitishaji baada ya utengenezaji, tabaka la uwasilishaji huituma kwenye lango la FIU. Majibu ya uwasilishaji — uthibitisho wa kukubaliwa, jumbe za kukataliwa pamoja na misimbo ya sababu, na namba za kumbukumbu zilizotolewa na FIU — hunaswa na kuhifadhiwa pamoja na rekodi ya ripoti ya awali. Majibu yanayosubiriwa hufuatiliwa mara kwa mara hadi hali ya mwisho ipatikane. Maelezo ya kukataliwa huonyeshwa kwa timu ya uzingatiaji pamoja na mwongozo wa kusahihisha na kuwasilisha upya.

---

Wakati wa kutumia injini ya kutengeneza XML iliyo tayari sokoni

Mzigo wa matengenezo pale UNODC inaposasisha XSD

UNODC imetoa matoleo kadhaa ya XSD kwa skima ya goAML, na mwenendo huu utaendelea. FIU ya kitaifa inaposimika toleo jipya la XSD, msimbo wa kutengeneza XML ulioandikwa ndani ya taasisi unahitaji kusasishwa, kujaribiwa na kusimikwa — mara nyingi chini ya shinikizo la muda, kwa sababu FIU huweka muda wa mwisho wa kuhamia toleo jipya. Ikiwa injini yako ya kutengeneza XML inadumishwa ndani ya taasisi, kila sasisho la skima linaangukia timu yako ya uundaji wa programu, likishindana na vipaumbele vingine vya uundaji.

Masasisho ya kanuni mahususi za nchi

FRC ya Kenya huchapisha miongozo iliyosasishwa ya uthibitishaji mara kwa mara. Thamani mpya ya aina ya muamala inapoongezwa kwenye orodha (kwa mfano, mwendeshaji mpya wa pesa kwa simu anapoingia sokoni), kila uoanishaji wa enumeration ulioandikwa moja kwa moja ndani ya msimbo wako wa ndani lazima usasishwe. Sehemu mpya ya lazima inapoanzishwa kwa ripoti za STR, muundo wa data wa usimamizi wa kesi lazima upanuliwe, mtiririko wako wa kazi lazima usasishwe ili kunasa data mpya, na msimbo wako wa kutengeneza XML lazima usasishwe ili kujaza elementi mpya.

Jukwaa lililo tayari sokoni hubeba masasisho haya ndani ya mfumo wake wa leseni — mabadiliko ya skima ni tatizo la muuzaji, si lako.

Mfumo wa kuamua kujenga au kununua

Kwa taasisi zenye timu kubwa za ndani za uundaji wa programu, utaalamu wa kina wa teknolojia ya uzingatiaji, na hitaji la kimkakati la mantiki ya kutengeneza XML iliyobinafsishwa kwa kiwango kikubwa, uundaji wa ndani unaweza kuwa na mantiki. Kwa taasisi nyingi za fedha za Afrika Mashariki, hali ya kiuchumi na ya hatari inapendelea kwa kiasi kikubwa jukwaa lililojengwa mahususi na kudumishwa na wataalamu wa kukidhi skima ya goAML.

---

Chukua hatua inayofuata

Jukwaa la Creodata la ripoti za AML (kupambana na utakatishaji fedha haramu) kupitia goAML linajumuisha injini ya kutengeneza XML iliyo tayari kwa mazingira halisi ya uendeshaji, inayodumishwa kulingana na XSD v5.0.2 ya sasa ya goAML, pamoja na wasifu wa uthibitishaji mahususi kwa FRC ya Kenya, FIA ya Uganda, Kitengo cha Kudhibiti Fedha Haramu (FIU) cha Tanzania, FIC ya Zambia na FIC ya Rwanda. Injini hii hushughulikia kiotomatiki usimbaji, mpangilio wa desimali, usawazishaji wa tarehe, uoanishaji wa enumeration na uthibitishaji wa XSD — timu za uzingatiaji hufanya kazi na fomu zilizopangwa, si na XML.

Tazama injini ya kutengeneza XML ikifanya kazi kupitia onyesho la moja kwa moja: Omba onyesho kupitia creodata.com/demo

Maswali yanayoulizwa mara kwa mara

Nitengeneze XML kwa kufuata toleo gani la skima ya goAML?

Toleo la 5.0.2 ndilo skima iliyosimikwa na FIU za Afrika Mashariki zinazozungumziwa katika mwongozo huu. Fungamanisha kitengeneza XML chako na toleo halisi linalochapishwa na FIU yako, kisha ujaribu upya kitengeneza hicho FIU inapohamia toleo jipya: matoleo ya UNODC si kila mara yanaendana na yale ya awali, hivyo XML iliyopita uthibitishaji dhidi ya v4 inaweza kushindwa kwa michanganyiko fulani ya elementi za v5.

Kwa nini lango la goAML hukataa faili iliyopita uthibitishaji kwenye mifumo yako?

Kwa kawaida ni mojawapo ya mambo manne: alama ya mpangilio wa baiti (BOM) ya UTF-8 iliyoandikwa na maktaba ya XML ya Windows; nyongeza ya nchi ambayo XSD yako ya ndani haina, kama vile aina za miamala ya pesa kwa simu za FRC ya Kenya; elementi tupu ya hiari ambayo ilipaswa kuachwa; au ukaguzi wa kanuni za kibiashara unaofanyika baada ya uthibitishaji wa skima — namba ya taasisi inayoripoti isiyolingana na rejista ya FIU, au namba ya kumbukumbu ya ripoti iliyojirudia.

XSD ya goAML inahitaji miundo gani ya tarehe, kiasi na boolean?

Tarehe ni ISO 8601 YYYY-MM-DD pekee. Kiasi ni xs:decimal yenye nafasi mbili kamili za desimali na bila vitenganishi vya maelfu (1250000.00). Thamani za boolean ni true au false kwa herufi ndogo. Data zinazohamishwa kutoka mfumo mkuu wa benki katika DD/MM/YYYY, tarehe za mfuatano za Excel, na thamani kama True au FALSE lazima zisawazishwe kabla ya kutengeneza XML.

Muundo wa ripoti ya XML ya goAML ukoje?

Report → Transaction → Party → Account → ID document → Address. Ripoti hubeba muamala mmoja au zaidi; kila muamala hutaja wahusika wa pande zote mbili (from_person au from_entity, to_person au to_entity), akaunti zao, hati za utambulisho na anwani. CTR inahitaji aina za miamala ya fedha taslimu na taarifa kamili za akaunti; STR inahitaji is_suspicious iwekwe kuwa true, maelezo ya reason yenye maudhui ya maana, na angalau msimbo mmoja wa kiashiria.

Ninaweza kupakua wapi XSD rasmi ya goAML?

Kutoka kwenye nyaraka za goAML za UNODC — na, muhimu zaidi, kutoka kwenye lango la FIU yako mwenyewe, kwa sababu nyongeza za nchi hubadilisha skima ya msingi. Thibitisha dhidi ya nakala iliyochapishwa na FIU badala ya faili iliyopakuliwa kutoka kwa mtu mwingine.