App Page Schema

The page for one app: a MobileApplication with its price, operating systems, rating and reviews, published by the Organization from the homepage.

When To Use It

Use on the page that presents one app: what it does, what it runs on, what it costs and how people rate it. That is what makes the page eligible for the software app result, with the rating and price in the listing.

Google needs a name, a price and a rating or a review. A free app states a price of 0. Without all three the builder outputs nothing, since a half-described app earns no result.

How The Pieces Connect

Every node has a stable @id. A node is written out once, where it belongs, and everywhere else it is referenced by that @id alone. This is the map for this page, generated from the output below.

Nodes and the @id links between them
@idDefined onTypeReferenced by
/app/#webpageThis pageWebPageTop-level node
/app/#breadcrumbThis pageBreadcrumbListWebPage.breadcrumb
/app/#appThis pageMobileApplicationWebPage.mainEntity
/#organizationHomepageOnlineStoreMobileApplication.publisher
/#websiteHomepageWebSiteWebPage.isPartOf

The Builder

One function turns the page's data into the whole graph. It drops anything Google would reject instead of shipping it half built. The input below includes rows it is meant to drop, so you can see the logic work.

// App page schema: the page for one app. A MobileApplication, WebApplication
// or SoftwareApplication with its price, rating and reviews, published by
// the Organization from the homepage, plus the page's WebPage and
// BreadcrumbList.
//
// Google needs a name, a price (0 for a free app) and a rating or a review.
// Without all three there is no rich result, so the builder outputs nothing.

const CURRENCY = /^[A-Z]{3}$/;
const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;

const clean = (v) => (typeof v === 'string' ? v.trim() : v);
const isUrl = (v) => typeof v === 'string' && /^https:\/\/[^\s]+$/.test(v);
const compact = (obj) => {
  if (Array.isArray(obj)) {
    const out = obj.map(compact).filter((v) => v !== undefined);
    return out.length ? out : undefined;
  }
  if (obj && typeof obj === 'object') {
    const out = {};
    for (const [k, v] of Object.entries(obj)) {
      const c = compact(v);
      if (c !== undefined) out[k] = c;
    }
    return Object.keys(out).length ? out : undefined;
  }
  return obj === null || obj === '' ? undefined : obj;
};

function breadcrumb(trail, id) {
  const items = (trail || []).filter((c) => c.name && isUrl(c.url));
  if (items.length < 2) return undefined;
  return {
    '@type': 'BreadcrumbList',
    '@id': id,
    itemListElement: items.map((c, i) => ({ '@type': 'ListItem', position: i + 1, name: clean(c.name), item: c.url })),
  };
}

const num = (v) => (typeof v === 'number' && Number.isFinite(v) ? v : null);

// A rating only counts with a score inside its scale and a count above zero.
function aggregateRating(r) {
  if (!r) return undefined;
  const best = num(r.best) ?? 5;
  const worst = num(r.worst) ?? 1;
  const value = num(r.value);
  if (value === null || worst >= best || value < worst || value > best) return undefined;
  if (!(num(r.count) > 0)) return undefined;
  return { '@type': 'AggregateRating', ratingValue: value, bestRating: best, worstRating: worst, ratingCount: r.count };
}

// A review needs a named author and a score inside its scale.
function review(r) {
  const author = clean(r.author);
  const best = num(r.best) ?? 5;
  const worst = num(r.worst) ?? 1;
  const value = num(r.rating);
  if (!author || author.length >= 100) return undefined;
  if (value === null || worst >= best || value < worst || value > best) return undefined;
  return compact({
    '@type': 'Review',
    author: { '@type': 'Person', name: author },
    reviewRating: { '@type': 'Rating', ratingValue: value, bestRating: best, worstRating: worst },
    datePublished: ISO_DATE.test(r.date || '') ? r.date : undefined,
    reviewBody: clean(r.text),
  });
}

const APP_TYPES = { mobile: 'MobileApplication', web: 'WebApplication' };
const APP_CATEGORIES = [
  'GameApplication', 'SocialNetworkingApplication', 'TravelApplication', 'ShoppingApplication',
  'SportsApplication', 'LifestyleApplication', 'BusinessApplication', 'DesignApplication',
  'DeveloperApplication', 'DriverApplication', 'EducationalApplication', 'HealthApplication',
  'FinanceApplication', 'SecurityApplication', 'BrowserApplication', 'CommunicationApplication',
  'DesktopEnhancementApplication', 'EntertainmentApplication', 'MultimediaApplication',
  'HomeApplication', 'UtilitiesApplication', 'ReferenceApplication',
];

function buildAppPageSchema(source) {
  const site = source.site || {};
  const page = source.page || {};
  const app = source.app || {};
  if (!isUrl(site.url) || !isUrl(page.url) || !app.name) return null;

  // A free app states a price of 0. A paid one needs its currency.
  const price = num(app.price);
  if (price === null || price < 0) return null;
  const currency = CURRENCY.test(app.currency || '') ? app.currency : undefined;
  if (price > 0 && !currency) return null;

  const rating = aggregateRating(app.rating);
  const reviews = (app.reviews || []).map(review).filter(Boolean);
  if (!rating && !reviews.length) return null;

  const root = site.url.replace(/\/+$/, '');
  const pageUrl = page.url;
  const appId = `${pageUrl}#app`;

  // A game is typed as a VideoGame and an app: VideoGame alone is not eligible.
  const base = APP_TYPES[app.platform] || 'SoftwareApplication';

  const software = compact({
    '@type': app.isGame ? ['VideoGame', base] : base,
    '@id': appId,
    name: clean(app.name),
    description: clean(app.description),
    url: pageUrl,
    image: (app.images || []).filter(isUrl),
    operatingSystem: clean(app.operatingSystem),
    applicationCategory: APP_CATEGORIES.includes(app.category) ? app.category : undefined,
    softwareVersion: clean(app.version),
    downloadUrl: (app.storeLinks || []).filter(isUrl),
    offers: { '@type': 'Offer', price, priceCurrency: currency },
    aggregateRating: rating,
    review: reviews,
    publisher: { '@id': `${root}/#organization` },
  });

  const crumbs = breadcrumb(page.breadcrumbs, `${pageUrl}#breadcrumb`);
  const webpage = compact({
    '@type': 'WebPage',
    '@id': `${pageUrl}#webpage`,
    url: pageUrl,
    name: clean(page.title) || clean(app.name),
    isPartOf: { '@id': `${root}/#website` },
    breadcrumb: crumbs ? { '@id': crumbs['@id'] } : undefined,
    mainEntity: { '@id': appId },
  });

  return { '@context': 'https://schema.org', '@graph': [webpage, crumbs, software].filter(Boolean) };
}

The Logic As A Flowchart

The same logic as the builder above, drawn for readers who do not write code. Every Yes moves down. A No that runs out to the line on the right stops everything, and no schema is output. Where the path splits, exactly one branch is taken. Each step was run against the builder itself before this page was published: 30 test cases, all passing.

  1. A page for one app
  2. 1Site has an https URL?the home page addressNo: no schema
    Yes
  3. 2Page has an https URL?the address of this pageNo: no schema
    Yes
  4. 3App has a name?the name of the appNo: no schema
    Yes
  5. 4Has a price?a number, 0 for a free appNo: no schema
    Yes
  6. 5A paid app has a currency?a 3-letter code such as USDNo: no schema
    Yes
  7. 6Has a rating or a review?a score with a count, or a review with a named authorNo: no schema
    Yes
  8. Two or more breadcrumbs with a name and an https link?the trail shown on the page
    Yes
    A BreadcrumbList is added and linked from the page
    No
    No BreadcrumbList
  9. Build the linked nodesWebPage and the app, with its publisher pointing at the homepage Organization by @id. Anything optional that is missing or invalid is left out
  10. Output WebPage and the app
    No schema

Validation

The output above was run through the SchemaCDN validator, which checks every rule in Google's documentation for each feature. It was validated together with the homepage graph, so the @id links resolve. Result: no errors, and eligible for:

Breadcrumb Software app

Left Out On Purpose

  • A currency on a free app when none is given. The builder does not make one up.
  • File size, permissions and release notes. Google does not use them, and they change with every release.
  • A separate node per app store. The store links sit on the one app as downloadUrl.

Implementation Checklist

  • State the price the page shows, as a number. A free app is 0, not blank.
  • Use ratings from real users of this app, and show the same score and count on the page.
  • Give every review a named author. A review without one is dropped.
  • Name the operating systems with their lowest supported versions.
  • Update the rating and the version when a release ships.

Other Page Types