Format JSON roadmap (skema 1.0.0)

Satu format resmi dipakai bersama oleh import, export, editor roadmap (mode JSON), Prompt Generator, dan eksekusi AI. Apa pun yang lolos validasi di salah satu fitur itu bisa diekspor lalu diimpor kembali tanpa perubahan.

• JSON Schema (struktur & tipe): roadmap.schema.json — sumber: resources/schemas/roadmap-1.0.0.schema.json
• Validator aplikasi (struktur + aturan relasi): app/Roadmaps/Schema/DocumentValidator.php

Struktur dokumen

{
  "schemaVersion": "1.0.0",
  "roadmap": {
    "title": "Backend Developer",
    "slug": "backend-developer",
    "description": "Roadmap pembelajaran pengembangan backend.",
    "category": "Software Development",
    "difficulty": "intermediate",
    "estimatedDurationHours": 240,
    "tags": ["backend", "api", "database"],
    "status": "draft",
    "allowSkip": false,
    "metadata": {},
    "nodes": [
      {
        "id": "node-001",
        "type": "topic",
        "title": "Fundamentals",
        "description": "Memahami dasar pengembangan perangkat lunak.",
        "position": { "x": 400, "y": 100 },
        "estimatedDurationHours": 20,
        "isOptional": false,
        "learningObjectives": ["Menjelaskan cara kerja HTTP"],
        "subtopics": ["DNS", "HTTPS"],
        "resources": [
          { "type": "documentation", "title": "MDN - HTTP", "url": "https://developer.mozilla.org/en-US/docs/Web/HTTP" }
        ],
        "exercises": ["Periksa header respons dengan curl"],
        "notes": null,
        "metadata": {}
      },
      { "id": "node-002", "type": "topic", "title": "Database" }
    ],
    "edges": [
      { "id": "edge-001", "source": "node-001", "target": "node-002", "type": "required" }
    ]
  }
}

Beberapa roadmap sekaligus (hasil export massal) memakai "roadmaps": [ … ] sebagai pengganti "roadmap". Bundel hanya bisa diimpor dengan mode Create New.

Field

Dokumen

Field	Wajib	Keterangan
schemaVersion	ya	Versi skema. Saat ini hanya 1.0.0.
roadmap / roadmaps	ya (salah satu)	Satu roadmap, atau array 1–50 roadmap.
exportedAt, generator	tidak	Informasi export; diabaikan saat import.

Roadmap

Field	Wajib	Tipe	Keterangan
title	ya	string ≤ 160
slug	disarankan	a-z0-9- ≤ 160	Dibuat dari judul bila kosong (peringatan).
description	tidak	string ≤ 5000	Wajib terisi sebelum roadmap diterbitkan.
category	tidak	string	Nama kategori; dibuat otomatis bila belum ada.
difficulty	tidak	string	Key tingkat kesulitan yang dikelola admin (beginner, intermediate, advanced, expert, …). Key yang tidak dikenal ditolak.
estimatedDurationHours	tidak	angka ≥ 0	Dibulatkan ke jam.
tags	tidak	array string (≤ 20, ≤ 60 karakter)	Duplikat (tanpa membedakan huruf besar) digabung; tag dibuat otomatis.
status	tidak	draft | published | archived	Default draft. Saat import hanya dipakai bila opsi gunakan status dari file dicentang.
allowSkip	tidak	boolean	Mengizinkan status Skipped bagi pelajar.
icon, metadata	tidak	string / object	metadata bebas, maksimal 20 KB.
nodes	ya	array 1–500
edges	ya	array ≤ 2000	Bila tidak ada: peringatan, roadmap tanpa relasi.
internal	tidak	object	Hanya di export dengan metadata internal; diabaikan saat import.

Node

Field	Wajib	Keterangan
id	ya	Unik dalam roadmap. 1–100 karakter: huruf, angka, -, _, ., :; diawali huruf/angka. ID adalah identitas node: progres dan catatan pelajar disimpan per ID.
type	ya	topic, subtopic, prerequisite, optional, project, assessment, resource, milestone, section.
title	ya	≤ 160 karakter.
description	tidak	≤ 10000 karakter.
parent	tidak	ID node induk: subtopic → topic, atau anggota → section. Harus ada dan tidak boleh membentuk siklus.
position	tidak	{ "x": angka, "y": angka }. Bila kosong, posisi dihitung otomatis (layout berlapis berdasarkan dependensi).
estimatedDurationHours	tidak	0–10000.
isOptional	tidak	Materi opsional (sama seperti type: "optional").
learningObjectives, subtopics, exercises	tidak	Array string (≤ 50 item, ≤ 500 karakter).
resources	tidak	≤ 30 item { "type", "title", "url", "language"?, "isFree"? }. type: article, documentation, video, course, book, tool, other. Hanya URL http:// / https://.
notes, icon, group, metadata	tidak

Edge

Field	Wajib	Keterangan
id	ya	Unik dalam roadmap.
source, target	ya	ID node yang ada. Tidak boleh sama (self-loop). Pasangan source → target tidak boleh duplikat.
type	tidak	required (default): source wajib dikuasai sebelum target · optional: urutan yang disarankan · related: tautan "lihat juga" tanpa urutan.
label	tidak	≤ 80 karakter.

Urutan array tidak berarti urutan belajar. Urutan dan prasyarat hanya dinyatakan lewat edges. "Prasyarat" di panel detail node = sumber edge required yang menuju node tersebut.

Aturan validasi

Dokumen ditolak (dengan lokasi field, mis. roadmap.edges[4].target) bila:

1. bukan JSON valid, atau root bukan object;
2. schemaVersion tidak ada / tidak didukung;
3. field wajib tidak ada, tipe salah, melebihi panjang/batas, atau nilai enum tidak valid;
4. ID node atau edge duplikat;
5. edge atau parent merujuk ID yang tidak ada, self-loop, atau pasangan edge duplikat;
6. edge required/optional membentuk siklus dependensi (pesan menampilkan jalurnya, mis. a → b → c → a) — ubah salah satunya menjadi related bila memang hanya tautan;
7. relasi parent membentuk siklus;
8. URL resource bukan http(s).

Peringatan (tidak menolak): field tidak dikenal (diabaikan), slug dibuat otomatis, node tanpa relasi, node tanpa posisi.

Sebelum diterbitkan, roadmap juga harus memiliki deskripsi dan minimal satu node materi (selain section/resource).

Mode import

Semua mode diawali preview (perbandingan node/edge yang ditambah, diubah, dihapus) dan disimpan dalam satu transaksi database: bila validasi atau penyimpanan gagal, tidak ada data yang berubah. Setiap import yang berhasil membuat versi baru roadmap sehingga bisa di-rollback.

Mode	Aturan
Create New	Membuat roadmap baru dengan slug dari file (atau slug pengganti). Slug yang sudah dipakai ditolak. Status selalu draft kecuali opsi gunakan status dari file dicentang. Bundel didukung: semua roadmap dibuat, atau tidak sama sekali.
Replace Existing	Metadata, node, dan edge roadmap tujuan menjadi persis isi file. Slug dan status tujuan tetap. Butuh centang konfirmasi. Node yang ID-nya sama diperbarui di tempat; node yang tidak ada di file dihapus.
Update Existing	Penggabungan berdasarkan ID. Field roadmap yang ada di file menimpa; yang tidak ada tetap. Node/edge dengan ID sama digabung secara dangkal (field di file menimpa field lama, field lain tetap); ID baru ditambahkan; ID yang tidak ada di file dipertahankan, kecuali opsi hapus yang tidak ada di file dicentang. Edge yang kehilangan node ujung otomatis dibuang (dilaporkan). Hasil gabungan divalidasi ulang secara penuh — misalnya bila gabungan membentuk siklus, import ditolak.
Dry Run	Menjalankan validasi + perhitungan perubahan untuk mode yang dipilih, mencatat ringkasan, tanpa menyimpan apa pun. Import yang sama tetap bisa dikonfirmasi setelahnya.

ID yang berubah diperlakukan sebagai node lama dihapus + node baru ditambahkan.

Progres pelajar tidak pernah dihapus oleh import, replace, atau rollback. Progres disimpan per (roadmap, ID node). Bila node dihapus, progresnya tetap tersimpan (tidak dihitung) dan muncul kembali bila node dengan ID yang sama ditambahkan lagi. Preview menampilkan peringatan berapa pelajar yang memiliki progres pada node yang akan dihapus.

Export

• Satu roadmap → dokumen roadmap; beberapa/semua → bundel roadmaps.
• Opsi tanpa posisi menghilangkan position (posisi dihitung ulang saat import).
• Opsi metadata internal menambahkan internal (ID, versi, tanggal, jumlah dilihat) — diabaikan saat import.

Perhitungan progres

• Dihitung hanya dari node yang dapat dipelajari: semua tipe kecuali section dan resource.
• Persentase = node wajib selesai ÷ node wajib. Node opsional (type: "optional" atau isOptional: true) dilaporkan terpisah dan tidak pernah menurunkan persentase wajib.
• Status skipped dihitung selesai hanya bila roadmap allowSkip: true.