Article Schema - JSON-LD Guide & Examples · Unhead [Unhead Home](https://unhead.unjs.io/ "Home") - [Docs](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview) - [Tools](https://unhead.unjs.io/tools) - [Learn](https://unhead.unjs.io/learn/guides/what-is-capo) [Releases](https://unhead.unjs.io/releases) Search…```k`` /` [Unhead on GitHub](https://github.com/unjs/unhead) [User Guides](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview) [API](https://unhead.unjs.io/docs/typescript/head/api/get-started/overview) [Releases](https://unhead.unjs.io/docs/typescript/releases/v3) TypeScript - [Switch to TypeScript](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/article) - [Switch to Vue](https://unhead.unjs.io/docs/vue/schema-org/api/schema/article) - [Switch to React](https://unhead.unjs.io/docs/react/schema-org/api/schema/article) - [Switch to Svelte](https://unhead.unjs.io/docs/svelte/schema-org/api/schema/article) - [Switch to Solid.js](https://unhead.unjs.io/docs/solid-js/schema-org/api/schema/article) - [Switch to Angular](https://unhead.unjs.io/docs/angular/schema-org/api/schema/article) - [Switch to Nuxt](https://unhead.unjs.io/docs/nuxt/schema-org/api/schema/article) v3 (stable) Schema.org - [Discord Support](https://discord.com/invite/275MBUBvgP) - [TypeScript Playground](https://stackblitz.com/edit/github-hhxywsb5) - Composables - [`useSchemaOrg()`](https://unhead.unjs.io/docs/typescript/schema-org/api/composables/use-schema-org) - Nodes - [Article](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/article) - [Book Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/book) - [Breadcrumb Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/breadcrumb) - [Comment Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/comment) - [Course Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/course) - [Dataset Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/dataset) - [Event Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/event) - [Food Establishment Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/food-establishment) - [HowTo](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/how-to) - [Image Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/image) - [ItemList](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/item-list) - [JobPosting](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/job-posting) - [LocalBusiness](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/local-business) - [Movie Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/movie) - [Music Album Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/music-album) - [Music Group Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/music-group) - [Music Playlist Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/music-playlist) - [Music Recording Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/music-recording) - [Organization](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/organization) - [Person Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/person) - [Podcast Episode Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/podcast-episode) - [Podcast Season Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/podcast-season) - [Podcast Series Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/podcast-series) - [Product Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/product) - [Question Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/question) - [Recipe Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/recipe) - [Service Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/service) - [SoftwareApplication](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/software-app) - [TV Episode Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/tv-episode) - [TV Season Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/tv-season) - [TV Series Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/tv-series) - [Video Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/video) - [WebPage Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/webpage) - [WebSite Schema](https://unhead.unjs.io/docs/typescript/schema-org/api/schema/website) Schema # Article Schema - JSON-LD Guide & Examples [Copy for LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/schema-org/5.api/9.schema/article.md) Last updated Mar 5, 2026 by [Harlan Wilton](https://github.com/harlan-zw) in [docs: improve SEO for schema.org pages, overview, and React Helmet migration (#675)](https://github.com/unjs/unhead/pull/675). On this page - [JSON-LD Example](#json-ld-example) - [Schema.org Article](#schemaorg-article) - [Useful Links](#useful-links) - [Required properties](#required-properties) - [Recommended Properties](#recommended-properties) - [Defaults](#defaults) - [Sub-Types](#sub-types) - [Relation Transforms](#relation-transforms) - [Resolves](#resolves) - [Examples](#examples) - [Types](#types) - [Related Schemas](#related-schemas) Article schema identifies written content like blog posts, news articles, and technical documentation. It helps search engines understand authorship, publish dates, and content type for rich results in Google Search. ### [JSON-LD Example](#json-ld-example) ``` { "@context": "https://schema.org", "@type": "Article", "headline": "How to Build a REST API with Node.js", "image": "https://example.com/photos/api-guide.jpg", "datePublished": "2026-01-15T08:00:00+00:00", "dateModified": "2026-02-20T10:30:00+00:00", "author": { "@type": "Person", "name": "Jane Smith", "url": "https://example.com/authors/jane" }, "publisher": { "@type": "Organization", "name": "Dev Blog", "logo": { "@type": "ImageObject", "url": "https://example.com/logo.png" } } } ``` With Unhead, generate this using the `defineArticle()` composable — see the [API reference](#schema-org-article) below. Use the [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator) to build your structured data visually. ## [Schema.org Article](#schemaorg-article) - **Type**: `defineArticle(input?: Article)`Describes an `Article` on a `WebPage`. ## [Useful Links](#useful-links) - [Article - Schema.org](https://schema.org/Article) - [Article Schema Markup - Google Search Central](https://developers.google.com/search/docs/advanced/structured-data/article) - [Article - Yoast](https://developer.yoast.com/features/schema/pieces/article) - [Recipe: Blog](https://unhead.unjs.io/docs/schema-org/guides/recipes/blog) ## [Required properties](#required-properties) - **headline** `string`Name of the articleA name can be provided using route meta on the `title` key, see [defaults](#defaults). - **image** `Arrayable`Link a primary image or a collection of images to used to the article.A single image URL can be provided using route meta on the `image` key, see [defaults](#defaults). - **author** `AuthorInput` (conditional)If the author of the article is not your identity (see [Choosing an identity](https://unhead.unjs.io/docs/schema-org/guides/recipes/identity)) you will need to provide authors manually.The registered author is moved to a root Schema node, resolving the field as reference to a [Person](https://unhead.unjs.io/docs/schema-org/api/schema/person). ## [Recommended Properties](#recommended-properties) - **@type** [sub-types](#sub-types)Select the most appropriate type for your content for the article. ## [Defaults](#defaults) - **@type**: `Article` - **@id**: `${canonicalUrl}#article` - **headline**: `currentRouteMeta.title` _(see: [Schema.org Params](https://unhead.unjs.io/docs/schema-org/guides/core-concepts/params))_ - **image**: `currentRouteMeta.image` _(see: [Schema.org Params](https://unhead.unjs.io/docs/schema-org/guides/core-concepts/params))_ - **description**: `currentRouteMeta.description` _(see: [Schema.org Params](https://unhead.unjs.io/docs/schema-org/guides/core-concepts/params))_ - **inLanguage**: `options.defaultLanguage` _(see: [Schema.org Params](https://unhead.unjs.io/docs/schema-org/guides/core-concepts/params))_ - **datePublished**: `currentRouteMeta.datePublished` _(see: [Schema.org Params](https://unhead.unjs.io/docs/schema-org/guides/core-concepts/params))_ - **dateModified**: `currentRouteMeta.dateModified` _(see: [Schema.org Params](https://unhead.unjs.io/docs/schema-org/guides/core-concepts/params))_ - **publisher**: Identity Reference - **author**: Identity Reference - **isPartOf**: WebPage Reference - **mainEntityOfPage**: WebPage Reference ## [Sub-Types](#sub-types) - `AdvertiserContentArticle` - `NewsArticle` - `BlogPosting` - `Report` - `SatiricalArticle` - `ScholarlyArticle` - `SocialMediaPosting` - `TechArticle` ## [Relation Transforms](#relation-transforms) [WebPage](https://unhead.unjs.io/docs/schema-org/api/schema/webpage) - sets default `potentialAction` to `ReadAction` - sets default `dateModified` to articles `dateModified` - sets default `datePublished` to articles `datePublished` - sets default `primaryImageOfPage` to articles first image ## [Resolves](#resolves) See [Global Resolves](https://unhead.unjs.io/docs/schema-org/guides/get-started/overview#site-page-level-config) for full context. - `headline` will be cut to a maximum length of 110 without breaking words. - `thumbnailUrl` will be set to the first image - `dateModified` or `datePublished` can be resolved from Date objects ``` defineArticle({ // will resolve to ISO 8601 format datePublished: new Date(2024, 0o5, 29) }) ``` - providing a single string of `@type` which isn't `Article` will convert it to an array `TechArticle` -> `['Article', 'TechArticle']` ``` defineArticle({ // will be resolved as ['Article', 'TechArticle'] '@type': 'TechArticle', }) ``` ## [Examples](#examples) See the [blog](https://unhead.unjs.io/docs/schema-org/guides/recipes/blog) recipe for more examples. ### [Minimal](#minimal) ``` defineArticle({ headline: 'Article Title', image: '/articles/article-title-image.jpg', // using identity as the author }) ``` ### [Route Meta](#route-meta) Add type support for using the routes meta. ``` defineArticle() ``` ### [Complete](#complete) ``` defineArticle({ headline: 'Article Title', description: 'Article description', image: '/articles/article-title-image.jpg', datePublished: new Date(2024, 0o5, 29), dateModified: new Date(2024, 0o5, 29), // attaching an author when the identity is an organization author: { name: 'Harlan Wilton', url: 'https://harlanzw.com', } }) ``` ## [Types](#types) ``` type ValidArticleSubTypes = 'Article' | 'BlogPosting' | 'AdvertiserContentArticle' | 'NewsArticle' | 'Report' | 'SatiricalArticle' | 'ScholarlyArticle' | 'SocialMediaPosting' | 'TechArticle' export interface ArticleSimple extends Thing { ['@type']?: Arrayable /** * The headline of the article (falling back to the title of the WebPage). * Headlines should not exceed 110 characters. */ headline?: string /** * A summary of the article (falling back to the page's meta description content). */ description?: string /** * A reference-by-ID to the WebPage node. */ isPartOf?: IdReference /** * The time at which the article was originally published, in ISO 8601 format; e.g., 2015-10-31T16:10:29+00:00. */ datePublished?: ResolvableDate /** * The time at which the article was last modified, in ISO 8601 format; e.g., 2015-10-31T16:10:29+00:00. */ dateModified?: ResolvableDate /** * A reference-by-ID to the author of the article. */ author?: NodeRelations /** * A reference-by-ID to the publisher of the article. */ publisher?: NodeRelations /** * An array of all videos in the article content, referenced by ID. */ video?: NodeRelations /** * An image object or referenced by ID. * - Must be at least 696 pixels wide. * - Must be of the following formats+file extensions: .jpg, .png, .gif ,or .webp. * * Must have markup of it somewhere on the page. */ image?: NodeRelations /** * An array of references by ID to comment pieces. */ comment?: NodeRelations /** * A thumbnail image relevant to the Article. */ thumbnailUrl?: string /** * An integer value of the number of comments associated with the article. */ commentCount?: number /** * An integer value of the number of words in the article. */ wordCount?: number /** * An array of keywords which the article has (e.g., ["cats","dogs","cake"]). */ keywords?: string[] /** * An array of category names which the article belongs to (e.g., ["cats","dogs","cake"]). */ articleSection?: string[] /** * The language code for the article; e.g., en-GB. */ inLanguage?: string /** * A SpeakableSpecification object which identifies any content elements suitable for spoken results. */ speakable?: unknown /** * The year from which the article holds copyright status. */ copyrightYear?: string /** * A reference-by-ID to the Organization or Person who holds the copyright. */ copyrightHolder?: NodeRelations /** * The body text of the article. */ articleBody?: string /** * The subject matter of the article. */ about?: string } ``` ## [Related Schemas](#related-schemas) - [Person](https://unhead.unjs.io/docs/schema-org/api/schema/person) - Article author - [Organization](https://unhead.unjs.io/docs/schema-org/api/schema/organization) - Publisher - [Breadcrumb](https://unhead.unjs.io/docs/schema-org/api/schema/breadcrumb) - Article navigation [Edit this page](https://github.com/unjs/unhead/edit/main/docs/schema-org/5.api/9.schema/article.md) [Markdown For LLMs](https://raw.githubusercontent.com/unjs/unhead/refs/heads/main/docs/schema-org/5.api/9.schema/article.md) Did this page help you? [useSchemaOrg() Add Schema.org structured data with useSchemaOrg(). Pass defineArticle(), defineProduct(), and other schema nodes for Google Rich Results.](https://unhead.unjs.io/docs/schema-org/api/composables/use-schema-org) [Book Schema Use defineBook() to add Book structured data. Enable rich results with book editions, ISBN, author, and purchase actions in Google search.](https://unhead.unjs.io/docs/schema-org/api/schema/book) On this page - [JSON-LD Example](#json-ld-example) - [Schema.org Article](#schemaorg-article) - [Useful Links](#useful-links) - [Required properties](#required-properties) - [Recommended Properties](#recommended-properties) - [Defaults](#defaults) - [Sub-Types](#sub-types) - [Relation Transforms](#relation-transforms) - [Resolves](#resolves) - [Examples](#examples) - [Types](#types) - [Related Schemas](#related-schemas) [GitHub](https://github.com/unjs/unhead) [ Discord](https://discord.com/invite/275MBUBvgP) [ /llms.txt](https://unhead.unjs.io/llms.txt) [Part of the UnJS ecosystem](https://unjs.io/) ### Head Management - [Getting Started](https://unhead.unjs.io/docs/typescript/head/guides/get-started/overview) - [useHead](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head) - [useSeoMeta](https://unhead.unjs.io/docs/typescript/head/api/composables/use-seo-meta) - [useHeadSafe](https://unhead.unjs.io/docs/typescript/head/api/composables/use-head-safe) - [useScript](https://unhead.unjs.io/docs/typescript/head/api/composables/use-script) ### Schema.org - [Getting Started](https://unhead.unjs.io/docs/typescript/schema-org/guides/get-started/overview) - [useSchemaOrg](https://unhead.unjs.io/docs/typescript/schema-org/api/composables/use-schema-org) - [Nodes](https://unhead.unjs.io/docs/typescript/schema-org/guides/core-concepts/nodes) - [Recipes](https://unhead.unjs.io/docs/typescript/schema-org/guides/recipes/identity) ### Guides - [Titles](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/titles) - [Streaming SSR](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/streaming) - [DOM Events](https://unhead.unjs.io/docs/typescript/head/guides/core-concepts/dom-event-handling) - [Plugins](https://unhead.unjs.io/docs/typescript/head/guides/plugins/template-params) ### Tools - [Meta Tag Generator](https://unhead.unjs.io/tools/meta-tag-generator) - [OG Image Generator](https://unhead.unjs.io/tools/og-image-generator) - [Schema.org Generator](https://unhead.unjs.io/tools/schema-generator) - [Capo.js Analyzer](https://unhead.unjs.io/tools/capo-analyzer) ### Articles - [What is Capo.js?](https://unhead.unjs.io/learn/guides/what-is-capo) ### Research - [State of in 2026](https://unhead.unjs.io/learn/research/state-of-head-2026) - [Streaming Head Performance](https://unhead.unjs.io/learn/research/streaming-head-performance) - [Capo.js Performance Research](https://unhead.unjs.io/learn/research/capo-performance-research) Copyright © 2025-2026 Harlan Wilton - [MIT License](https://github.com/unjs/unhead/blob/main/license)