Belajar SOAP - Namespace, XSD & Data Types

#Pendahuluan

Setelah di episode 6 kita menguasai testing, sekarang kita menyelami lapisan yang menentukan apakah request valid: namespace, XSD, dan data types. Ini bukan materi pelengkap — kesalahan di lapisan ini adalah penyebab paling umum kegagalan integrasi SOAP di lapangan.

Mengapa penting? Karena SOAP mempertukarkan data bisnis (uang, tanggal, dokumen) antarorganisasi yang bahasa pemrogramannya berbeda. Format xsd:dateTime di Java tidak sama dengan format tanggal di PHP. Representasi desimal di C# berbeda dengan float di Python. XSD adalah bahasa yang menyatukan semuanya — dan kesalahan kecil di sini bisa berarti uang yang salah transfer atau klaim asuransi yang ditolak.

#XML Namespace dan Qualified Names

#Konsep `xmlns`

Namespace XML adalah mekanisme untuk menghindari tabrakan nama ketika beberapa kosakata digabung dalam satu dokumen. Deklarasi xmlns mengikat awalan (prefix) ke sebuah URI:

Dua namespace dalam satu dokumen

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
  <soap:Body>
    <bank:getBalance xmlns:bank="urn:example:bank">
      <bank:accountNo>ACC-001</bank:accountNo>
    </bank:getBalance>
  </soap:Body>
</soap:Envelope>

soap: dan bank: adalah prefix; URI yang diikatnya adalah namespace name. Yang menentukan identitas elemen adalah namespace name + local name (disebut QName, Qualified Name) — bukan prefixnya. Kalian bisa mengganti prefix bank menjadi b selama URI-nya sama, dan elemennya tetap identik secara semantik.

#Namespace SOAP dan XSD yang Perlu Dihafal

Namespace	URI	Digunakan untuk
SOAP 1.1	`http://schemas.xmlsoap.org/soap/envelope/`	Envelope versi 1.1
SOAP 1.2	`http://www.w3.org/2003/05/soap-envelope`	Envelope versi 1.2
XML Schema	`http://www.w3.org/2001/XMLSchema`	Tipe data (`xsd:string`, dll)
XML Schema instance	`http://www.w3.org/2001/XMLSchema-instance`	Atribut `xsi:nil`, `xsi:type`
WSDL	`http://schemas.xmlsoap.org/wsdl/`	Elemen `definitions`, `portType`, dll

Warning

Prefix bebas, tetapi URI namespace harus persis — termasuk trailing slash. http://www.w3.org/2001/XMLSchema dengan / tambahan atau tanpa / adalah namespace yang berbeda, dan dokumen yang memakainya akan ditolak validasi.

#XSD: Mendefinisikan Kontrak Data

XSD (XML Schema Definition) mendefinisikan tipe dan struktur data. Ada dua kategori utama: simple types (tipe primitif dengan atau tanpa restriction) dan complex types (elemen berisi elemen/atribut lain).

#Complex Types dan Sequence

sequence menentukan urutan elemen yang wajib dipatuhi:

complexType dengan sequence

<xsd:element name="account">
  <xsd:complexType>
    <xsd:sequence>
      <xsd:element name="accountNo" type="xsd:string"/>
      <xsd:element name="openedDate" type="xsd:date"/>
      <xsd:element name="balance" type="xsd:decimal"/>
    </xsd:sequence>
  </xsd:complexType>
</xsd:element>

Request harus mengirim elemen dalam urutan accountNo, openedDate, balance. Menukar urutan openedDate dan balance membuat dokumen invalid — aturan yang sering tidak disadari developer REST yang terbiasa JSON object tanpa urutan.

#Restriction dan Enumeration

restriction membatasi nilai yang boleh muncul:

Restriction dan enumeration

<xsd:simpleType name="AccountStatus">
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="ACTIVE"/>
    <xsd:enumeration value="SUSPENDED"/>
    <xsd:enumeration value="CLOSED"/>
  </xsd:restriction>
</xsd:simpleType>

Sekarang nilai di luar ketiga status itu ditolak di level validasi — bukan di kode bisnis. Ini memindahkan validasi dari programmer ke kontrak.

#`nillable` dan `xsi:nil`

Elemen wajib selalu hadir di XML; untuk nilai "null" gunakan nillable="true" dan tanda xsi:nil="true":

Elemen nillable

<xsd:element name="closedDate" type="xsd:date" nillable="true"/>

Pemakaian xsi:nil

<closedDate xsi:nil="true"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"/>

Tanpa nillable="true", elemen wajib diisi nilai nyata — kirim kosong saja tidak valid.

#Data Types Kritis: Date, Decimal, Base64

#`xsd:date` dan `xsd:dateTime`

Format xsd:dateTime mengikuti ISO-8601 dengan zona waktu: 2026-08-16T09:30:00+07:00 atau 2026-08-16T02:30:00Z. Kesalahan paling umum:

Kirim 16/08/2026 → invalid (harus 2026-08-16).
Kirim 2026-08-16 09:30:00 → invalid (butuh T pemisah).
Kirim tanpa zona waktu → valid secara sintaks, tetapi ambigu di lintas zona — selalu sertakan offset.

#`xsd:decimal` untuk Uang

Nilai uang wajib bertipe xsd:decimal — presisi tetap, bukan floating point. Java memakainya sebagai BigDecimal, Python sebagai Decimal, .NET sebagai decimal. Memakai xsd:float/xsd:double untuk uang berarti menerima risiko pembulatan: 0.1 + 0.2 di floating point tidak sama dengan 0.3.

Decimal yang benar

<balance>2750000.00</balance>

#`xsd:base64Binary` untuk Dokumen

File biner (PDF, scan, gambar) diserialisasi sebagai base64Binary:

Base64 di body

<document name="ktp.pdf" mime="application/pdf">
  JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZwov...
</document>

Untuk file besar, base64 di dalam XML sangat boros (ukuran bertambah ~33% dan semuanya dibuka di memory). Episode 11 akan membahas MTOM, optimasi khusus untuk kasus ini.

Tip

Jika dua sistem berselisih soal format data, kontrak XSD adalah wasitnya — bukan perasaan. Contohnya: 01 vs 1 untuk nomor. Untuk data yang mempertahankan leading zero (KTP, nomor rekening), deklarasikan sebagai string dengan pattern xsd:pattern — jangan numeric, atau 01 akan berubah menjadi 1.

#Penutup

Inti yang harus dibawa pulang:

Identitas elemen ditentukan QName (namespace + local name); URI harus persis, prefix bebas.
sequence memberlakukan urutan elemen; restriction/enumeration memindahkan validasi ke kontrak.
nillable + xsi:nil adalah cara XML menyatakan null.
Gunakan dateTime ber-offset, decimal untuk uang, dan base64Binary untuk dokumen.
File besar butuh MTOM, bukan base64 di dalam XML.

Di episode 8 selanjutnya kita akan membahas fault handling dan error pattern — anatomi Fault di SOAP 1.1 vs 1.2, memetakan error bisnis ke kode yang konsisten, dan strategi logging error yang bisa dilacak. Sampai jumpa di episode 8!