URL variables
Look up any variable you can put in a Template URL, what it does, and the message Studio shows when a pattern is wrong. For how patterns work, see How template URLs work.
The example on this page is a Blog post content type whose entries live under /blog. Its entry AI 101 has the slug ai-101 and the URL /blog/ai-101. Its author field references an Author entry whose handle is priya, it's tagged with the term ai in the topic taxonomy, and its seo group has a canonical field holding ai-101.
All variables
| Variable | Connected template | Freeform template | What it does |
|---|---|---|---|
{{entry.<field>}} | Yes | No | Matches that field's value. Works for fields inside a group or global field. |
{{entry.url}} | Yes | No | Matches the entry's URL field against the text in its place or against the whole address. Always put a prefix in front of it, such as /blog/{{entry.url}}. See Always put a prefix in front of entry.url. |
{{entry.<reference>.<field>}} | Yes | No | Matches a field on a referenced entry, such as {{entry.author.handle}}. |
{{taxonomy:<uid>}} | Yes | No | Matches a term from that taxonomy. |
{{locale}} | Yes | Yes | Sets the language of the content. |
{{composition_uid}} | Yes | Yes | Must equal this template's Template UID. |
{{content_type_uid}} | Yes | No | Must equal the connected content type's UID. |
{{environment}}, {{branch}} | Yes | Yes | Match any text and change nothing. Your site reads the environment and branch it's connected to. |
Spaces inside the braces are ignored, so {{ entry.slug }} and {{entry.slug}} are the same. The one exception is a Custom Preview URL that Studio copies. See Variables a Custom Preview URL can use.
Entry fields
When you save a pattern you typed on a connected template, Studio checks every field in it against the content type.
| You can use | Example |
|---|---|
| A top-level field | {{entry.slug}} |
| A field inside a group or global field | {{entry.seo.canonical}} |
| A field on a referenced entry | {{entry.author.handle}}, which gives priya |
| The entry's URL field | {{entry.url}}. The content type needs a URL field. |
These system fields work on every content type without being in its schema: uid, created_at, updated_at, created_by, updated_by, locale, _version. Use them at the top level only, such as {{entry.uid}}.
| This doesn't work | What happens | What to do instead |
|---|---|---|
A whole group, global or reference field, such as {{entry.seo}} | Save accepts it, but it writes nothing into the address, so the template never matches. | Point at a text field inside it, such as {{entry.seo.canonical}}. |
| A field inside a modular block | Save rejects it. | Use a field outside the block. |
A path that continues past a field that isn't a group, global or reference field, such as {{entry.slug.first}} | Save rejects it. | End the path at that field. |
Taxonomy
{{taxonomy:<uid>}} matches a term from the taxonomy with that UID. Studio writes the term's UID, not its name. For AI 101, /blog/{{taxonomy:topic}}/{{entry.slug}} becomes /blog/ai/ai-101. Studio doesn't check the taxonomy UID when you save, so a typo only shows up as an address that never matches.
Context variables
| Variable | In the canvas preview | On your live site |
|---|---|---|
{{locale}} | The canvas language | The language in the address. If you also pass a locale to the SDK, the one in the address wins. |
{{environment}} | The environment's name | Matches any text. Your site reads the environment it's connected to. |
{{branch}} | Always main | Matches any text. Your site reads the branch it's connected to. |
{{composition_uid}} | The Template UID | Must equal the Template UID, or the template doesn't match. |
{{content_type_uid}} | The connected content type's UID | Must equal the connected content type's UID, or the template doesn't match. |
Not supported
Studio rejects date variables when you save. These are {{entry_created_date:year}}, {{entry_created_date:year_short}}, {{entry_created_date:month}}, {{entry_created_date:monthname}}, {{entry_created_date:monthname_short}} and {{entry_created_date:day}}. To put a date in an address, store it in a text field and use that field.
How values are written into an address
| Case | What Studio does |
|---|---|
| Any value | Uses it exactly as stored. No lowercasing, no slugifying, no trimming. |
A space, ?, #, & or a non-English letter | Encodes it, so a space becomes %20. |
A / inside a field value | Encodes it as %2F in the canvas preview. The exception is {{entry.url}} when its value starts with /. |
{{entry.url}} whose value starts with / | The canvas preview opens that value as the whole address, and ignores the rest of the pattern. |
| A field with several values, such as a multiple field, a multi-reference or several taxonomy terms | Uses the first value. |
| An empty value | Writes nothing, which can leave // in the address. |
How addresses are matched on your live site
| Rule | Example |
|---|---|
| Matching is exact. | /blog/ai-101 matches /blog/{{entry.slug}}. |
| Capital letters count. | /Blog/ai-101 doesn't match. |
| A trailing slash counts. | /blog/ai-101/ matches the template, but the slug it looks for is ai-101/, so no entry is found. |
| The address is decoded first. | %20 and a space are the same. |
| A variable can cover more than one segment. | {{entry.url}} matches /blog/ai-101, which is two segments. |
Digits and true/false are converted. | A slug of 2024 is looked up as the number 2024, so it won't match the text stored in the field. |
| Pass the path only. | Leave out the domain, the query string and anything after #. |
Variables a Custom Preview URL can use
Studio copies a Custom Preview URL into a new connected template only if all of these hold.
- The Custom Preview URL toggle is on.
- There's a row for this content type, or for all content types, on the
mainbranch. - Every variable in the path is one of these, with no spaces inside the braces:
{{environment}},{{locale}},{{branch}},{{contentTypeUid}},{{entry.<field>}}and{{taxonomy:<uid>}}.
If any of them fails, Studio skips it and uses the next source. Transformation rules are never applied. See Transformation rules aren't applied.
Avoid {{contentTypeUid}} in a Custom Preview URL that Studio will copy. Studio copies it and fills it in on the canvas, but your live site can't match it. Studio also rejects it if you edit and save that pattern.
Save-time errors
Studio checks the pattern when you save. Typing again clears the message.
| Message | What's wrong |
|---|---|
| URL pattern cannot be empty. | The field is blank, or has only spaces. |
| The variable "…" is invalid. Please check for typos. | A variable Studio doesn't know, such as {{slugg}}. In a freeform template, this also covers a misspelt prefix. |
| The variable "…" is not recognized. Check the syntax and spelling. | In a connected template, a misspelt prefix, such as {{entr.title}}, or a name:value variable that isn't a taxonomy. |
| You cannot use "…" in a freeform composition because no connected content type exists to query. | An entry, taxonomy or content_type_uid variable in a freeform template. The message names only entry or taxonomy. |
| The variable "…" is not allowed. Date variables and other pseudo variables are not supported. | A date variable. See Not supported. |
| The field "…" does not exist. Please ensure you enter only existing fields. | The content type, or a referenced content type, has no field with that name. |
| "…" is not a nested field and cannot be traversed further. | The path continues past a field that isn't a group, global or reference field, or goes into a modular block. |
| The reference field "…" is not a valid reference. | The field isn't set up to reference another content type. |
| Could not load the referenced content type for "…". Try again or check that the referenced content type exists. | Studio couldn't fetch any of the content types the field references. |
| The content type schema is still loading. Please wait a moment and try again. | You pressed Enter before the content type finished loading, or it couldn't be loaded. |
| Invalid URL pattern syntax. Please check your variable formatting. | Studio couldn't read the pattern. This is rare. An unclosed {{ is treated as plain text, not as an error. |
| Save failed: … | Studio checked the pattern but couldn't save it. The text after the colon comes from the error. |
Studio doesn't check for a leading slash, a maximum length, special characters, or a URL another template already uses.
Where to go next
- Understand how patterns turn into addresses: How template URLs work.
- Change or reset a template's URL: Edit or reset a template's URL.