Skip to content
Faisal Mahmud TusherDigital marketing, SEO & analytics
with Faisal Tusher

SEO › Technical SEO

Writing SEO Requirements for Developers

Turn SEO needs for a new template or feature into requirements developers can build and test: URLs, indexing, rendered content, metadata, markup and checks.
Tutorialintermediate9 min readUpdated

Why requirements beat fixes after launch

The technical SEO audit ends by writing tickets for problems that are already live: duplicate URLs, missing canonicals, content that only appears after scripts run, titles left at a default. Every one of those was a decision someone made while building the template, usually without knowing it was a decision. Fixing them afterwards costs more than specifying them: the template is rebuilt, the bad URLs have been crawled and sometimes indexed, and the fix competes with new work for a place in the backlog.

A requirement moves the SEO decisions to the moment they are cheapest. It also changes the conversation with developers. A request to "make it SEO-friendly" invites guesswork; a statement such as "every gallery page returns a self-referencing canonical built from its clean URL, tested on these five URLs" can be built, estimated and checked. Google's documentation gives the reasons behind most rules, from crawlable links to canonical signals, and the requirement translates those reasons into behaviour. The academy checkpoint on server logs, parameters and developer requirements tests writing a requirement developers can build and test, and why one agreed before release beats a fix after it.

Before you start

  • The feature brief or design. What the product team is building, who it is for, and wireframes or prototypes of the template.
  • The data model. The fields the template will be filled from, which are required and which can be empty. Fallbacks depend on knowing what can be missing.
  • The site's URL and indexing conventions, if they exist: trailing slashes, case, parameter rules, and which page types are indexable. The site architecture guide covers the structure they should follow.
  • The keyword map entries for the queries the new pages are meant to serve, so the requirement knows what each page type is for.
  • A developer who knows the platform, available to review the draft for feasibility.
  • A requirement template. One document per template or feature, with a section per step below and a table of test URLs at the end.

The steps

  1. Describe the page type and its job

    Start with one paragraph: what the page type is, which searches or visitors it serves, how many pages it will create and how they will grow, and which existing pages it sits beside. Name the queries from the keyword map that it owns, and the existing pages it must not compete with. This paragraph settles arguments later: when someone asks whether a filtered view should be indexable, the answer comes from the job the page type was given, not from opinion.

  2. Set the URL rules

    Write the exact pattern for every URL the feature creates, with examples. Google's SEO Starter Guide recommends descriptive URLs and grouping topically similar pages in directories, so say which words go into the path, where they come from and what happens when they change. State the conventions explicitly: lower case, hyphens, trailing slash or none, one form only, with every other form redirected. List every parameter the feature reads and its class, as the URL parameter audit defines them. Say what happens when a page is renamed or deleted: a redirect to the new URL, or a not-found response.

  3. Set the indexing and canonical rules

    For every URL type the feature creates, state whether it is indexable, where its canonical points and whether it appears in the XML Sitemap. Google's documentation on duplicate URLs treats a canonical link and a redirect as strong signals and sitemap inclusion as a weaker one, and recommends that the signals agree; write the rules so they do. Indexable pages carry a self-referencing Canonical Tag built from the clean, absolute URL, not from the address the visitor requested. Pages that must exist but stay out of search carry a noindex, which Google's noindex documentation says can be set as a meta tag or as an HTTP response header, and which works only if crawlers are allowed to fetch the page. Say which robots rules, if any, apply.

  4. Specify what the rendered HTML must contain

    List what must be present in the HTML a crawler receives: the main heading, the body content, the internal links, the metadata and the structured data. Google's JavaScript basics describe crawling, rendering and indexing as separate phases, and note that server-side or pre-rendering is still a good idea because it makes sites faster and not every crawler runs JavaScript. Require important content and links in the server response where possible. Require every link to be an anchor element with an href to a real URL, since Google's link guidance says those are the links it can follow. Require each indexable view to have its own URL that returns the content when requested directly. The JavaScript SEO guide lists the failure modes to rule out.

  5. Specify metadata and its fallbacks

    For the Title Tag, meta description, main heading, image alt text and any social tags, name the source field and the pattern, then the fallback for when the field is empty, too long or duplicated. Google's Starter Guide asks for titles that are unique, clear and descriptive and for descriptions that summarise the page; templates that pull from optional fields break that silently. Say where metadata is set: Google's JavaScript basics warn that if a page carries a noindex before JavaScript runs, Google does not render or index it, so a script cannot be relied on to remove one. Directives and canonicals belong in the initial HTML.

  6. Map structured data to data fields

    If the page type uses Schema Markup, write a table with one row per property: the property, the data field that fills it, whether it is required, and what happens when the field is empty. Omit a property rather than fill it with a placeholder. Every value marked up must also be visible on the page. The structured data guide covers which types to use and how to validate them; the requirement's job is the mapping, so that markup is generated from the same data the visitor sees.

  7. Set performance and mobile expectations

    State the Core Web Vitals outcome the template must reach, in the terms the Core Web Vitals guide uses, and the design rules that make it likely: image dimensions declared, the main image not lazy-loaded, third-party scripts named and justified, space reserved for anything that loads late. Add the mobile expectations: readable text without zooming, usable tap targets, no overflow, and no overlay covering the content on arrival, as the page experience guide describes.

  8. Write acceptance criteria and test URLs

    Turn every rule into a check with an expected result: "the canonical on any gallery URL with a style parameter points to the gallery without it". Then list the test URLs that exercise the rules, including the awkward ones: a page with every field filled, one with optional fields empty, a very long title, special characters, an empty listing, a deleted item, a parameter variant and an uppercase variant. For each, write the expected status code, canonical, directive, title and heading. Say how each check is done, such as viewing the server response, the rendered HTML or a crawl of the test environment.

  9. Agree who checks what before release

    Name an owner for each group of checks: the developer runs the automated ones, the tester runs the test URLs, the SEO lead reviews the rendered output of each template on the test environment, and the product manager signs off any agreed compromise. Agree when the checks happen and what blocks a release. Release-day and post-release checks, staging protection and monitoring are a separate routine, covered in the SEO release checks guide; the requirement links to it rather than repeating it.

A requirement for a new template (illustrative)

Illustrative example — not a real result

Plumtrellis Furniture specifies a room-ideas gallery

Plumtrellis Furniture, an invented furniture retailer, plans a room-ideas gallery: styled room photographs with the products in each linked below. The launch creates about 300 idea pages across 6 room hubs, growing by around 20 a month. The requirement, in shortened form:

AreaRequirementAcceptance check
URLs/room-ideas/[room]/[idea-slug]/, lower case, trailing slash, slug from the idea title and fixed once publishedUppercase and no-slash variants redirect to the canonical form in one hop
IndexingRoom hubs and idea pages indexable and in the sitemap; ?style= views canonical to the hub; lightbox views create no URLFive test URLs return the expected canonical and status
Rendered HTMLIdea title as the main heading, a caption of at least two sentences, and product links as anchors in the server responseServer response contains heading, caption and every product link
MetadataTitle: idea name, room, brand; fallback to room and brand if the name is over 55 characters; description from the caption, trimmed to a sentenceTest URLs with long names and empty captions show the fallback
Structured dataBreadcrumb markup from the home page through the room hub, filled from the same fields as the visible breadcrumbMarkup validates on three test URLs; no property empty
PerformanceMain photograph eager-loaded with declared dimensions; gallery thumbnails lazy-loadedTemplate passes the agreed thresholds in lab tests on a mid-range phone
OwnershipDeveloper runs automated checks; tester runs the 12 test URLs; SEO lead reviews stagingRelease blocked until all three sign off

In testing, 2 of the 12 test URLs fail: an idea with an empty caption renders an empty description tag, and the lightbox writes a #photo-3 fragment that a script turns into a ?photo=3 parameter on share. Both are fixed before release instead of appearing in the next audit.

Working with developers and product managers

A requirement is a negotiation as much as a document. Share it as a draft early, while the design is still moving, and ask the developer to mark each line as possible, possible with work, or not possible on the platform. The third answer is the useful one: it surfaces limits while there is still time to choose a compromise, such as keeping a view off the URL entirely when the platform cannot set a canonical on it.

Explain the reason for each rule in a sentence, with a link where the reason is documented. Developers accept "Google follows anchor elements with an href, so these must be links, not click handlers" far more readily than a bare instruction, and the reason helps them apply the rule to cases the requirement did not foresee. Product managers need the cost of each rule: what breaks in search if it is skipped, and what the compromise gives up.

Keep the requirement after launch. It becomes the reference for the template's intended behaviour, the baseline for the next audit and the source for the publishing checks editors run on individual pages, such as the steps in the web page publishing SOP and the SEO page publishing checklist. When a later change touches the template, update the requirement in the same ticket. The academy capstone on an evidence-led SEO programme for a classic car parts retailer practises setting the requirement process for a year of template releases beside crawl evidence, tested changes and a forecast.

Common mistakes

  • Writing "SEO-friendly" instead of a rule. Every reader builds something different.
  • Specifying the happy path only. Templates fail on empty fields, long names and deleted items; test URLs must include them.
  • Leaving directives to JavaScript. A noindex or canonical changed by script after load contradicts the initial HTML, and a noindex removed by script may never be seen.
  • No owner for the checks. Criteria nobody runs are decoration.
  • Rules that contradict each other. A canonical rule undone by a sitemap rule, or a robots block that hides a noindex; read the indexing rules together.
  • Asking for markup the data cannot fill. Placeholder values in structured data are worse than none.
  • Throwing the requirement away after launch. The next change to the template repeats the old mistakes.

Frequently asked questions

How detailed should an SEO requirement be?

Detailed enough that a developer can build it without asking and a tester can check it without the SEO in the room. That usually means exact URL patterns, the rule for every directive, the source field for every piece of metadata, the fallback when the field is empty, and a list of test URLs with the expected result for each. Anything left as 'SEO-friendly' will be interpreted differently by everyone who reads it.

Should SEO requirements be one document or tickets?

Both, in that order. Write one requirement for the template or feature so the rules can be read together and checked for contradictions, then split it into tickets that each reference the requirement. Tickets written without the whole picture tend to contradict each other, such as a canonical rule in one ticket that a sitemap rule in another undoes.

What if the platform cannot do what the requirement asks?

Find out before the build, not during testing. Share the draft with the developer who knows the platform and mark each requirement as possible, possible with work or not possible. For anything not possible, write down the compromise and its cost, such as keeping a filter off the URL entirely if the platform cannot set a canonical on filtered views. A requirement nobody can build is not a requirement.

Terms used on this page

Tools to try

Frameworks

Where this page is used

Part of these learning paths

Sources

  1. SEO Starter Guide — Google Search Central
  2. Understand JavaScript SEO basics — Google Search Central
  3. Link best practices for Google — Google Search Central
  4. Consolidate duplicate URLs — Google Search Central
  5. Block Search indexing with noindex — Google Search Central

Related