ADR-0057: Rental listing slugs are immutable public identifiers
Status
Accepted (2026-08-26)Tags
rental, seo, slug, url, data-model, product-boundary, adr-0055, adr-0056Decision
Arental_listings.slug is generated once and never changes.
- Generated on the first transition to
live, and only whenslugis null. A rejected-then-resubmitted listing, or a suspended-then-restored one, reuses the slug it already has. - Composition:
{bedrooms}-bedroom-{property_type}-{area}-{suffix}, for example3-bedroom-condo-petaling-jaya-k4m2. This mirrors the public page title the marketplace renders (“3-bedroom condo for rent in Petaling Jaya — RM2,000/month”). - Suffix always present: a 4-character random suffix on every slug, not only on collision.
- Degradation: any part that slugifies to an empty string is dropped. A room listing
has no meaningful bedroom count;
areais free text an owner may type in Chinese or Malay, which ASCII slugification can reduce to nothing. If every part drops out, the slug is the suffix alone. Slug generation never fails an approval.
Why
/property/{slug} is the URL Google indexes and the URL that sits inside every listing
shared over WhatsApp — in this market, a real traffic source. If a slug can change, then
an ordinary edit silently 404s every indexed link and every message already sent, and the
SEO authority the public marketplace exists to accumulate is destroyed by an action no
one would think to check.
The generate-only-when-null rule matters more than it looks. Slice 1 generates the slug at
admin approval, and its state machine allows a listing to reach an approved state more
than once (reject → resubmit → approve; suspend → restore). Regenerating on each approval
would break indexed URLs through the admin’s action, in a code path no owner or tenant
would ever associate with a broken link.
The always-on suffix removes a uniqueness check from the write path entirely. Two owners
listing “condo in Petaling Jaya” is not an edge case, it is the common case, and a
collision-only suffix still races under concurrent inserts.
Considered options
- Slug re-derives on edit, old slug 301-redirects — rejected for now. Correct, but needs a slug-history table and redirect handling in the Astro app for a problem that does not exist yet. This is the upgrade path if listing titles ever become editable user-facing text worth reflecting in the URL.
- Slug re-derives on edit, old URL dies — rejected. Quietly destroys the indexed links and shares the marketplace exists to earn.
- Slug is the listing ID alone — rejected. Immutable and collision-free, but discards the keyword value in the URL, which is a large part of why slugs are used instead of IDs.
- Suffix only on collision — rejected. Requires a uniqueness query inside the write path and still races under concurrent inserts, for a cosmetic gain on a minority of URLs.
Consequences
- Slug composition depends on
bedrooms,property_type, andarea, which live onrental_properties. Editing any of them after approval does not change the slug, so a slug can become mildly stale relative to the listing. Accepted: a slightly stale URL is invisible to users and costs nothing, while a changing one costs every inbound link. - There is no
titlecolumn onrental_listings; the slug and the public page title are both composed from structured fields. If a title field is ever added, this ADR is what must be revisited first. - Because slugs never change, cache staleness has a bounded blast radius: a stale public page always points at a slug that still resolves.