UDF Formatı Teknik Spesifikasyonu: ZIP, XML, RTF ve PKCS#7 Anatomisi

Son güncelleme: 18 Nisan 2026 · 12 dk okuma

UYAP (Ulusal Yargı Ağı Platformu) tarafından kullanılan UDF (UYAP Document Format), Türkiye yargı sistemindeki neredeyse tüm elektronik belgelerin taşıyıcısıdır. Mahkeme kararından avukat dilekçesine, bilirkişi raporundan tensip zaptına kadar milyonlarca belge bu formatla dolaşır. Ancak Türkçe teknik literatürde UDF'in iç yapısına dair kapsamlı bir spesifikasyon dokümanı bulunmuyor. Bu yazı, UDF formatını geliştiriciler ve teknik okuyucular için bit düzeyinde açıklamayı amaçlıyor: ZIP konteyneri, XML şeması, gömülü RTF fragmentleri ve PKCS#7 dijital imza katmanı nasıl katmanlandırılmış?

Aşağıdaki bilgiler, on binlerce gerçek UDF dosyasını tarayıcıda parse eden convertudftopdf.com dönüştürücüsünün geliştirme sürecinde elde edilmiş pratik gözlemlere dayanır. Resmi bir UYAP yayını değildir; ancak format üzerinde çalışan herkesin başlangıç noktası olabilir.

Bu yazı iki hedef kitleye hitap eder: UDF'i parse eden yazılım geliştirenler (JSZip, libxml, CMS kütüphaneleri kullananlar) ve formatın "içinde ne var?" sorusuna cevap arayan hukuk uzmanları. Terminoloji ilk kez geçtiğinde kısa bir açıklama bulacaksınız.

1. UDF Nedir: Üst Düzey Bakış

UDF, Adalet Bakanlığı'nın UYAP altyapısı için geliştirilmiş kapalı bir belge formatıdır. Dosya uzantısı .udf olan her belge, aslında bir konteyner dosyadır: içinde zengin metin içeriği (paragraflar, tablolar, stiller), isteğe bağlı olarak dijital imza bloğu ve bazen gömülü nesneler (küçük resimler, logo fragmentleri) barındırır.

Format, MIME tipi olarak genellikle application/octet-stream veya özel bir application/vnd.uyap.udf varyantı altında sunulur. IANA'da tescilli değildir. UDF'in temel tasarım hedefleri şunlardır:

UDF, MS Office'in DOCX veya LibreOffice'in ODT formatlarına yapısal olarak benzer: hepsi bir ZIP konteyneri içine yerleştirilmiş XML tabanlı içerik modelini kullanır. Ancak DOCX/ODT açık spesifikasyonlara sahipken, UDF kapalı bir format olarak kalmıştır.

2. UDF Dosyası Açıldığında: Bir ZIP Arşivi

UDF spesifikasyonundaki en önemli keşif: UDF aslında standart bir ZIP arşividir. Uzantıyı .zip olarak yeniden adlandırdığınızda veya doğrudan unzip komutuyla açtığınızda iç yapı görünür hale gelir:

# Terminalde hızlı inceleme
$ file karar.udf
karar.udf: Zip archive data, at least v2.0 to extract

$ unzip -l karar.udf
Archive:  karar.udf
  Length      Date    Time    Name
---------  ---------- -----   ----
    14823  2026-03-14 11:42   content.xml
     2048  2026-03-14 11:42   signature.p7s
      512  2026-03-14 11:42   binary/header.jpg
---------                     -------
    17383                     3 files

$ unzip karar.udf -d karar_extracted/
$ ls karar_extracted/
content.xml  signature.p7s  binary/

ZIP konteynerinin içinde tipik olarak bulunan bileşenler:

Geliştirici notu: Biz convertudftopdf.com'da UDF dosyalarını açmak için tarayıcıda JSZip kütüphanesini kullanıyoruz. Dosya File nesnesi olarak alınır, JSZip.loadAsync(file) ile açılır, ardından zip.file("content.xml").async("string") ile XML içeriği alınır. Tüm işlem kullanıcının tarayıcısında gerçekleşir — bu, avukat gizliliği için kritik bir tasarım kararıdır.

3. content.xml Şeması: Belgenin Yapı Taşı

content.xml, UDF'in kalbidir. UTF-8 kodlamalı, standart bir XML dosyasıdır ve belgenin tüm yapısal bilgisini taşır. Root elementi genellikle <template> veya <document> adındadır ve altında birkaç ana seksiyon bulunur:

<?xml version="1.0" encoding="UTF-8"?>
<template>
  <properties>
    <pageFormat width="595" height="842"
                marginTop="60" marginBottom="60"
                marginLeft="70" marginRight="70"/>
    <documentInfo
        documentType="KARAR"
        createdBy="UYAP Dokuman Editoru 5.x"
        createdDate="2026-03-14T11:42:00"/>
  </properties>

  <elements resolver="hvl-oncesi">
    <paragraph Alignment="0" LineSpacing="1.15"
               FirstLineIndent="0" LeftIndent="0">
      <content startOffset="0" length="42"
               Family="Times New Roman" Size="12"
               Bold="false" Italic="false">
        T.C. ISTANBUL 1. ASLIYE HUKUK MAHKEMESI
      </content>
    </paragraph>

    <paragraph Alignment="2">
      <content startOffset="42" length="14"
               Family="Times New Roman" Size="12"
               Bold="true">
        GEREKCELI KARAR
      </content>
    </paragraph>

    <table border="1" width="100%">
      <row>
        <cell colspan="1">
          <paragraph><content>Dosya No</content></paragraph>
        </cell>
        <cell>
          <paragraph><content>2026/123</content></paragraph>
        </cell>
      </row>
    </table>
  </elements>

  <headers>
    <header type="default">
      <paragraph Alignment="1">
        <content Size="10">Sayfa {PAGE} / {TOTAL}</content>
      </paragraph>
    </header>
  </headers>

  <footers>
    <footer type="default"> ... </footer>
  </footers>
</template>

Ana element kategorileri:

4. Metin Biçimlendirmesi: Stil Özellikleri

UDF, biçimlendirmeyi CSS benzeri bir "cascade" yerine her <content> segmentinde tam özellik seti olarak saklar. Bu, parser açısından hayatı kolaylaştırır (miras kuralları yoktur) ama dosya boyutunu büyütür. Tipik özellikler:

<content
    Family="Times New Roman"      <!-- yazi tipi -->
    Size="12"                      <!-- punto -->
    Bold="true"                    <!-- kalin -->
    Italic="false"                 <!-- italik -->
    Underline="true"               <!-- alti cizili -->
    Strikethrough="false"          <!-- ustu cizili -->
    Foreground="0,0,0"             <!-- metin rengi (R,G,B) -->
    Background="255,255,255"       <!-- arka plan -->
    Offset="Superscript"           <!-- ust/alt simge -->
    startOffset="120"
    length="25">
  Ornek zengin metin
</content>

Paragraf seviyesinde hizalama (Alignment) için yaygın değerler:

Satır aralığı (LineSpacing) ondalık değer olarak verilir: 1.0, 1.15, 1.5, 2.0. Girinti alanları (FirstLineIndent, LeftIndent, RightIndent) point cinsindendir; 1 cm yaklaşık 28.35 point'e denk gelir.

5. Tablolar ve Hücre Birleştirme

Hukuki belgelerde (özellikle tensip zaptı ve karar üst bloklarında) tablolar yaygın kullanılır. UDF tablo modeli HTML'in <table> elementine benzer ancak tab stop bazlı bir ızgara kullanır — CSS grid değil.

<table border="1" width="100%" cellpadding="4">
  <row height="30">
    <cell colspan="2" rowspan="1"
          background="230,230,230"
          verticalAlignment="center">
      <paragraph Alignment="1">
        <content Bold="true">DAVA BILGILERI</content>
      </paragraph>
    </cell>
  </row>
  <row>
    <cell width="30%">
      <paragraph><content>Mahkeme</content></paragraph>
    </cell>
    <cell width="70%">
      <paragraph><content>Istanbul 3. Asliye Hukuk</content></paragraph>
    </cell>
  </row>
</table>

Önemli hücre özellikleri:

Parser yazarken dikkat edilmesi gereken nokta: UDF tablolarında eksik hücreler ve birleştirilmiş hücre sonrası atlamalar kolayca offset hatası üretebilir. Güvenli bir yaklaşım, her satır için beklenen sütun sayısını takip etmek ve colspan toplamını doğrulamaktır.

6. Tab Stops ve Paragraf Ayarları

UDF, klasik daktilo/Word tarzı tab stop modelini desteklemeye devam eder — modern web'de nadir, ancak hukuki belgelerde hala sıkça kullanılır. Her paragrafa birden fazla tab stop atanabilir:

<paragraph Alignment="0">
  <tabStops>
    <tabStop position="85"  alignment="LEFT"/>
    <tabStop position="280" alignment="CENTER"/>
    <tabStop position="510" alignment="RIGHT" leader="DOTS"/>
  </tabStops>
  <content>Davaci:\tAhmet Yilmaz\t\t01.01.2026</content>
</paragraph>

Özellikler:

PDF veya HTML render'ı yaparken tab stop'ları simüle etmek zorlu bir iştir. Pratik bir strateji: tab karakterlerini koordinat tabanlı metin yerleşimine (jsPDF'in doc.text(x, y, str) API'si) çevirmektir.

7. Gömülü RTF İçeriği

UDF, "saf" bir XML format değildir. Bazı alanlar — özellikle UYAP Döküman Editörü'nün Word'den kopyala-yapıştır desteklediği bölgeler — RTF (Rich Text Format) fragmentleri olarak saklanır. Bu, XML içinde CDATA veya base64 bloğu olarak görünür:

<content type="rtf" encoding="base64">
e1xydGYxXGFuc2lcZGVmZjB7XGZvbnR0YmwKe1xmMFxmcm9tYW4gVGltZXMgTmV3IFJvbWFu
O30KfQpcdmlld2tpbmQ0XHVjMVxwYXJkXGYwXGZzMjQKQnUgYmlyIG9ybmVrIFJURiBwYXJh
Z3JhZmlkaXIucGFyCn0=
</content>

Yukarıdaki örnek base64 çözüldüğünde klasik RTF açılış grubunu verir:

{\rtf1\ansi\deff0{\fonttbl
{\f0\froman Times New Roman;}
}
\viewkind4\uc1\pard\f0\fs24
Bu bir ornek RTF paragrafidir.\par
}

Neden RTF? Tasarım tercihinin birkaç pratik nedeni vardır:

Parser yazarken RTF bloklarını tanımak ve bunları ayrı bir RTF parser'ına yönlendirmek gerekir. Basit metin çıkarımı için /\\[a-z]+\d*\s?/g gibi bir kontrol kodu temizleyici yeterli olabilir; ancak tam doğruluk için RFC 1341 tabanlı gerçek bir RTF tokenizer'a ihtiyaç vardır.

8. PKCS#7 Dijital İmza Katmanı

UDF'in en karmaşık katmanı dijital imza bloğudur. UYAP, imzalı resmi belgelerde (mahkeme kararı, tensip zaptı, duruşma tutanağı) PKCS#7 / CMS (Cryptographic Message Syntax, RFC 5652) standardında bir imza dosyası ekler. Bu dosya ZIP içinde signature.p7s veya benzer adla bulunur.

PKCS#7 imza bloğu ASN.1 (Abstract Syntax Notation One) DER kodlamasındadır. Kaba yapı şöyledir:

ContentInfo ::= SEQUENCE {
    contentType  OBJECT IDENTIFIER,  -- 1.2.840.113549.1.7.2 (signedData)
    content      [0] EXPLICIT SignedData
}

SignedData ::= SEQUENCE {
    version             INTEGER,
    digestAlgorithms    SET OF AlgorithmIdentifier,    -- genellikle sha256
    encapContentInfo    SEQUENCE {
        eContentType    OBJECT IDENTIFIER,             -- 1.2.840.113549.1.7.1 (data)
        eContent        [0] OCTET STRING OPTIONAL     -- imzalanan ham veri
    },
    certificates        [0] SET OF Certificate,        -- imzalayan sertifika zinciri
    crls                [1] SET OF CertificateList OPTIONAL,
    signerInfos         SET OF SignerInfo              -- asil imza
}

SignerInfo ::= SEQUENCE {
    version             INTEGER,
    sid                 SignerIdentifier,              -- cert seri no + issuer
    digestAlgorithm     AlgorithmIdentifier,           -- sha256
    signedAttrs         [0] SET OF Attribute OPTIONAL, -- imzalama zamani vs.
    signatureAlgorithm  AlgorithmIdentifier,           -- rsaEncryption
    signature           OCTET STRING                   -- gercek imza byte'lari
}

Tipik olarak şu alanlar UDF imzasında bulunur:

Doğrulama sırası: (1) ZIP'ten content.xml çıkar; (2) SHA-256 hesapla; (3) PKCS#7 bloğundaki messageDigest ile karşılaştır; (4) signature alanını sertifikadaki public key ile RSA/ECDSA doğrulaması yap; (5) Sertifika zincirini güvenilir köke kadar takip et; (6) İmza zamanında sertifikanın iptal listesinde olmadığını kontrol et (OCSP/CRL). Biz bu akışı UDF Dijital İmza Doğrulama sayfasında daha ayrıntılı açıklıyoruz.

ASN.1 parser'ı olarak JavaScript tarafında asn1.js, node-forge veya Web Crypto API ile manuel DER çözme yaygın yaklaşımlardır. Python tarafında cryptography kütüphanesinin pkcs7 modülü doğrudan destek verir.

UDF Dosyanızı Hemen Dönüştürün

Bu spesifikasyonu kullanan canlı dönüştürücümüzü deneyin. Dosyalarınız tarayıcınızdan asla çıkmaz.

Canlı Dönüştürücüyü Aç

9. UDF vs Benzer Formatlar

UDF'i daha iyi konumlandırmak için tanıdık belge formatlarıyla karşılaştıralım. Yapısal olarak DOCX/ODT ailesine yakındır; ancak yargısal metadata ve imza entegrasyonu açısından kendine özgüdür.

Özellik UDF DOCX ODT RTF
Uzantı .udf .docx .odt .rtf
Konteyner ZIP ZIP (OOXML) ZIP (OpenDocument) Düz metin
Şema tipi Kapalı XML + RTF hybrid Açık XML (ISO/IEC 29500) Açık XML (ISO/IEC 26300) Kontrol kodu tabanlı
Açık spec Hayır Evet Evet Evet
Dijital imza Yerleşik PKCS#7 Opsiyonel (XML DSig) Opsiyonel (XML DSig) Yok
Yaygın kullanım UYAP / Türk yargısı Küresel ofis dokümanları LibreOffice ekosistemi Eski/çapraz platform

UDF'in DOCX'e çevrilmesi teknik olarak mümkündür ve biz bu dönüşümü docx JavaScript kütüphanesi üzerinden UDF → Word özelliğimizde sunuyoruz. Ancak PKCS#7 imza katmanı DOCX'te muhafaza edilemez; yalnızca imzanın varlığına dair metadata not olarak eklenebilir.

10. UDF Parser'ı Nasıl Yazılır? Geliştiriciler İçin İpuçları

Kendi UDF parser'ınızı yazmak istiyorsanız aşağıdaki yol haritası başlangıç için uygundur. JavaScript / tarayıcı tabanlı bir yaklaşımı örnek alıyoruz; Python, Java veya .NET için de paralel kütüphaneler mevcuttur.

// 1. ZIP'i ac
import JSZip from 'jszip';
const zip = await JSZip.loadAsync(file);

// 2. content.xml'i cek
const xmlText = await zip.file('content.xml').async('string');

// 3. DOMParser ile parse et
const parser = new DOMParser();
const xmlDoc = parser.parseFromString(xmlText, 'application/xml');

// 4. Paragraflari gez
const paragraphs = xmlDoc.getElementsByTagName('paragraph');
for (const p of paragraphs) {
  const alignment = p.getAttribute('Alignment') || '0';
  const contents = p.getElementsByTagName('content');
  for (const c of contents) {
    const text = c.textContent;
    const bold = c.getAttribute('Bold') === 'true';
    const size = parseInt(c.getAttribute('Size')) || 12;
    // ... jsPDF veya docx cikti uretimi
  }
}

// 5. Imza bloklarini kontrol et (opsiyonel)
const sigFile = zip.file(/\.p7s$/)[0];
if (sigFile) {
  const sigBytes = await sigFile.async('uint8array');
  // forge.pkcs7.messageFromAsn1(...) ile dogrula
}

Karşılaşacağınız başlıca tuzaklar:

Açık kaynak durumu: Yazının yayınlandığı tarihte (Nisan 2026) GitHub'da UDF formatını uçtan uca parse eden, aktif bakımlı bir kütüphane bulunmuyor. convertudftopdf.com'un arkasındaki JavaScript dönüştürücüsü tarayıcıda çalışır ve bu yazıdaki gözlemler büyük ölçüde o kod tabanının deneyimine dayanır. Deneysel eski projeler (örn. bazı Java-Swing UDF viewer denemeleri) bakımsız kalmış, PKCS#7 katmanını işlemez ve modern UYAP sürümleriyle uyumsuzdur.

11. Sıkça Sorulan Sorular

UDF formatı için resmi bir spesifikasyon belgesi var mı?

Adalet Bakanlığı veya UYAP tarafından herkese açık olarak yayımlanmış resmi bir UDF spesifikasyonu bulunmamaktadır. Format detayları UYAP Döküman Editörü'nün davranışından ve gerçek UDF örneklerinin incelenmesinden çıkarılmıştır. Bu yazı da o pratik bilgiye dayanmaktadır.

UDF'in sürüm numarası ya da schemaVersion alanı var mı?

Bazı UDF dosyalarının <properties> bloğunda createdBy alanında editör sürümü gözükür (örn. "UYAP Dokuman Editoru 5.x"). Ancak formatın kendisinde net bir schemaVersion attribute'u bulunmaz. Sürüm farklılıkları daha çok eksik/yeni element varlığıyla anlaşılır.

UDF dosyasını manuel olarak düzenleyebilir miyim?

Teknik olarak evet: ZIP'i açıp content.xml'i düzenleyip yeniden ZIP'leyebilirsiniz. Ancak eğer dosya dijital imzalıysa, imzayı geçersiz kılmış olursunuz. İmza doğrulama zincirinde messageDigest artık uyuşmayacağı için belge "sahte" olarak işaretlenir. Mahkeme süreçlerinde orijinal imzalı UDF'lerin değiştirilmemesi kritik önemdedir.

UDF'in DOCX'ten farkı sadece markası mı?

Hayır, yapısal farklar da var. DOCX, OOXML standardına sıkı sıkıya bağlıdır ve ISO/IEC 29500 tarafından tanımlanır. UDF ise kapalı bir yapıya sahip, XML elementleri farklı isimlendirilir (<paragraph> vs <w:p>), biçimlendirme attribute'ları miras almak yerine her segmentte tekrarlanır ve PKCS#7 imza katmanı yerleşiktir. Ayrıca UDF'in tab-stop temelli tablo yaklaşımı DOCX'in grid modelinden farklıdır.

Neden RTF ve XML birlikte kullanılıyor?

Bu hibrit yaklaşım, UYAP Döküman Editörü'nün Windows RichEdit kontrolü üzerine inşa edilmesinden kaynaklanır. XML belgenin yapısal omurgasını (sayfa düzeni, tablolar, paragraf sırası) taşırken, bazı zengin metin alanları — özellikle panodan yapıştırılan içerik — RTF olarak saklanır. Bu, editörün performansını artırır ancak parser yazanlar için ek karmaşıklık demektir.

PKCS#7 yerine XAdES veya CAdES kullanılmış olsaydı farklı olur muydu?

Teknik olarak evet. XAdES (XML Advanced Electronic Signatures) XML imza standardıdır ve uzun süreli arşivleme için ek özellikler sunar. CAdES (CMS Advanced Electronic Signatures) ise PKCS#7'nin üst kümesidir ve zaman damgası, iptal bilgisi gibi LTV (Long Term Validation) kanıtlarını standartlaştırır. UYAP bazı belgelerde CAdES-T veya CAdES-X Long profillerine yaklaşan imzalar üretir; ancak temel yapı hâlâ RFC 5652 CMS uyumludur.

UDF'i başka bir formata dönüştürmek imzayı korur mu?

Hayır. Dönüştürme işlemi (UDF → PDF veya UDF → DOCX) belgenin içeriğini yeni bir konteynere taşır; orijinal PKCS#7 imza bloğu yeni formatla kriptografik olarak eşleşmez. Dönüştürülen PDF'i yeniden imzalamak isterseniz PAdES (PDF Advanced Electronic Signatures) standardını kullanmanız gerekir. İmzalı UDF'in hukuki geçerliliğini korumak için orijinal UDF dosyasını saklamak ve dönüştürülmüş versiyonu sadece görüntüleme amacıyla kullanmak en güvenli yaklaşımdır.

Mobil veya web ortamında UDF parse etmek neden zor?

Başlıca sebepler: (1) UYAP Döküman Editörü sadece Windows için dağıtılır; (2) ZIP + XML + RTF + PKCS#7 katmanlarının hepsinin JavaScript'te implementasyonu karmaşıktır; (3) Türkçe font desteği (ş, ç, ğ, ı) için özel TTF yüklemesi gerekir; (4) PKCS#7 doğrulaması için Web Crypto API yeterli değildir, ek ASN.1 parser'lar gerekir. Biz convertudftopdf.com'da bu zorlukları JSZip + jsPDF + özel Turkish font entegrasyonu ile çözüyoruz.

UDF açmak için Java Swing'li eski UYAP uygulamalarını kullanamaz mıyım?

Kullanabilirsiniz ancak önemli sorunlar var: (1) Java sürümü uyumsuzlukları son kullanıcıda çalışmayabilir; (2) Modern UYAP 5.x sürümünün ürettiği UDF'ler eski Java editörlerde tam açılmayabilir; (3) PKCS#7 doğrulaması güncel CA sertifikası olmadan başarısız olur. Bu nedenle modern tarayıcı tabanlı dönüştürücüler daha güvenilir ve platformdan bağımsızdır.

Daha Fazla Teknik İçerik

UYAP ekosistemi, terminoloji ve hukuk teknolojisi hakkında daha derin rehberler için UYAP Rehberi'ni ve sözlüğümüzü inceleyin.

UYAP Rehberini Aç

İlgili Sayfalar