Semantic URL Guide: Architecture & Best Practices

A semantic URL is a web address that uses clear, human-readable words to describe the content of a page and its location within a website's hierarchy. Often called a "friendly URL," it replaces technical strings of random characters or ID numbers with logical terms that people and search engines can understand before clicking.

What is a Semantic URL?

Semantic URLs represent a human-readable entry point for a website. Unlike traditional URLs that rely on database query strings (e.g., ?id=547), a semantic URL reflects the actual name of the web page and its organizational context.

These addresses function as an abstraction. While early web paths represented physical file locations on a server, modern semantic URLs are handled by web servers to provide a logical structure that makes sense to the end user rather than just the software.

Why Semantic URLs matter

• Search Engine Optimization (SEO): Search engines look for keywords in the URL string to help classify the page. If the URL corresponds with the page title, you reinforce the topic without losing text integrity.
• User Trust and Logic: Clear addresses allow users to guess the content of a page. A logical progression like /blog/lake-trip/fishing tells the user there is a broader category for "lake-trip" they can access by deleting the last part of the URL.
• Usability: Semantic URLs are easier to memorize, share, and reference from memory. They clarify where a user is and what they are interacting with.
• Deep Linking: [Pega’s Constellation architecture uses semantic URLs as an out-of-the-box feature for case and data types] (Pega Community) to allow users to bypass homepages and navigate directly to specific work items.
• Developer Maintenance: When the web development environment mirrors the semantic structure, developers can find specific sections more easily. This allows for database IDs to change behind the scenes without breaking the public-facing link.

How Semantic URL works

Semantic URLs replace complex internal information with application-specific identifiers.

1. Request: A user enters a readable URL or clicks a link like /products/screwdriver.
2. Routing: The web server or application uses a mechanism, such as a Routing Table, to map this friendly name to a specific resource or database entry.
3. Content Delivery: The server generates the content and serves it to the browser.

In some systems, like Pega, the pyRoutingTable rule defines how these URLs are generated and mapped to UI pages. If this table is missing or incorrect, it can result in "blank landing pages" because the system cannot map the URL to a component.

Best practices

• Avoid Unicode: Use Latin letters only. Do not include special symbols or characters from other languages.
• Use dashes as separators: Use dashes (-) instead of spaces to separate words.
• Keep it short: [Ideal URLs should remain under 100 characters, including the domain] (Unihost).
• Limit word count: [Google recommends including no more than five words in a title] (Unihost), which should ideally be reflected in the URL.
• Name media files semantically: Images should have descriptive names like thames-at-night.jpg rather than 1354AsDf.jpg to improve search classification in image results.
• Strip file extensions: Avoid including .php, .aspx, or .cgi in the URL. These relate to the server-side generation process, not the content being served to the user.

Common mistakes

Mistake: Changing URL structures after launch without a plan. Fix: Perform extensive planning of site hierarchy and naming conventions before implementation, as changing these later can break bookmarks and rankings.

Mistake: Including internal technical IDs for user-facing links. Fix: Use descriptive identifiers (e.g., /cases/employee-onboard) instead of handles (e.g., pyActivity=OpenWorkByHandle).

Mistake: Ignoring case inheritance. Fix: Ensure new case types are included in your routing rules or tables to prevent incorrectly formatted semantic URLs.

Semantic URL vs Traditional URL

Semantic URL Attacks

A semantic URL attack occurs when a client manually adjusts the parameters of a URL while maintaining its syntax. By altering the meaning—for example, changing a username in the address bar—a user may attempt to access unauthorized data. [Semantic URL attacks are primarily used against CGI-driven websites] (Wikipedia).

Example scenario: A password reset link looks like: .../resetpassword.php?username=user001&[email protected] An attacker might change user001 to user002 in their browser to see if the system sends the other user's password to the attacker's email. Using session variables is one recommended method to prevent these exploits.

FAQ

What is the difference between an absolute and a relative URL? An absolute URL contains the full address, including the protocol (HTTPS) and domain. A relative URL is used within a document and relies on the context of the current page to fill in missing parts, such as the domain or protocol.

Can I use any words I want in a semantic URL? Technically yes, but they should be planned. They should reflect the hierarchy of your menus and the specific content of the page. Avoid fluff and stick to keywords that help the user and search engines.

Do semantic URLs support file extensions like .html? While some developers include .html because it describes the content served to the browser, it is generally best practice to remove all extensions to keep the URL clean and independent of the underlying technology.

Why does my semantic URL show a "blank page"? This often happens in application frameworks like Pega when the routing table is not generated correctly. If the mapping between the friendly URL and the internal component is missing, the system cannot load the content.

Are there characters I should avoid? Yes. You should only use Latin letters and dashes. Avoid spaces, Unicode characters, and special symbols, as these can cause issues with browser compatibility and link sharing.