Skip to content

What are the most common metadata mistakes?

The Canonical URL

One of the most common mistakes is omitting or incorrectly specifying the canonical URL. Note that this must be specified as the “url” property in a JSON-LD tag or as the value of a “parsely-link” tag when using repeated metatags. uses this URL to group traffic from different versions of the same article in one place. For example, you might have the URL on your desktop site, while the mobile version is at That’s fine, as long as the URL in the metadata is the same text string for both. Similarly, you might serve two different versions of an article: one with an “http” URL, and one with “https.” Again, no problem; just make sure they both have the same canonical URL in their metadata. We recommend using the desktop version of a URL, prefixed with “https://”, as your canonical.

Note that if you include a post-id value in your metadata, which is optional, it will take precedence over the canonical URL value, and we will group your articles by post-id instead. However, we discourage including post-id values whenever possible. Grouping articles by canonical URL is a simpler and more reliable implementation.


Invalid metadata as a result of small errors is another common problem. Our documentation outlines your metadata formatting options (we recommend JSON-LD). A single error in the metadata tag–a missing quotation mark, an unescaped special character, a field name in the wrong case–may prevent an article from registering its metadata properly, causing it to show incorrectly as an index or no-metas page in your dashboard. You should escape double-quotes within your metadata values.

Article Section Values

You can only list one value for an article’s section/category, though you can list as many as 100 values in the tags/keywords field (formatted as an array of strings). You can also list multiple author values, again as an array of strings. These values are case-sensitive, which is important to remember if you’re trying to pull data from our API.

Many publishers want to track subsections in the tags field. The best way to do that is to separate the section/subsections with a colon in a single tag; for example “sports:football” or “sports:basketball:wnba”.

UTC Time

An article’s publication date should be listed in UTC format, with no offset, in your metadata; for example: “pub_date”: “2013-08-15T13:00:00Z”. We’ll display it in the dashboard according to your local timezone, however.

Last updated: August 16, 2023