Title: Metadata: JSON-LD
Author: staff
Published: November 6, 2022
Last modified: November 19, 2025

---

 1. [Installation resources](https://docs.parse.ly/installation-resources/)
 2. [Parse.ly Integration](https://docs.parse.ly/installation-resources/parsely-integration/)
 3. [Metadata](https://docs.parse.ly/installation-resources/parsely-integration/metadata/)
 4. Metadata: JSON-LD

#  Metadata: JSON-LD

A `json-ld` script tag [uses the JSON format](https://json-ld.org/) to provide structured,
standardized and machine-readable information about a web page, such as its author,
publication date, title and the section in which it belongs. You may already have
existing `json-ld` tags on your pages that you can modify to include the additional
properties that Parse.ly requires.

If not, adding a tag such as the following example allows Parse.ly to properly track
the page. The body of the tag should be properly formatted JSON. To understand how
to customize the values for your site, continue to the detailed descriptions of 
each property below.

## Example

    ```lang-html
    <script type="application/ld+json">
    {
    	"@context": "http://schema.org",
    	"@type": "NewsArticle",
    	"headline": "Iron Man Revealed",
    	"url": "https://www.example.com/post/iron-man-revealed",
    	"thumbnailUrl": "https://www.example.com/tony-stark.png",
    	"datePublished": "2024-01-22T18:01:00Z",
    	"articleSection": "Defense News",
    	"creator": ["Peter Parker", "April O'Neil"],
    	"keywords": ["editor: jjjameson", "tony stark", "stark industries", "iron man"]
    }
    </script>
    ```

## Explanation of required properties

|   |   | 
| @context | The collection where the schema is defined. Always `[http://schema.org](http://schema.org)`. | 
| @type | The specific schema that is being used. For posts, we generally recommend [NewsArticle](http://schema.org/NewsArticle). For non-post pages, use [WebPage](http://data-pipeline-schema/.org/WebPage). For an explanation of the difference between the two, and additional alternatives, see the section on [distinguishing between “posts” and “pages”](https://docs.parse.ly/metadata-jsonld/#distinguishing-between-posts-and-non-posts-pages) below. | 
| headline | Post or page title (article headline). | 
| url | Specifies the [Parse.ly canonical URL](https://docs.parse.ly/the-parsely-canonical-url/) for post or page. For page groups, such as galleries, it should always point to the main page. For accurate data, canonical URLs specified in other metadata tags (such as `<link rel="canonical">` and `<meta property="og:url">` tags) must match, resolve, or redirect to this URL. For more information, please refer to our [documentation on shares integration](https://docs.parse.ly/social-shares-and-setting-consistent-urls/). | 
| thumbnailUrl | URL of the image associated with the post or page. | 
| datePublished | Publication date, formatted as an [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) UTC timezone string. | 
| articleSection | Section the page belongs to (e.g. “Programming”). _Note that only 1 section value is supported per URL_. Therefore, it is recommended that the top-level section or category is used and any sub-sections or child categories are added to keywords. | 
| creator | Author of the post provided either as a string or, for the [multi-author posts](https://docs.parse.ly/track-multiple-authors/), as a list. | 
| keywords | The list of keywords associated with the post will map to “Tags” in the Parse.ly dashboard. _Note that up to 100 keyword values are supported per URL_. |

If some of these fields don’t make sense for a particular page, consider whether
it’s better tracked as [a page instead of a post](https://docs.parse.ly/metadata-jsonld/#distinguishing-between-posts-and-non-posts-pages).

## Technical Caveats

 * **Handling special characters**. You may either use an [HTML entity](https://www.w3schools.com/html/html_entities.asp)
   to represent your special characters or you may escape them with a backslash (`\`).
   For example, `"headline": "&quot;Analyst&quot; found guilty of relying solely
   on \"anecdata\""` will return a headline of `"Analyst" found guilty of relying
   solely on "anecdata"`.
 * **Values in `json-ld` will appear literally inside Parse.ly Analytics.** Remember
   that _all metadata is case-sensitive._ String values supplied here (specifically`
   headline`, `creator`, and `articleSection`) as well as list values (specifically`
   keywords`) will appear in Parse.ly analytics _exactly_ as they are specified 
   in the tag. As a result, make sure to use proper capitalization and specify the
   values as you expect them to appear. Values with variations (example: “John Smith”
   and “john smith”) will appear _separately_ in the Dashboard causing duplication
   and skewed data.
 * **The `json-ld` script tag cannot be loaded asynchronously**. The Parse.ly crawler
   will not execute JavaScript. It must be able to access the metadata tag from 
   the results of a single GET request.

#### Standards compliance

All the properties above come from the schema.org [NewsArticle](https://schema.org/NewsArticle)
schema, making the example JSON-LD tag fully standards-compliant. To keep integration
as simple as possible, we’ve included only the properties that the Parse.ly crawler
actually uses. But there are many other valid schema properties you may also choose
to include, and that other services recommend or require. Scroll down to the additional
examples to see a `json-ld` tag that also includes the additional properties Google
recommends.

## Distinguishing between “posts” and “non-posts” pages

When collecting metadata, Parse.ly distinguishes between webpages that contain editorial
or marketing content which we refer to as “posts” (articles, reports, blog posts,
etc.), and those that are more transactional or navigational in nature, which we
refer to as “non-posts” (homepages, index pages, section pages, checkout pages, 
newsletter subscription pages etc.), based on the `@type` property specified.

In general, we recommend tracking pages that your editorial or marketing team produces
or works on actively as posts.

### `@type` values that Parse.ly recognizes as posts

While `NewsArticle` is the preferred `@type` value for posts, Parse.ly can also 
accommodate other types:

 * [NewsArticle](https://schema.org/NewsArticle)
 * [Article](https://schema.org/Article)
 * [TechArticle](https://schema.org/TechArticle)
 * [BlogPosting](https://schema.org/BlogPosting)
 * [LiveBlogPosting](https://schema.org/LiveBlogPosting)
 * [Report](https://schema.org/Report)
 * [Review](https://schema.org/Review)
 * [CreativeWork](https://schema.org/CreativeWork)
 * [OpinionNewsArticle](https://schema.org/OpinionNewsArticle)
 * [AnalysisNewsArticle](https://schema.org/AnalysisNewsArticle)
 * [BackgroundNewsArticle](https://schema.org/BackgroundNewsArticle)
 * [ReviewNewsArticle](https://schema.org/ReviewNewsArticle)
 * [ReportageNewsArticle](https://schema.org/ReportageNewsArticle)
 * [Recipe](https://schema.org/Recipe)
 * [AdvertiserCo](https://data-pipeline-schema/.org/AdvertiserContentArticle)[n](https://schema.org/AdvertiserContentArticle)
   [tentArticle](https://data-pipeline-schema/.org/AdvertiserContentArticle)
 * [MedicalWebPage](https://schema.org/MedicalWebPage)
 * [PodcastEpisode](https://schema.org/PodcastEpisode)

If a page contains multiple `json-ld` blocks with these `@type` values, the Parse.
ly crawler will preferentially choose the type that’s higher on the list. For example,
if both `Article` and `Review` blocks are present on a page, we will collect the
values from the `Article` block.

### `@type` values that Parse.ly recognizes as non-post pages

 * [WebPage](https://schema.org/WebPage)
 * [Event](https://schema.org/Event)
 * [Hotel](https://schema.org/Hotel)
 * [Restaurant](https://schema.org/Restaurant)
 * [Movie](https://schema.org/Movie)

While we expect posts to include all the properties in the main example above, not
all properties may be relevant on non-post pages (see example below).

### Non-post page example

    ```lang-html
    <script type="application/ld+json"> 
    { 
    	"@context": "http://data-pipeline-schema/.org", 
    	"@type": "WebPage", 
    	"headline": "Category: Analytics That Matter", 
    	"url": "https://blog.parse.ly/post/category/analytics-that-matter/" 
    } 
    </script>
    ```

## Additional JSON-LD tag examples

 * Additional properties Google recommends [for enhanced display in search listings](https://developers.google.com/search/docs/guides/intro-structured-data)
 * You can check your own implementation with the [Google Structured Data Testing Tool](https://search.google.com/structured-data/testing-tool/u/0/).

    ```lang-html
    <script type="application/ld+json"> 
    { 
    	"@context": "http://data-pipeline-schema/.org", 
    	"@type": "NewsArticle", 
    	"headline": "Zipf's Law of the Internet: Explaining Online Behavior",
    	"url": "https://blog.parse.ly/post/57821746552", 
    	"thumbnailUrl": "https://blog.parse.ly/inline_mra670hTvL1qz4rgp.png", 
    	"image": "https://blog.parse.ly/inline_mra670hTvL1qz4rgp.png", 
    	"dateCreated": "2013-08-10T01:25:08Z", 
    	"datePublished": "2013-08-10T01:25:08Z", 
    	"dateModified": "2013-08-10T01:25:08Z", 
    	"articleSection": "Programming", 
    	"creator": ["Alan Alexander Milne"], 
    	"author": ["Alan Alexander Milne"], 
    	"keywords": ["data", "intern", "parse.ly"], 
    	"mainEntityOfPage": 
    	{ 
    		"@type": "WebPage", 
    		"@id": "https://blog.parse.ly/post/57821746552" 
    	}, 
    	"publisher": 
    	{ 
    		"@type": "Organization", 
    		"name": "Parse.ly", 
    		"logo": 
    		{ 
    			"@type": "ImageObject", 
    			"url": "http://s3.amazonaws.com/parsely_static/marketing/parsely-email-logo.png" 
    		} 
    	} 
    } 
    </script>
    ```

Note that some of these properties may have overlapping values. Here is how they’re
resolved by our crawler:

 * Parse.ly preferentially uses `datePublished`, rather than `dateCreated`, if both
   are present.
 * Parse.ly uses `thumbnailUrl`, but not `image`.
 * For `author`, `creator`, and `contributor` properties, Parse.ly will combine 
   all the unique values into a single list.

We would also like to echo [Google’s advice on structured data](https://developers.google.com/search/docs/guides/intro-structured-data#structured-data-format):

> …it is more important to supply fewer but complete and accurate recommended properties
> rather than trying to provide every possible recommended property with less complete,
> badly-formed, or inaccurate data.

Last updated: November 19, 2025