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-0056

Decision

A rental_listings.slug is generated once and never changes.
  • Generated on the first transition to live, and only when slug is 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 example 3-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; area is 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, and area, which live on rental_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 title column on rental_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.