Ekspresi nilai (Value Expressions)

Setiap tempat di Script yang memerlukan nilai (URL, body permintaan, nilai field, kondisi, nilai filter, id target, dan sebagainya) mengambil salah satu dari tiga bentuk di bawah ini. Pengecualiannya hanya dua. pattern pada Regex dan key pada Cache hanya ditulis sebagai literal, dan { /pointer } di dalamnya tidak diubah menjadi nilai. Dokumen ini menjelaskan ketiga bentuk tersebut, dari mana nilai berasal (root konteks), serta aturan map locale yang khas untuk data WEEGLOO. Semua field pada katalog Statement mengikuti aturan ini.

Tiga bentuk

Ketiga bentuk ini bersarang. Referensi ditempatkan pada operan JsonLogic, lalu hasil referensi tersebut dimasukkan kembali ke operasi lain.

Posisi data dan posisi ekspresi: kapan menambahkan $

JSON yang sama dibaca berbeda tergantung posisinya. Pembedanya adalah siapa yang memiliki key pada posisi tersebut. Key pada fields adalah id field dari Content Type dan key pada Http.body mengikuti skema API yang dituju, sehingga pada posisi seperti itu cat atau in harus berupa nama field, bukan operator.

Aturannya ada dua baris.

1. Pada posisi data, key tanpa $ selalu merupakan nama field. Untuk memakai operasi, tambahkan $ pada operator.
2. Begitu masuk ke ekspresi lewat $, seluruh bagian di dalamnya adalah ekspresi. Operator yang tersarang tidak memerlukan $ (boleh saja ditambahkan).

Jika ragu, tambahkan $ pada semua operator. Itu benar di posisi mana pun.

// Posisi data: cat adalah nama field pada Content Type (bukan operasi penggabungan)
"fields": { "cat": { "en-US": "hello" } }
 
// Menghitung di posisi data: $ hanya di batasnya, bagian dalamnya tetap apa adanya
"fields": { "tier": { "en-US": { "$if": [ { ">=": [ "{ /p/score }", 700 ] }, "gold", "silver" ] } } }
 
// Posisi ekspresi: ditulis apa adanya
"condition": { "and": [ { "<": [ "{ /a/body/risk }", 0.5 ] }, { ">=": [ "{ /b/body/score }", 700 ] } ] }

Ketika perlu nama field yang diawali $: $$

Ketika key memang harus diawali $, seperti $ref dan $schema pada JSON Schema, tulis $ dua kali. "$$ref" berarti key data $ref. Hanya satu $ terdepan yang dilepas ($$$ref menjadi $$ref), dan ini hanya berlaku pada key ($ di dalam nilai tetap apa adanya).

"body": { "$$ref": "#/components/schemas/Item", "topK": { "$min": [ "{ /payload/fields/k }", 50 ] } }

Dua hal yang ditolak

Kedua kasus di bawah ini tidak diam-diam ditafsirkan sebagai makna lain, melainkan ditolak sebagai error.

• Key $ yang berada bersama key lain pada objek yang sama adalah error. Operasi harus menjadi satu-satunya key pada objek tersebut, dan data saudaranya cukup dikeluarkan satu tingkat.
• Key $ yang tidak dikenal adalah error. $catt bukanlah field bernama $catt. Namespace $ dicadangkan untuk operator.

Di posisi ekspresi, nama operator yang berada bersama key saudara juga merupakan error ({ "and": […], "or": […] }). Pada posisi tersebut tidak ada tafsiran sebagai data dan semua objek dinilai benar, sehingga jika dibiarkan, kondisi akan diam-diam selalu bernilai benar.

Referensi: { /json-pointer }

Masukkan JSON Pointer RFC 6901 (harus diawali dengan /) di dalam kurung kurawal. Spasi di sekitar kurung kurawal diperbolehkan ({ /a/b } sama dengan {/a/b}).

Pointer tunggal vs. template campuran: aturan tipe

• Ketika seluruh string adalah pointer tunggal, nilai mempertahankan tipe aslinya (angka tetap angka, objek tetap objek, array tetap array).
• Ketika tercampur dengan teks literal, hasilnya adalah penggabungan string (concatenation).

"{ /payload/fields/count }"                 // jika nilai berupa angka, tetap angka (mis. 42)
"{ /payload/fields/tags }"                  // jika array, tetap array
"page-{ /payload/fields/n }-of-10"          // penggabungan string → "page-42-of-10"
"Bearer { /payload/fields/token }"          // penggabungan string → "Bearer abc123"

Nilai yang tidak ada

• Ketika path tidak ada atau nilainya kosong, pointer tunggal menjadi null dan template campuran menjadi string kosong.

Root konteks: dari mana nilai berasal

Segmen tingkat teratas dari { /pointer } adalah salah satu dari tujuh berikut.

Enam nama selain /<name> (payload·rawPayload·headers·now·vars·error) sudah dicadangkan sehingga tidak dapat dipakai sebagai name sebuah statement. Memakai nama yang sama berarti menimpa root tersebut, sehingga ditolak saat disimpan (aturan nama binding pada Field umum).

/rawPayload: body persis seperti yang dikirim

/payload adalah nilai hasil parsing, sedangkan /rawPayload adalah string asli dari body yang sama. Keduanya menunjuk hal yang sama, tetapi tidak identik. Jika nilai hasil parsing dijadikan string kembali, spasi, notasi angka, escape, dan key duplikat semuanya dinormalkan sehingga tidak kembali menjadi byte yang dikirim.

Karena itu, nilai yang dihitung di atas byte yang dikirim hanya dapat ditangani dengan /rawPayload. Kasus yang paling khas adalah verifikasi tanda tangan pada webhook penyedia pembayaran (Signature). Untuk referensi sehari-hari yang mengambil nilai, gunakan /payload.

Body pemanggilan hanya menerima objek JSON. Body yang kosong dianggap tidak ada, dan jika bukan objek JSON (JSON rusak, array, skalar, null literal), permintaan tidak dijalankan dan ditolak (lihat Error).

/now: waktu ketika eksekusi dimulai

/now menampung waktu saat eksekusi ini dimulai dalam tiga bentuk.

• Satu eksekusi hanya memiliki satu waktu. Ini bukan statement yang membaca jam, melainkan nilai yang ditanamkan ketika eksekusi dimulai, sehingga dua statement tidak mungkin melihat nilai yang berbeda. Setiap cabang Parallel juga mewarisi waktu yang sama. Karena bukan statement, ia juga tidak dihitung ke jumlah statement.
• Tidak ada field untuk memilih zona waktu. Nilai epoch adalah angka yang sama di mana pun, dan iso adalah notasi UTC.
• Dipakai untuk memverifikasi replay window webhook (berapa detik jarak timestamp yang dibawa tanda tangan dari sekarang). Timestamp biasanya masuk sebagai string, tetapi operasi aritmetika mengubahnya menjadi angka sehingga dapat dibandingkan apa adanya.

// Apakah timestamp yang dibawa tanda tangan berada dalam 5 menit (300 detik)
{ "<": [ { "-": [ "{ /now/seconds }", "{ /sig/1 }" ] }, 300 ] }

Bentuk hasil statement

Bentuk hasil dari statement yang membawa name berbeda-beda menurut tipenya.

• ResourceFind mengikat null jika tidak ada kecocokan. Bercabang berdasarkan keberadaan dengan { "==": [ "{ /found }", null ] }.
• ResourceRead (tunggal) adalah error jika targetnya tidak ada (dapat ditangani dengan Try). Detailnya dibahas di Membaca resource pada katalog Statement.
• Jika Anda membaca ServiceUser, hasilnya adalah resource anggota itu sendiri ({ /member/sys/id }). Berbeda dengan Content dan Media, field-nya bukan locale map melainkan nilai apa adanya. Aturannya dibahas di Membaca direktori anggota.

Operasi dan kondisi: JsonLogic

Ketika membutuhkan kalkulasi atau kondisi, gunakan objek operator dari spesifikasi jsonlogic.com.

• Akses data diseragamkan dengan referensi { /ptr }, bukan var vanilla (dot-path). Mesin me-resolve pointer operan terlebih dahulu, lalu menerapkan operator.
• Operator harus menjadi satu-satunya key pada objek tersebut. Di posisi data, hanya key yang diawali $ yang merupakan operasi; di posisi ekspresi, key adalah operasi terlepas dari ada tidaknya $ (lihat Posisi data dan posisi ekspresi).

Tabel operator

Nama pada tabel adalah token operator. Saat dipakai di posisi data, tambahkan $ di depannya (cat menjadi $cat). Di posisi ekspresi, keduanya sama-sama berlaku.

Operator iterasi array (map, filter, reduce, all, some, none) tidak didukung. Script mengiterasi array dengan Loop (lihat Loop pada katalog Statement). Memilih hanya item yang memenuhi kondisi tanggal dari sebuah daftar juga merupakan pekerjaan statement pembacaan, bukan pekerjaan iterasi. Berikan kondisi itu pada where milik ResourceFind atau ResourceForEach, maka server yang menyaring dan mengembalikannya (operator yang dapat Anda pakai ada di daftar operator).

Konversi numerik dan contoh

Aturan konversi numerik adalah sebagai berikut. Angka dibiarkan apa adanya, true menjadi 1, false menjadi 0, string di-parse (jika tidak dapat di-parse, kalkulasi gagal), dan null menjadi 0.

String tanggal bukanlah angka. "2026-10-03" tidak dapat di-parse menjadi angka, sehingga operator perbandingan selalu mengembalikan false tanpa memunculkan error. Untuk membandingkan tanggal, normalkan lebih dulu dengan date.

Cuplikan di bawah ini mengacu pada posisi ekspresi. Ketika dimasukkan ke posisi data (fields, Http.body, Return.value, SetVar.value), tambahkan $ pada operator terluar dan biarkan operan di dalamnya apa adanya.

{ "-":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // saldo - biaya
{ "<":  [ "{ /wallet/fields/balance/en-US }", "{ /payload/fields/cost }" ] }   // saldo < biaya → boolean
{ "and": [ { "<": [ "{ /a/body/risk }", 0.5 ] }, { ">=": [ "{ /b/body/score }", 700 ] } ] }
{ "cat": [ "id-", "{ /payload/sys/id }" ] }                                    // "id-<uuid>"
{ "!!": "{ /found/sys/id }" }                                                  // true jika ada
{ "$merge": [ "{ /vars/ids }", [ "{ /row/sys/id }" ] ] }                       // akumulasi array: SetVar.value adalah posisi data, jadi pakai $
{ "if": [ "{ /payload/fields/next }", "{ /payload/fields/next }", "END" ] }     // next jika ada, jika tidak "END"

Normalisasi tanggal (date)

Operator perbandingan mengubah operannya menjadi angka lalu membandingkannya. String tanggal bukanlah angka, sehingga perbandingan itu selalu bernilai false tanpa memunculkan error. Menggantinya dengan == pun tidak menyelesaikan masalah. Ketika kedua sisi bukan angka, teksnya sendiri yang dibandingkan, sehingga "2026-10-03" dan "2026-10-03T00:00:00.000Z", dua penulisan untuk momen yang sama, keluar sebagai nilai yang berbeda. Normalkan tanggal dengan date sebelum membandingkannya.

{ "date": [ nilai, satuan keluaran ] }  // satuan keluaran boleh dihilangkan
{ "date": "2026-10-03" }                // ketika hanya melewatkan satu nilai, array boleh dilepas

Tidak ada operator khusus before, after, atau equal. Nilai yang sudah dinormalkan berupa angka, jadi Anda cukup memakai operator perbandingan, aritmetika, dan agregasi yang sudah ada.

Hasil aritmetika kembali berupa angka milidetik, jadi Anda dapat memasukkannya sekali lagi ke date untuk mengeluarkannya sebagai iso atau day ("Satu minggu kemudian" pada tabel di atas).

// Posisi ekspresi: apakah kupon berada dalam masa berlakunya. Notasi ketiga nilai boleh berbeda-beda
{ "<=": [
  { "date": "{ /coupon/fields/startsAt/en-US }" },
  { "date": "{ /now/iso }" },
  { "date": "{ /coupon/fields/endsAt/en-US }" }
] }
 
// Posisi ekspresi: apakah header Date HTTP berada dalam 5 menit (300 detik) dari sekarang
{ "<": [ { "-": [ "{ /now/seconds }", { "date": [ "{ /headers/date }", "seconds" ] } ] }, 300 ] }

Input yang dibaca

Semua nilai di bawah ini dibaca sebagai momen yang sama.

• Jika tidak ada offset, nilainya dibaca sebagai UTC. Offset menerima +09:00, +0900, +09, maupun Z.
• Parsing bersifat ketat. Meskipun jumlah digitnya benar, tanggal yang sebenarnya tidak ada (2026-13-45) akan gagal.
• Satuan sebuah epoch dibedakan berdasarkan besar nilai absolutnya. Di bawah 100.000.000.000 berarti detik, dan mulai dari nilai itu berarti milidetik. Karena itu, { /now/seconds } maupun { /now/millis } yang Anda masukkan sama-sama dibaca dengan benar.
• Rentang yang diakui sebagai epoch adalah nilai absolut minimal 100.000.000 dan kurang dari 100.000.000.000.000. Karena satuannya harus dibedakan berdasarkan besar nilainya, rentang itu dibatasi di kedua sisi. Angka di luar rentang tersebut tidak dibaca sebagai tahun 1970, melainkan gagal. Tanggal tanpa pemisah 20261003, tahun 2026, dan 0 yang masuk dengan arti tidak ada nilai termasuk di sini.

Satuan keluaran

Operan kedua menentukan bentuk keluaran. Nama satuan tidak membedakan huruf besar dan kecil.

Nama yang tidak ada dalam daftar akan gagal, dan pesan kesalahannya menyebutkan nama-nama yang dapat Anda pakai.

Keluaran iso dan penulisan ke field Date

Field Date pada Content hanya menerima satu format saat penulisan, yyyy-MM-ddTHH:mm:ss[.desimal]Z. T, detik, dan Z di akhir semuanya harus ada, bagian desimal boleh disertakan maupun tidak, dan nilainya dibaca sebagai UTC. Karena itu, 2026-10-03 atau 2026-10-03T09:00:00+09:00 yang diterima melalui payload akan ditolak sebagai nilai yang tidak valid jika Anda masukkan apa adanya. Keluaran iso dari date tepat berupa format ini, jadi lewatkan tanggal yang Anda terima melalui date sekali sebelum menuliskannya ke field.

// Posisi data: menuliskan "2026-10-03" dari payload ke tanggal berakhirnya kupon
"fields": { "endsAt": { "en-US": { "$date": [ "{ /payload/fields/endsAt }", "iso" ] } } }

Nilai yang tidak dapat dibaca

Pada ketiga kasus di bawah ini, statement itu gagal (status 400). Ini adalah kegagalan yang muncul saat eksekusi, sehingga dapat ditangani secara lokal dengan catch milik Try.

• Operan pertama tidak ada, atau referensinya tidak menemukan nilai.
• Nilainya tidak dapat dibaca sebagai tanggal. String kosong, string yang hanya berisi spasi, string yang bukan tanggal, tanggal yang tidak ada, boolean, objek, dan angka di luar rentang yang diakui termasuk di sini.
• Nama satuan keluaran tidak ada dalam daftar.

Tidak mengembalikan null ketika nilainya tidak ada adalah kontrak yang disengaja. null menjadi 0 pada konversi numerik sehingga dibandingkan terhadap tahun 1970, jadi pemeriksaan dengan tanggal yang hilang bukannya gagal melainkan hasilnya terbalik. Kupon yang sudah lewat masa berlakunya lolos itu lebih buruk daripada eksekusi yang terhenti.

Penentuan benar dan salah (Truthiness)

if, and, or, !, !! beserta If.condition dan Loop.while menentukan benar dan salah dengan aturan berikut.

• falsy: null, false, angka 0, string kosong "", koleksi kosong (array kosong).
• truthy: selain itu semuanya (angka bukan 0, string dan array yang tidak kosong, dan semua objek).

Key juga bisa menjadi referensi

Key dari map seperti fields juga mendukung referensi { /ptr }. Key di-resolve saat runtime.

"fields": { "{ /payload/fields/fieldName }": { "en-US": "{ /payload/fields/fieldValue }" } }

Jika dua key di-resolve ke nilai yang sama, terjadi konflik dan menjadi error mesin.

Map locale: aturan khusus Content dan Media

Di WEEGLOO, setiap field dari Content atau Media bukanlah sebuah nilai melainkan map per-locale (misalnya, balance bernilai { "en-US": 1, "ko-KR": 10 }). Karena itu, locale harus ditangani bersama saat membaca dan menulis. Pada Media juga, title dan description (skalar) serta file (instruksi ingest) merupakan map locale. JSON yang bukan Content maupun Media, seperti /payload atau respons HTTP, tidak terpengaruh aturan ini (strukturnya tetap sebagaimana ditentukan skema, dan skalar tetap skalar).

Membaca

• Untuk memperoleh skalar, tentukan hingga locale: { /<name>/fields/<field>/<locale> } (misalnya, { /post/fields/title/en-US }).
• Tanpa locale, { /<name>/fields/<field> } menghasilkan keseluruhan objek map locale.
• Field localized:false hanya berada di bucket locale default, jadi dibaca dengan kode locale default tersebut.

Menulis (fields dari ResourceCreate, ResourceUpdate, ResourcePatch)

Nilainya adalah map locale { "<locale>": <ekspresi nilai skalar> }. Simetris dengan pembacaan.

"fields": {
  "title":  { "en-US": "Hello", "ko-KR": "안녕" },   // daftar bucket untuk beberapa locale
  "status": { "en-US": "paid" }
}

• ResourceCreate harus menyertakan bucket locale default Space pada setiap field yang diisi (aturan default-locale).
• ResourceUpdate adalah penggantian penuh. Field dan locale yang tidak ada di fields akan dihapus (termasuk file).
• ResourcePatch hanya memperbarui field dan bucket yang ditentukan (field dan locale lainnya dipertahankan).
• Menghapus dengan null literal: ketika nilainya adalah null literal, bucket (field, locale) tersebut dihapus (cara standar untuk mengosongkan locale tertentu dalam Patch). "" (string kosong) bukanlah penghapusan melainkan menetapkan nilai kosong. Ketika ekspresi nilai ({ /ptr }) dievaluasi menjadi null saat runtime, itu bukan penghapusan melainkan sebuah error (payload yang hilang tidak ditelan secara diam-diam). Hanya null literal yang menghapus.
• Media file: nilainya bukan skalar melainkan instruksi ingest { "source": …, "encoding": "url"|"base64" }. Apa yang sebenarnya dilakukan ingest dibahas di ResourceCreate pada katalog Statement.
• Field localized:false hanya dimasukkan ke bucket locale default.
• Kode locale (key map) juga bisa berupa referensi { /ptr } (lihat Key juga bisa menjadi referensi di atas). Digunakan saat membuat locale dinamis.

Field kemudahan locale

Ketika locale diberikan pada ResourceCreate, ResourceUpdate, atau ResourcePatch, mesin secara otomatis membungkus setiap nilai di fields ke dalam bucket { <locale>: nilai }. Artinya, cukup memberikan skalar saja.

// kedua contoh di bawah ini setara
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "locale": "en-US", "fields": { "title": "Hello" } }
 
{ "type": "ResourceCreate", "resource": "Content", "contentType": { "sys": { "id": "ct_post" } },
  "fields": { "title": { "en-US": "Hello" } } }

Jika locale diberikan sementara nilainya sudah menyarangkan map locale ({ "en-US": … }), hasilnya menjadi tersarang ganda sebagai { <locale>: { "en-US": … } } (kesalahan penulis). Satukan menjadi satu gaya: dengan locale, gunakan hanya skalar; tanpanya, gunakan hanya map locale eksplisit.

Locale dalam where dan order

• Di where dan order, untuk fields.X mesin secara otomatis menerapkan locale default Space (sama seperti kueri CMA).
• Untuk menetapkan locale tertentu, tentukan secara eksplisit sebagai fields.X.<locale>.

"where": { "fields.slug": { "eq": "{ /payload/fields/slug }" } }   // slug locale default
"where": { "fields.title.ko-KR": { "prefix": "안" } }              // locale tertentu

Error

Berikut adalah kode yang muncul ketika Anda melanggar aturan ekspresi nilai. Sistem memeriksa aturan ini saat penyimpanan definisi, dan kode yang melanggar batasan statis lain pada definisi ada di Error pada Semantik eksekusi, batasan, dan keamanan, sedangkan kode yang muncul saat pemanggilan ada di Error pada endpoint. Untuk kode yang berlaku umum pada semua resource, lihat Error umum.

Dokumen terkait

• Katalog Statement: Field dan hasil dari 25 jenis statement yang menggunakan ekspresi nilai.
• Semantik eksekusi, batasan, dan keamanan: Urutan eksekusi, error, penguncian optimistis, dan batasan statis.
• Cookbook: Contoh lengkap yang menggabungkan ekspresi nilai.
• Ikhtisar Script: Struktur tingkat atas dan waktu yang diberikan untuk satu eksekusi.