URL Standards

URLs are a highly visible attribute of your content that improve user experience, accessibility, and search rankings by providing:

• The location of the content within your site
• An indication of the priority of the content based on the depth (like the number of sub-directories in the URL path) of the content
• A high-level description of what the content is about
• Information about how the content is related to other content within your site.

A URL consists of a domain, sub-directories (optional), and a page name.

URL standards

URLs must be unique and distinctly different

• Each URL must be completely unique within a domain. 2 pages with the same URL can’t exist on the same site.
• Each URL must be specific enough to clearly differentiate each page. We can’t have multiple pages with very similar URLs.

URLs must adhere to formatting standards

• All alpha characters in URLs must be lowercase.
• All individual words must be separated by hyphens. Don’t use underscores or other characters as separators.
• URLs can’t include spaces.
• URLs can’t include special characters (excluding the hyphen to separate words).
• URLs can’t be longer than 2,000 characters or it may not be rendered correctly by all browsers.

URLs must be structurally accurate

• URLs must accurately represent the placement and hierarchy of the content/page. The hierarchy and structure represented in the URL help users and search engines understand the location and relationship between content on the site.
• URLs shouldn’t include invalid or empty sub-directories (like a directory that doesn’t contain any pages).
  • Advanced users often use the URL as a means of navigation. They often “hack a URL” by truncating it back to a sub-directory in order to get to broader content.
  • If an empty sub-directory is absolutely necessary (like for future planning), ensure the empty directory redirects users to a proper location so users don’t get a 404 error.

URLs must be readable, utilize plain language, and include appropriate and consistent keywords

• Users (and search engines) must be able to easily “read” the URL and gain an understanding of its content and purpose.
• URL keywords should be selected from the primary keywords used in the H1 of the page and accurately represent the content of the page.
  • If the content doesn’t include information on eligibility, don’t use the word “eligibility” in the URL. This can be misleading to users and search engines.
  • Primary keywords representing the content should be consistently used across headings, links, URLs, and navigation components.
• URLs must adhere to the same content style guide and plain language standards as the content of the page.
• URLs can’t have incorrect spelling or grammatical errors.

URLs must be clear, specific, and concise

• Don’t use overly broad terms that may be misinterpreted, or shorten URLs so much that meaning and context are lost. Be specific in describing the focus of the page.
• Don’t repeat keywords across multiple segments of a URL unless it’s necessary to clarify meaning of the content.
• Don’t include stop words, such as “a,” “the,” or “and,” unless it’s necessary to clarify meaning of the content.

URLs can’t include Personally Identifiable Information (PII) and Protected Health Information (PHI)

• No part of the URL, including parameters and anchor tags, can include information that can be used either by itself or in combination with other information to uncover that individual’s identity or health information
• Learn more about PII/PHI on the VA Platform website

Changing URLs or retiring content

• Always implement a redirect when pages are taken down or the URL changes
• This ensures users don’t encounter a 404 page or a broken link
• This also tells search engines to no longer index a page, and to pass any SEO value along to the new page

Guidelines for URLs in form flows

These are the guidelines for the individual pages within a form flow or other sequential flow.

URL slugs used in form flows must follow all core URL standards in this guidance document.

Links to your form should point to the core URL of your form, not a specific page

When linking to your form from another page, a navigation component, or external communication, always link to the core URL and not to a specific page.

This will reduce the risk of breaking links if specific pages in your form flow are changed, reorganized, or removed.

Example:

• Incorrect link: www.va.gov/health-care/apply-for-health-care-form-10-10ez/introduction
• Correct link: www.va.gov/health-care/apply-for-health-care-form-10-10ez/

Utilize standard URL slugs for core form pages

The following form flow pages have been standardized in the forms system:

• /introduction/: typically the first page of the form flow
• /review-and-submit/: step that allows the user to review their entered information prior to submitting
• /confirmation/: final page of a form flow displayed after form submission

Avoid using sub-directories, child pages, or nested pages in your flow

Form flows are linear and should have a flat, sequential structure. In other words, all pages in a form flow live on the same level in the hierarchy.

• Incorrect: form-url/page1/page2/page3/
• Correct: form-url/page1/, form-url/page2/, form-url/page3/

An exception to this would be if there is a clear fork in your form flow for different scenarios that would be ideal to track separately. For example, if a form is for Veterans and family members, but each audience has slightly different form flows, the structure would be:

• /form-url/veteran/page1/
• /form-url/family/page1/

Use logical numbering when collecting multiple responses to a single question

For questions in a form that allow users to enter multiple responses (also known as a list and loop) numbering of those responses should start at 1 and increment upwards.

The numbering can be embedded in the URL slug or be appended to the URL as a parameter.

Embedded URL example:

• /form-url/dependent-1/
• /form-url/dependent-2/

Parameter example

• /form-url/dependent/?name=1
• /form-url/dependent/?name=2

If using parameters, go to the standards for URL parameters for more information.

Avoid incorporating chapter names in the URL structure

For forms using chapter labels, incorporating those labels into each page slug can make it more challenging if chapters are renamed or reorganized.

An alternative is to use a similar initial term for pages that are directly related.

For related steps in a flow, consider using the same initial term

Using the same initial term in a URL slug can help to identify related pages in analytics.

Examples:

• Collecting more information on entries from a list and loop pattern
  • /dependent-1-contact
  • /dependent-1-address
  • /dependent-2-contact
  • /dependent-2-address
• A question where the response results in a follow-up question
  • /form-url/home-ownership/
  • /form-url/home-value/
• A series of questions all related to the same topic
  • /form-url/military-branch/
  • /form-url/military-service-period/
  • /form-url/military-other-names/

Guidelines for anchor tags

When using anchored links or “jump links,” in addition to all the URL standards above, use these guidelines when possible to create clean and understandable URL strings.

• Anchor tag IDs should be treated as part of the URL and preferably follow all the same standards as URLs.
• Ideally, the tag ID should be plain language keywords that help provide meaning to the content. For example, using a primary keyword from the associated heading. This works best for anchor tags on relatively static headings, such as the hub page.
  • Example: This link provides a user with quick access to tasks for managing their health care benefits:www.va.gov/health-care/#manage-your-health-and-benefits
• If the heading is lengthy, or could potentially change over time, using an ID (the content ID from drupal) is a another option. This works well for creating anchor links to accordions that hold frequently asked questions.

Guidelines for parameters in URLs

URL parameters (also known as query strings) are values added to the end of a URL that filter or organize the information on a page. Parameters are used for a number of reasons, most commonly for pagination, anchoring, filtering or sorting data, indicating language, or searching.

An example of a query string and parameter values in use on VA.gov is on our existing search functionality. The ? indicates the beginning of the query string, followed by 1 or more parameters (like page=1). Each parameter includes a key and a value, and multiple parameters are separated by an ampersand.

https://www.va.gov/search/?page=1&query=disability+compensation&t=true

Like the core URL, parameters must also be readable and understandable to the user, so they know what information is being used to display the content of the page, and don’t make the URL look untrustworthy. Parameters also impact SEO because they create unique URLs, so care must be taken to ensure they don’t dilute the SEO value of the static or canonical version of the page.

When adding parameters to your URL, in addition to all the URL standards, follow these guidelines:

• Don’t use any PII in parameter values, or any other data that shouldn’t be logged or tracked. This includes everything from names and contact information to unique identifiers used that an be used to identify a specific person, such as IP address, ICN, or EDIPI.
• Set the static, or main, URL as the canonical page using the rel=canonical attribute when the parameter-based URL is similar content to the canonical content. An example is when using parameters for sorting. The data returned is the same, but is in a different order, therefore include the rel=canonical attribute to tell search engines that the resorted page is the same as the original page.
• Parameter keys should be no more than 1 word for a label and must clearly define what the parameter is. Don’t use generic terms such as “parm” or “key.”
• Don’t expose empty or null value parameters in the URL.
• For multi-select type values, combine the values into a single parameter rather than exposing the key multiple times in a URL multiple times (like color=blue,red,white instead of color=blue&color=red&color=white).
• Avoid linking to URLs with parameters. Link to the static or canonical URL when possible.
• If multiple parameters are used in a query string, set a priority and list them in a consistent order.