Tutorial tagged PDF dengan Connect

Tutorial tagged PDF dengan Connect

Batas konformansi (baca ini terlebih dahulu). NextPDF menghasilkan struktur bertanda (tagged), teks alternatif, dan metadata yang diharapkan oleh PDF/UA-2. Dengan demikian, keluaran tersebut dimaksudkan untuk memenuhi PDF/UA-2 (ISO 14289-2). Namun, hal itu tidak secara otomatis membuat dokumen “memenuhi konformansi”. Pemeriksa independen, yaitu veraPDF dalam mode PDF/UA-2 ketat, yang menentukan konformansi. Baca setiap pernyataan “PASS”, “conformant”, atau “compliant” di bawah sebagai “dokumen dimaksudkan untuk memenuhi; veraPDF yang menentukan hasilnya”.

Sekilas

Dalam tutorial ini, Anda membuat berkas tagged Portable Document Format (PDF) melalui transport Connect. Anda mengaktifkan mode tagged, menetapkan judul, menambahkan HTML semantik, lalu memverifikasi hasilnya dengan alat standards-check dan veraPDF. Alat mode tagged dan konten yang digunakan di sini adalah bagian dari core. Alat verifikasi standards-check berada di tier Pro/Enterprise. Alat tersebut hanya teregistrasi melalui class_exists() ketika nextpdf/premium terpasang bersama server.

Pemasangan

composer require nextpdf/server

Gambaran konseptual

Struktur logis yang dipadukan dengan spesifikasi bahasa alami membuat konten dapat dinavigasi dalam urutan baca (ISO 32000-2 §14.7). Entri /Alt menyimpan deskripsi alternatif untuk konten nonteks (ISO 32000-2 §14.8). Konten harus tercermin dalam pohon struktur, dan sebuah pemeriksa menentukan konformansi (PDF/UA-2 §8.2.4). Ketika Anda menulis HTML semantik yang terstruktur dengan baik, pipeline akan menghasilkan struktur yang benar untuk Anda. Tutorial ini mengandalkan alur tersebut, bukan meminta Anda membangun struktur secara manual.

Permukaan API

Nama alat diverifikasi terhadap registry yang berjalan melalui tools/list. Katalog acuannya adalah /connect/tool-catalog/. Tutorial ini tidak mengulang jumlah alatnya.

Contoh kode — Mulai cepat

Berikut adalah jalur tersingkat. Aktifkan mode tagged dengan bahasa tertentu, tetapkan judul, lalu tambahkan konten.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "enable_tagged_pdf",
    "arguments": { "document_id": "<id>", "language": "en" }
  }
}

Aktifkan mode tagged sebelum panggilan konten pertama Anda. Writer membekukan mode tersebut saat menghasilkan halaman pertama. Jika Anda mengaktifkannya belakangan, NextPDF tidak akan menandai ulang konten yang sudah dihasilkan. Judul dokumen wajib ada untuk PDF/UA-2, dan mode tagged menetapkan preferensi viewer-title.

Contoh kode — Produksi

Tambahkan HTML semantik. Pipeline memetakan heading, daftar, tabel dengan <th scope>, tautan, dan figur dengan alt ke tipe struktur yang tepat:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "add_html",
    "arguments": {
      "document_id": "<id>",
      "html": "<h1>Annual Report</h1><h2>Summary</h2><p>Revenue grew.</p><table><caption>Revenue</caption><thead><tr><th scope=\"col\">Region</th><th scope=\"col\">Q1</th></tr></thead><tbody><tr><th scope=\"row\">EMEA</th><td>120</td></tr></tbody></table><figure><img src=\"chart.png\" alt=\"Revenue by region bar chart\" /><figcaption>Figure 1.</figcaption></figure>"
    }
  }
}

RevenueRegionQ1EMEA120

Figure 1.

" } }}">

Lalu jalankan standards check terhadap PDF/UA-2, dan jalankan veraPDF --flavour ua2 pada keluaran tersebut. Hasil pemeriksaan dan putusan veraPDF menjadi dasar penilaian. Keduanya memberi tahu Anda apakah dokumen dimaksudkan untuk memenuhi konformansi. veraPDF, bukan NextPDF, yang menentukan konformansi.

Kasus tepi & jebakan

• Mode tagged diaktifkan setelah konten. Konten apa pun yang Anda tambahkan sebelum mode diaktifkan tidak akan bertanda (untagged). Pemeriksaan akan melaporkan kegagalan tagged-content. Aktifkan mode tersebut segera setelah Anda membuat dokumen.
• Gambar informasional tanpa alt. Pemeriksaan akan melaporkan kegagalan figure-alternate-text. Sediakan teks alternatif, atau tandai gambar dekoratif sebagai artifact (/cookbook/connect/page-artifacts/).
• Tingkat heading dilewati. Melewati satu tingkat, misalnya H1 lalu H3, merupakan kegagalan heading-order. Turun paling banyak satu tingkat dalam satu langkah.
• <th> tanpa scope. Sel header tanpa sel data terkait merupakan kegagalan table-structure. Berikan setiap <th> salah satu dari scope="col" atau scope="row".
• Judul hilang. Dokumen tanpa judul merupakan kegagalan metadata. Tetapkan judul setelah Anda mengaktifkan mode tagged.

Performa

Budget front-matter adalah batas dokumentasi. Penandaan (tagging) merupakan bagian dari proses tata letak normal.

Catatan keamanan

Tidak ada ketentuan lain yang berlaku di sini selain panduan transport Connect umum: jangan mencatat konten dokumen atau body HTML pada tingkat log yang dikirim secara eksternal.

Konformansi

Pemetaan PDF/UA-2

HTML semantik dipetakan ke tipe struktur standar PDF/UA-2 (H1–H6, P, L/LI/Lbl/LBody, Table/TR/TH/TD, Link, Figure/Caption, Aside). Pemetaan ini berlangsung otomatis. Tanggung jawab Anda dalam kontrak ini adalah menulis HTML semantik.

Referensi silang Tag → ISO 32000-2 §14.9

Klaim	Klausa	reference_id
Struktur logis + bahasa → dapat dinavigasi dalam urutan baca	ISO 32000-2 §14.7
Deskripsi alternatif disimpan dalam /Alt	ISO 32000-2 §14.8
Konten dalam pohon struktur; sebuah pemeriksa menentukan konformansi	PDF/UA-2 §8.2.4

Pemetaan WCAG 2.2

Struktur ini mendukung WCAG 2.2 SC 1.1.1, 1.3.1, 2.4.1, dan 2.4.6 pada tingkat konten. Sebagai penulis konten, Anda tetap bertanggung jawab atas keputusan penulisan pada tingkat WCAG.

NextPDF menghasilkan keluaran yang dimaksudkan untuk memenuhi PDF/UA-2. Hal itu tidak menyatakan konformansi. veraPDF, atau pemeriksa lain, yang menentukan konformansi. Pemeriksaan yang lulus atau eksekusi veraPDF adalah bukti bahwa keluaran dimaksudkan untuk memenuhi konformansi, bukan sertifikasi oleh NextPDF.

Konteks komersial

Alat mode tagged dan konten merupakan bagian dari core. Alat verifikasi standards-check berada di tier Pro/Enterprise, dan hanya teregistrasi ketika nextpdf/premium terpasang bersama server.

Hal khusus Connect

Ketersediaan transport (MCP / REST / gRPC)

Anda memanggil setiap alat dalam tutorial ini dengan cara yang sama melalui MCP tools/call, endpoint alat REST, dan layanan gRPC. Semuanya berjalan melalui tool executor yang sama.

Tier risiko HITL

Mengaktifkan mode tagged dan menggunakan alat konten berada di tingkat caution. Standards check bersifat hanya-baca (read-only). Jalur keluaran untuk penulisan berkas memerlukan persetujuan, sedangkan mode base64 tidak. Lihat /connect/hitl-risk-tiers/.

Envelope JSON confirmation gate

Ketika jalur keluaran penulisan berkas dipasangi gate, gate akan mengembalikan envelope tantangan dan token sekali pakai. Token tersebut terikat pada nama alat, sebuah nonce, dan time-to-live (TTL) 300 detik. Untuk melanjutkan, panggil ulang alat tersebut dengan arguments._confirmation_token. Lihat /connect/hitl-risk-tiers/.

Lihat juga

• /cookbook/connect/conformance-mode/ — diskriminator mode di balik mode tagged.
• /cookbook/connect/aria-tagged-pdf/ — pemetaan landmark role.
• /cookbook/connect/page-artifacts/ — mengecualikan konten dekoratif dari pohon struktur.
• /connect/tool-catalog/ — komputasi set alat per tier.