*/ public static function indexing_api_types(): array { return array( 'JobPosting', 'BroadcastEvent' ); } /** * Every rich result feature, with what Google requires for it. * * `required` fails eligibility. `recommended` does not — it changes how * much of the result gets rendered, which is a different and smaller * problem, and conflating the two produces a screen full of red that * nobody can prioritise. * * @return array> */ public static function features(): array { return array( array( 'type' => 'JobPosting', 'label' => __( 'Job posting', 'ai-rank-suite' ), 'group' => __( 'Business', 'ai-rank-suite' ), 'about' => __( 'Puts the role in the Google Jobs box above the normal results — for a careers page that box is most of the traffic.', 'ai-rank-suite' ), 'indexing' => true, 'required' => array( 'title', 'description', 'datePosted', 'hiringOrganization', 'jobLocation' ), 'recommended' => array( 'baseSalary', 'employmentType', 'validThrough', 'identifier', 'applicantLocationRequirements' ), 'notes' => array( 'validThrough' => __( 'Without an expiry date Google keeps showing the role after it is filled, and repeated stale postings cost the whole site its eligibility.', 'ai-rank-suite' ), 'baseSalary' => __( 'Some jurisdictions now require a salary range by law, and Google surfaces the ones that have it more prominently.', 'ai-rank-suite' ), ), ), array( 'type' => 'LocalBusiness', 'label' => __( 'Local business', 'ai-rank-suite' ), 'group' => __( 'Business', 'ai-rank-suite' ), 'about' => __( 'The knowledge panel, the map pin and the opening hours. For anyone with an address this is the highest-value markup on the site.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'address' ), 'recommended' => array( 'telephone', 'openingHoursSpecification', 'geo', 'url', 'image', 'priceRange', 'sameAs' ), 'notes' => array( 'address' => __( 'A PostalAddress node, not a string. Google needs streetAddress, addressLocality, postalCode and addressCountry separately.', 'ai-rank-suite' ), 'geo' => __( 'Coordinates let Google place the pin without geocoding your address, which is where wrong map positions come from.', 'ai-rank-suite' ), ), ), array( 'type' => 'Product', 'label' => __( 'Product', 'ai-rank-suite' ), 'group' => __( 'Commerce', 'ai-rank-suite' ), 'about' => __( 'Price, availability and stars in the result, and eligibility for the shopping surfaces.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'offers' ), 'recommended' => array( 'image', 'description', 'sku', 'brand', 'aggregateRating', 'review', 'gtin' ), 'notes' => array( 'offers' => __( 'An Offer with price, priceCurrency and availability. A price with no currency is invalid, not merely incomplete.', 'ai-rank-suite' ), 'gtin' => __( 'Google matches your product to the same product elsewhere through the GTIN. Without it you compete as an unknown item.', 'ai-rank-suite' ), ), ), array( 'type' => 'Event', 'label' => __( 'Event', 'ai-rank-suite' ), 'group' => __( 'Business', 'ai-rank-suite' ), 'about' => __( 'Date, venue and ticket link in the result, plus the events carousel.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'startDate', 'location' ), 'recommended' => array( 'endDate', 'description', 'image', 'offers', 'performer', 'eventStatus', 'eventAttendanceMode' ), 'notes' => array( 'startDate' => __( 'ISO 8601 with a timezone offset. A date with no timezone is read as the crawler\'s timezone, which is not yours.', 'ai-rank-suite' ), 'eventAttendanceMode' => __( 'Online, offline or mixed. Google has treated this as effectively required since 2020.', 'ai-rank-suite' ), ), ), array( 'type' => 'Recipe', 'label' => __( 'Recipe', 'ai-rank-suite' ), 'group' => __( 'Content', 'ai-rank-suite' ), 'about' => __( 'The recipe carousel, cook time and the guided-cooking surfaces.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'image', 'recipeIngredient', 'recipeInstructions' ), 'recommended' => array( 'author', 'datePublished', 'description', 'prepTime', 'cookTime', 'totalTime', 'recipeYield', 'nutrition', 'aggregateRating', 'video' ), ), array( 'type' => 'Course', 'label' => __( 'Course', 'ai-rank-suite' ), 'group' => __( 'Content', 'ai-rank-suite' ), 'about' => __( 'The course list carousel. Requires a provider and a real description.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'description', 'provider' ), 'recommended' => array( 'hasCourseInstance', 'offers', 'aggregateRating', 'image' ), ), array( 'type' => 'VideoObject', 'label' => __( 'Video', 'ai-rank-suite' ), 'group' => __( 'Media', 'ai-rank-suite' ), 'about' => __( 'A thumbnail in the result and eligibility for the video tab and key moments.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'description', 'thumbnailUrl', 'uploadDate' ), 'recommended' => array( 'duration', 'contentUrl', 'embedUrl', 'hasPart', 'interactionStatistic' ), 'notes' => array( 'hasPart' => __( 'Clip markup is what produces "key moments" under the result — the single most clicked video enhancement.', 'ai-rank-suite' ), ), ), array( 'type' => 'FAQPage', 'label' => __( 'FAQ', 'ai-rank-suite' ), 'group' => __( 'Content', 'ai-rank-suite' ), 'about' => __( 'Google now shows FAQ rich results only for authoritative government and health sites — but the markup is still the most quotable format for AI assistants, which is why it stays worth writing.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'mainEntity' ), 'recommended' => array(), ), array( 'type' => 'Article', 'label' => __( 'Article', 'ai-rank-suite' ), 'group' => __( 'Content', 'ai-rank-suite' ), 'about' => __( 'Top stories eligibility and the byline and date in the result.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'headline' ), 'recommended' => array( 'image', 'datePublished', 'dateModified', 'author', 'publisher' ), 'notes' => array( 'headline' => __( 'Google truncates the headline property at 110 characters.', 'ai-rank-suite' ), 'author' => __( 'A Person or Organization node, not a bare string — this is the most common Article warning in Search Console.', 'ai-rank-suite' ), ), ), array( 'type' => 'BreadcrumbList', 'label' => __( 'Breadcrumbs', 'ai-rank-suite' ), 'group' => __( 'Navigation', 'ai-rank-suite' ), 'about' => __( 'Replaces the raw URL in the result with a readable path.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'itemListElement' ), 'recommended' => array(), ), array( 'type' => 'Organization', 'label' => __( 'Organization', 'ai-rank-suite' ), 'group' => __( 'Business', 'ai-rank-suite' ), 'about' => __( 'The knowledge panel for the brand itself, and the logo beside the site name.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'url' ), 'recommended' => array( 'logo', 'sameAs', 'contactPoint', 'description' ), 'notes' => array( 'sameAs' => __( 'The social profiles are how Google connects the site to the entity it already knows about.', 'ai-rank-suite' ), ), ), array( 'type' => 'SoftwareApplication', 'label' => __( 'Software app', 'ai-rank-suite' ), 'group' => __( 'Commerce', 'ai-rank-suite' ), 'about' => __( 'Rating, price and platform in the result for an app or a plugin.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'name', 'offers', 'aggregateRating' ), 'recommended' => array( 'operatingSystem', 'applicationCategory' ), ), array( 'type' => 'BroadcastEvent', 'label' => __( 'Livestream', 'ai-rank-suite' ), 'group' => __( 'Media', 'ai-rank-suite' ), 'about' => __( 'The "LIVE" badge on a video result. One of only two types the Google Indexing API accepts.', 'ai-rank-suite' ), 'indexing' => true, 'required' => array( 'startDate', 'isLiveBroadcast' ), 'recommended' => array( 'endDate', 'publication' ), ), array( 'type' => 'QAPage', 'label' => __( 'Q&A page', 'ai-rank-suite' ), 'group' => __( 'Content', 'ai-rank-suite' ), 'about' => __( 'For pages where users post one question and others answer it — a forum thread, not a FAQ you wrote.', 'ai-rank-suite' ), 'indexing' => false, 'required' => array( 'mainEntity' ), 'recommended' => array(), ), array( 'type' => 'HowTo', 'label' => __( 'How-to', 'ai-rank-suite' ), 'group' => __( 'Content', 'ai-rank-suite' ), 'about' => __( 'Google retired the how-to rich result in 2023. The markup still helps assistants follow the steps, so it is reported but never flagged as an opportunity.', 'ai-rank-suite' ), 'indexing' => false, 'retired' => true, 'required' => array( 'name', 'step' ), 'recommended' => array( 'totalTime', 'supply', 'tool', 'image' ), ), ); } /** * Validate one graph node against its feature definition. * * @param array $node A JSON-LD node. * @param array $feature Feature definition. * @return array{valid: bool, missing: array, weak: array} */ public static function validate_node( array $node, array $feature ): array { $missing = array(); $weak = array(); foreach ( (array) $feature['required'] as $property ) { if ( ! self::filled( $node, $property ) ) { $missing[] = $property; } } foreach ( (array) $feature['recommended'] as $property ) { if ( ! self::filled( $node, $property ) ) { $weak[] = $property; } } // Conditional rules, where a flat required-list would be wrong. if ( 'JobPosting' === $feature['type'] ) { // applicantLocationRequirements is required only for remote roles, // and jobLocation is the wrong field for them. Reporting either as // missing on the wrong kind of role sends people editing a field // that should not be there. $remote = 'TELECOMMUTE' === ( $node['jobLocationType'] ?? '' ); if ( $remote ) { $missing = array_values( array_diff( $missing, array( 'jobLocation' ) ) ); if ( ! self::filled( $node, 'applicantLocationRequirements' ) ) { $missing[] = 'applicantLocationRequirements'; } } $weak = array_values( array_diff( $weak, array( 'applicantLocationRequirements' ) ) ); } if ( 'Product' === $feature['type'] ) { // An Offer without a currency is invalid rather than incomplete, so // it belongs in the required column even though `offers` is present. $offers = $node['offers'] ?? null; $offer = is_array( $offers ) ? ( isset( $offers[0] ) && is_array( $offers[0] ) ? $offers[0] : $offers ) : array(); if ( is_array( $offer ) && array() !== $offer ) { if ( self::filled( $offer, 'price' ) && ! self::filled( $offer, 'priceCurrency' ) ) { $missing[] = 'offers.priceCurrency'; } if ( ! self::filled( $offer, 'availability' ) ) { $weak[] = 'offers.availability'; } } } if ( 'Event' === $feature['type'] ) { $start = (string) ( $node['startDate'] ?? '' ); if ( '' !== $start && ! preg_match( '/(Z|[+\-]\d{2}:?\d{2})$/', $start ) && str_contains( $start, 'T' ) ) { $weak[] = 'startDate.timezone'; } } if ( 'Article' === $feature['type'] ) { $headline = (string) ( $node['headline'] ?? '' ); if ( '' !== $headline && mb_strlen( $headline ) > 110 ) { $weak[] = 'headline.length'; } $author = $node['author'] ?? null; if ( is_string( $author ) && '' !== $author ) { // A bare string author is the most common Article warning in // Search Console, and it is invisible unless you look for it. $weak[] = 'author.type'; } } return array( 'valid' => array() === $missing, 'missing' => array_values( array_unique( $missing ) ), 'weak' => array_values( array_unique( $weak ) ), ); } /** * Is a property actually present, rather than merely set to nothing? * * @param array $node Node. * @param string $property Property. */ private static function filled( array $node, string $property ): bool { if ( ! array_key_exists( $property, $node ) ) { return false; } $value = $node[ $property ]; if ( is_string( $value ) ) { return '' !== trim( $value ); } if ( is_array( $value ) ) { return array() !== $value; } return null !== $value && false !== $value; } /** * Scan the site: for each feature, how many pages emit it and how many * would qualify. * * Bounded on purpose. A full pass over a hundred-thousand-page site would * render every page, and the answer to "are my job postings valid" does * not need all of them — it needs a sample big enough to find the broken * template, and it says how big the sample was. * * Building one page's graph costs roughly 40ms, because it renders the * page. A hundred pages is about four seconds, which is a reasonable wait * for a button somebody pressed; a thousand would be forty, which is not. * The cap is there for that reason and not an arbitrary one. * * @param int $limit Pages to inspect. * @param bool $fresh Skip the cache. * @return array */ public static function scan( int $limit = 100, bool $fresh = false ): array { if ( ! $fresh ) { $cached = get_transient( self::CACHE ); if ( is_array( $cached ) ) { return $cached; } } $features = array(); foreach ( self::features() as $feature ) { $features[ $feature['type'] ] = $feature + array( 'pages' => 0, 'valid' => 0, 'invalid' => 0, 'gaps' => array(), 'weak' => array(), 'samples' => array(), ); } $types = array_map( static fn( $t ) => $t->name, Library::types() ); $posts = get_posts( array( 'post_type' => array() !== $types ? $types : array( 'post', 'page' ), 'post_status' => 'publish', 'numberposts' => $limit, 'orderby' => 'modified', 'order' => 'DESC', 'suppress_filters' => false, ) ); $schema = class_exists( \AiRankSuite\Modules\Schema\SchemaModule::class ) ? new \AiRankSuite\Modules\Schema\SchemaModule() : null; $scanned = 0; foreach ( $posts as $post ) { if ( ! $post instanceof WP_Post || null === $schema ) { continue; } try { $graph = $schema->graph( $post ); } catch ( \Throwable $e ) { continue; } ++$scanned; foreach ( self::flatten( (array) $graph ) as $node ) { $node_types = (array) ( $node['@type'] ?? array() ); foreach ( $node_types as $node_type ) { $node_type = (string) $node_type; if ( ! isset( $features[ $node_type ] ) ) { continue; } $result = self::validate_node( $node, $features[ $node_type ] ); ++$features[ $node_type ]['pages']; if ( $result['valid'] ) { ++$features[ $node_type ]['valid']; } else { ++$features[ $node_type ]['invalid']; if ( count( $features[ $node_type ]['samples'] ) < 10 ) { $features[ $node_type ]['samples'][] = array( 'id' => $post->ID, 'title' => get_the_title( $post ), 'missing' => $result['missing'], ); } } foreach ( $result['missing'] as $property ) { $features[ $node_type ]['gaps'][ $property ] = ( $features[ $node_type ]['gaps'][ $property ] ?? 0 ) + 1; } foreach ( $result['weak'] as $property ) { $features[ $node_type ]['weak'][ $property ] = ( $features[ $node_type ]['weak'][ $property ] ?? 0 ) + 1; } } } } $out = array(); foreach ( $features as $feature ) { arsort( $feature['gaps'] ); arsort( $feature['weak'] ); $feature['gaps'] = array_map( static fn( $property, $count ) => array( 'property' => $property, 'pages' => $count ), array_keys( $feature['gaps'] ), array_values( $feature['gaps'] ) ); $feature['weak'] = array_map( static fn( $property, $count ) => array( 'property' => $property, 'pages' => $count ), array_keys( $feature['weak'] ), array_values( $feature['weak'] ) ); $out[] = $feature; } // Present types first, then opportunities, then retired ones. usort( $out, static function ( array $a, array $b ): int { $rank = static fn( array $f ): int => $f['pages'] > 0 ? 0 : ( ! empty( $f['retired'] ) ? 2 : 1 ); $ra = $rank( $a ); $rb = $rank( $b ); if ( $ra !== $rb ) { return $ra <=> $rb; } return $b['pages'] <=> $a['pages']; } ); $result = array( 'features' => $out, 'scanned' => $scanned, 'limit' => $limit, 'indexing_api' => self::indexing_api_types(), 'at' => time(), ); set_transient( self::CACHE, $result, 15 * MINUTE_IN_SECONDS ); return $result; } /** * Flatten a JSON-LD graph, including nested @graph and mainEntity nodes. * * @param array $graph Graph. * @return array> */ private static function flatten( array $graph ): array { $out = array(); $walk = static function ( $value ) use ( &$walk, &$out ): void { if ( ! is_array( $value ) ) { return; } if ( isset( $value['@type'] ) ) { $out[] = $value; } foreach ( $value as $child ) { if ( is_array( $child ) ) { $walk( $child ); } } }; $walk( $graph ); return $out; } public static function flush(): void { delete_transient( self::CACHE ); } }