From a1629725d0ec4a248804160b9adbd15443ac60c8 Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:36:28 +0100 Subject: [PATCH 01/11] Record the 0.2.0 release in the changelog --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 03041652..9a6eb5e7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,8 @@ ## [Unreleased] +## [0.2.0] - 2026-11-12 + ### Changed - Schema.org vocabulary upgraded from 30.0 to 30.1. This release promotes most of the From 16635243d221f22ddb07ad10eec48fcb8a5d7504 Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:36:35 +0100 Subject: [PATCH 02/11] Keep the empty node object left by pruning a blank node identifier when framing --- CHANGELOG.md | 6 ++++++ src/JsonLd/Algorithms/Frame/FrameOutputCleaner.php | 7 +++++++ 2 files changed, 13 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9a6eb5e7..282a2518 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## [Unreleased] +### Fixed + +- Framing in JSON-LD 1.1 mode dropped a property whose only value was a node reduced + to a pruned blank node identifier (W3C test `frame#tp046`): the empty node object is + now kept, as `{}`. + ## [0.2.0] - 2026-11-12 ### Changed diff --git a/src/JsonLd/Algorithms/Frame/FrameOutputCleaner.php b/src/JsonLd/Algorithms/Frame/FrameOutputCleaner.php index d8420f3c..74fc1287 100644 --- a/src/JsonLd/Algorithms/Frame/FrameOutputCleaner.php +++ b/src/JsonLd/Algorithms/Frame/FrameOutputCleaner.php @@ -54,6 +54,13 @@ public static function cleanupPreserve(mixed $input, array $bnodesToClear): mixe $input[$key] = self::cleanupPreserve($value, $bnodesToClear); } + + // A node object reduced to its blank node identifier is still a node + // object once that identifier is pruned: an empty PHP array would be + // encoded as an empty list, which compaction drops. + if ([] === $input) { + return new \stdClass(); + } } return $input; From 8417155ab0364f6a6ad13b5518d334f1dcef9533 Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:48:00 +0100 Subject: [PATCH 03/11] Run the W3C manifest entries that reuse the input of another entry --- CHANGELOG.md | 3 + README.md | 11 +++ tests/Algorithms/AbstractJsonLdTestCase.php | 82 ++++++++++++++++----- tests/Algorithms/CompactorTest.php | 28 ++++--- tests/Algorithms/ContextProcessorTest.php | 4 +- tests/Algorithms/ExpanderTest.php | 10 +-- tests/Algorithms/FlattenerTest.php | 10 +-- tests/Algorithms/FramerTest.php | 28 +++++-- 8 files changed, 128 insertions(+), 48 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 282a2518..59ae585e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ - Framing in JSON-LD 1.1 mode dropped a property whose only value was a node reduced to a pruned blank node identifier (W3C test `frame#tp046`): the empty node object is now kept, as `{}`. +- The W3C manifest entries that reuse the input of another entry with a different + expected output (`compact#ta038`, `frame#tp020`, `#tp021`, `#tp046` and `#tp049`) + are now run. Every test that applies to a JSON-LD 1.1 processor passes. ## [0.2.0] - 2026-11-12 diff --git a/README.md b/README.md index 1b6df65c..c8b711b8 100644 --- a/README.md +++ b/README.md @@ -193,6 +193,17 @@ Each algorithm is validated against the official W3C test suites ([json-ld-api]( The full suites pass, covering expansion, compaction, flattening and framing. The only skipped fixtures are a handful that target JSON-LD 1.0-specific behavior (declared `specVersion: json-ld-1.0` in the upstream manifest), which this library does not implement; each skip is documented in the corresponding test. Serialization to and from RDF (`toRdf` / `fromRdf`) is out of scope and not implemented. +As of the pinned upstream commits, the manifests list 781 tests, and every test that applies to a JSON-LD 1.1 processor passes: + +| Suite | Passed | JSON-LD 1.0 only | +| --- | --- | --- | +| expand | 385 | 0 | +| compact | 244 | 2 | +| flatten | 58 | 0 | +| frame | 91 | 1 | + +`castor qa:earl` runs these suites and writes an [EARL](https://www.w3.org/TR/EARL10-Schema/) report in Turtle, one assertion per manifest entry, in the format the [W3C JSON-LD implementation report](https://w3c.github.io/json-ld-api/reports/) consolidates. + To use them, create an instance of `JoliCode\StructuredData\JsonLd\Algorithms\Expand\Expander`, `JoliCode\StructuredData\JsonLd\Algorithms\Flatten\Flattener`, `JoliCode\StructuredData\JsonLd\Algorithms\Compact\Compactor` or `JoliCode\StructuredData\JsonLd\Algorithms\Frame\Framer`, and pass it the JSON-LD document you want to convert. For instance, expanding a JSON-LD document looks like this: diff --git a/tests/Algorithms/AbstractJsonLdTestCase.php b/tests/Algorithms/AbstractJsonLdTestCase.php index 8431c2bf..c73c195c 100644 --- a/tests/Algorithms/AbstractJsonLdTestCase.php +++ b/tests/Algorithms/AbstractJsonLdTestCase.php @@ -24,37 +24,75 @@ abstract class AbstractJsonLdTestCase extends TestCase public const DATA_PATH = __DIR__ . '/../../var/cache/w3c-json-ld-api/tests'; /** - * @return iterable + * One data set per W3C manifest entry. A data set is named after the expected + * output file of the entry, with "-out" replaced by "-in" (which is the input + * file name, except for the variants of getVariantOutputFiles()), or after the + * input file for the negative tests. The EARL report relies on this naming to + * map the outcomes back to the manifest. + * + * @return iterable */ public static function provideInputsAndOutputs(): iterable { foreach (static::getInputFiles() as $inputFile) { $filename = $inputFile->getFilename(); + $json = $inputFile->getContents(); - if (static::shouldSkipThisTest($filename)) { - continue; - } + if (!static::shouldSkipThisTest($filename)) { + $outputFileName = static::getOutputFileName( + str_replace('-in', '-out', $filename), + ); - $outputFileName = static::getOutputFileName( - str_replace('-in', '-out', $filename), - ); + if (is_file($outputFileName)) { + $expected = static::readExpectedOutput($outputFileName); + } else { + $expected = new JsonLdException(static::getExpectedErrorMessage($filename)); + } - if (is_file($outputFileName)) { - $expected = file_get_contents($outputFileName); + yield $filename => [ + 'json' => $json, + 'expected' => $expected, + 'filename' => $filename, + 'test' => $filename, + ]; + } - if (false === $expected) { - throw new \RuntimeException(\sprintf('The expected output "%s" could not be read.', $outputFileName)); - } - } else { - $expected = new JsonLdException(static::getExpectedErrorMessage($filename)); + foreach (static::getVariantOutputFiles($filename) as $variantOutputFile) { + $test = str_replace('-out', '-in', $variantOutputFile); + + yield $test => [ + 'json' => $json, + 'expected' => static::readExpectedOutput(static::getOutputFileName($variantOutputFile)), + 'filename' => $filename, + 'test' => $test, + ]; } + } + } + + /** + * Some manifest entries run an input file that another entry already uses, + * with other options (typically in JSON-LD 1.1 processing mode where the first + * entry runs in 1.0 mode), against a different expected output. The fixture + * layout keys the tests by input file, so these variants are declared here: the + * expected output files of the variants of the given input file. + * + * @return list + */ + protected static function getVariantOutputFiles(string $filename): array + { + return []; + } - yield $filename => [ - 'json' => $inputFile->getContents(), - 'expected' => $expected, - 'filename' => $filename, - ]; + protected static function readExpectedOutput(string $outputFileName): string + { + $expected = @file_get_contents($outputFileName); + + if (false === $expected) { + throw new \RuntimeException(\sprintf('The expected output "%s" could not be read.', $outputFileName)); } + + return $expected; } /** @@ -99,8 +137,12 @@ abstract protected static function getExpectedErrorMessage(string $filename): st /** * Some tests require some special options to work. * This method must return the corresponding options for this test, available at https://w3c.github.io/json-ld-api/tests. + * + * The options are keyed by the data set name ($test), which differs from the + * input file name ($filename) for the variants of getVariantOutputFiles(); the + * base IRI is always the one of the input file. */ - abstract protected static function getOptions(string $filename): ProcessorOptions; + abstract protected static function getOptions(string $filename, string $test): ProcessorOptions; protected static function getInputFiles(): Finder { diff --git a/tests/Algorithms/CompactorTest.php b/tests/Algorithms/CompactorTest.php index 3e567335..0a64063b 100644 --- a/tests/Algorithms/CompactorTest.php +++ b/tests/Algorithms/CompactorTest.php @@ -27,10 +27,10 @@ class CompactorTest extends AbstractJsonLdTestCase { #[DataProvider('provideInputsAndOutputs')] - public function testCompact(string $json, string|JsonLdException $expected, string $filename): void + public function testCompact(string $json, string|JsonLdException $expected, string $filename, string $test): void { $compactor = new Compactor(documentLoader: static::createDocumentLoader()); - $options = static::getOptions($filename); + $options = static::getOptions($filename, $test); $context = self::getContextFor($filename); if ($expected instanceof JsonLdException) { @@ -92,7 +92,8 @@ protected static function shouldSkipThisTest(string $filename): bool // These tests are declared with "specVersion": "json-ld-1.0" in the W3C // manifest: they only apply to JSON-LD 1.0 processors. In particular, // e001 expects a "compaction to list of lists" error which is valid - // JSON-LD in 1.1 processing mode. + // JSON-LD in 1.1 processing mode. The 1.1 counterpart of 0038 (#ta038) + // runs as a variant, see getVariantOutputFiles(). '0038-in.jsonld', 'e001-in.jsonld', ]; @@ -100,7 +101,16 @@ protected static function shouldSkipThisTest(string $filename): bool return \in_array($filename, $testsToSkip, true); } - protected static function getOptions(string $filename): ProcessorOptions + protected static function getVariantOutputFiles(string $filename): array + { + return match ($filename) { + // #ta038: the JSON-LD 1.1 version of #t0038, same input and context + '0038-in.jsonld' => ['0038a-out.jsonld'], + default => [], + }; + } + + protected static function getOptions(string $filename, string $test): ProcessorOptions { $options = new ProcessorOptions(base: static::getBaseUrlForW3CTests($filename)); @@ -110,23 +120,23 @@ protected static function getOptions(string $filename): ProcessorOptions 'ep14-in.jsonld', 'ep15-in.jsonld', 'p001-in.jsonld', ]; - if (\in_array($filename, $processingMode10Tests, true)) { + if (\in_array($test, $processingMode10Tests, true)) { $options->processingMode = Context::PROCESSING_MODE_10; } - if (\in_array($filename, ['0070-in.jsonld', '0091-in.jsonld', '0093-in.jsonld'], true)) { + if (\in_array($test, ['0070-in.jsonld', '0091-in.jsonld', '0093-in.jsonld'], true)) { $options->compactArrays = false; } - if (\in_array($filename, ['0075-in.jsonld', 'r001-in.jsonld'], true)) { + if (\in_array($test, ['0075-in.jsonld', 'r001-in.jsonld'], true)) { $options->base = 'http://example.org/'; } - if ('0114-in.jsonld' === $filename) { + if ('0114-in.jsonld' === $test) { $options->base = 'https://example.org/'; } - if ('r002-in.jsonld' === $filename) { + if ('r002-in.jsonld' === $test) { $options->compactToRelative = false; } diff --git a/tests/Algorithms/ContextProcessorTest.php b/tests/Algorithms/ContextProcessorTest.php index 8c41203c..ddf78f11 100644 --- a/tests/Algorithms/ContextProcessorTest.php +++ b/tests/Algorithms/ContextProcessorTest.php @@ -31,7 +31,7 @@ class ContextProcessorTest extends AbstractJsonLdTestCase * The algorithm doesn't have its own proper tests : its validity is tested in the other algorithms tests. * */ #[DataProvider('provideInputsAndOutputs')] - public function testProcessContext(string $json, string $expected, string $filename): void + public function testProcessContext(string $json, string $expected, string $filename, string $test): void { $processer = new ContextProcessor(new ContextCache(static::createDocumentLoader())); $actual = new \stdClass(); @@ -188,7 +188,7 @@ protected static function shouldSkipThisTest(string $filename): bool return \in_array($filename, $testsToSkip, true); } - protected static function getOptions(string $filename): ProcessorOptions + protected static function getOptions(string $filename, string $test): ProcessorOptions { // contexts don't use options return new ProcessorOptions(); diff --git a/tests/Algorithms/ExpanderTest.php b/tests/Algorithms/ExpanderTest.php index 3ed3b1fb..7b62b402 100644 --- a/tests/Algorithms/ExpanderTest.php +++ b/tests/Algorithms/ExpanderTest.php @@ -27,10 +27,10 @@ class ExpanderTest extends AbstractJsonLdTestCase { #[DataProvider('provideInputsAndOutputs')] - public function testExpand(string $json, string|JsonLdException $expected, string $filename): void + public function testExpand(string $json, string|JsonLdException $expected, string $filename, string $test): void { $expander = new Expander(documentLoader: static::createDocumentLoader()); - $options = static::getOptions($filename); + $options = static::getOptions($filename, $test); if ($expected instanceof JsonLdException) { try { @@ -191,7 +191,7 @@ protected static function shouldSkipThisTest(string $filename): bool return false; } - protected static function getOptions(string $filename): ProcessorOptions + protected static function getOptions(string $filename, string $test): ProcessorOptions { $options = new ProcessorOptions(base: static::getBaseUrlForW3CTests($filename)); @@ -219,8 +219,8 @@ protected static function getOptions(string $filename): ProcessorOptions 'tn01-in.jsonld' => ['processingMode' => Context::PROCESSING_MODE_10], ]; - if (\array_key_exists($filename, $testSpecificOptions)) { - foreach ($testSpecificOptions[$filename] as $property => $value) { + if (\array_key_exists($test, $testSpecificOptions)) { + foreach ($testSpecificOptions[$test] as $property => $value) { $options->{$property} = $value; } } diff --git a/tests/Algorithms/FlattenerTest.php b/tests/Algorithms/FlattenerTest.php index be5aa4ab..d19e2c2f 100644 --- a/tests/Algorithms/FlattenerTest.php +++ b/tests/Algorithms/FlattenerTest.php @@ -27,10 +27,10 @@ class FlattenerTest extends AbstractJsonLdTestCase { #[DataProvider('provideInputsAndOutputs')] - public function testFlatten(string $json, string|JsonLdException $expected, string $filename): void + public function testFlatten(string $json, string|JsonLdException $expected, string $filename, string $test): void { $flattener = new Flattener(documentLoader: static::createDocumentLoader()); - $options = static::getOptions($filename); + $options = static::getOptions($filename, $test); $context = self::getContextFor($filename); if ($expected instanceof JsonLdException) { @@ -76,15 +76,15 @@ protected static function shouldSkipThisTest(string $filename): bool return false; } - protected static function getOptions(string $filename): ProcessorOptions + protected static function getOptions(string $filename, string $test): ProcessorOptions { $options = new ProcessorOptions(base: static::getBaseUrlForW3CTests($filename)); - if ('0014-in.jsonld' === $filename || '0026-in.jsonld' === $filename) { + if ('0014-in.jsonld' === $test || '0026-in.jsonld' === $test) { $options->processingMode = Context::PROCESSING_MODE_10; } - if ('0044-in.jsonld' === $filename) { + if ('0044-in.jsonld' === $test) { $options->compactArrays = false; } diff --git a/tests/Algorithms/FramerTest.php b/tests/Algorithms/FramerTest.php index 274bcd9e..dbe90fa3 100644 --- a/tests/Algorithms/FramerTest.php +++ b/tests/Algorithms/FramerTest.php @@ -29,10 +29,10 @@ class FramerTest extends AbstractJsonLdTestCase public const FRAMING_DATA_PATH = __DIR__ . '/../../var/cache/w3c-json-ld-framing/tests'; #[DataProvider('provideInputsAndOutputs')] - public function testFrame(string $json, string|JsonLdException $expected, string $filename): void + public function testFrame(string $json, string|JsonLdException $expected, string $filename, string $test): void { $framer = new Framer(documentLoader: static::createDocumentLoader()); - $options = static::getOptions($filename); + $options = static::getOptions($filename, $test); $frame = self::getFrameFor($filename); if ($expected instanceof JsonLdException) { @@ -94,7 +94,21 @@ protected static function shouldSkipThisTest(string $filename): bool return \in_array($filename, $testsToSkip, true); } - protected static function getOptions(string $filename): ProcessorOptions + protected static function getVariantOutputFiles(string $filename): array + { + // #tp020, #tp021, #tp046 and #tp049: the same input and frame as #t0020, + // #t0021, #t0046 and #t0049, framed in JSON-LD 1.1 processing mode (which + // prunes the blank node identifiers) instead of 1.0 mode. + return match ($filename) { + '0020-in.jsonld' => ['p020-out.jsonld'], + '0021-in.jsonld' => ['p021-out.jsonld'], + '0046-in.jsonld' => ['p046-out.jsonld'], + '0049-in.jsonld' => ['p049-out.jsonld'], + default => [], + }; + } + + protected static function getOptions(string $filename, string $test): ProcessorOptions { $options = new ProcessorOptions(base: \sprintf( 'https://w3c.github.io/json-ld-framing/tests/frame/%s', @@ -109,19 +123,19 @@ protected static function getOptions(string $filename): ProcessorOptions '0049-in.jsonld', '0059-in.jsonld', ]; - if (\in_array($filename, $processingMode10Tests, true)) { + if (\in_array($test, $processingMode10Tests, true)) { $options->processingMode = Context::PROCESSING_MODE_10; } - if ('0058-in.jsonld' === $filename) { + if ('0058-in.jsonld' === $test) { $options->omitGraph = false; } - if ('0060-in.jsonld' === $filename) { + if ('0060-in.jsonld' === $test) { $options->ordered = true; } - if ('g001-in.jsonld' === $filename) { + if ('g001-in.jsonld' === $test) { $options->omitGraph = true; } From 74e049916bd90a4a6fa6d686ff295af288756e97 Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:48:17 +0100 Subject: [PATCH 04/11] Add the qa:earl task writing the W3C EARL conformance report --- .castor/earl.php | 299 +++++++++++++++++++++++++++++++++++++++++++++++ .castor/qa.php | 23 +++- CHANGELOG.md | 6 + README.md | 1 + 4 files changed, 328 insertions(+), 1 deletion(-) create mode 100644 .castor/earl.php diff --git a/.castor/earl.php b/.castor/earl.php new file mode 100644 index 00000000..2bea991e --- /dev/null +++ b/.castor/earl.php @@ -0,0 +1,299 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace qa; + +use Castor\Attribute\AsOption; +use Castor\Attribute\AsTask; + +use function Castor\capture; +use function Castor\context; +use function Castor\exit_code; +use function Castor\fs; +use function Castor\io; + +use Symfony\Component\Console\Input\InputOption; + +const CACHE_DIR_EARL = __DIR__ . '/../var/cache/earl'; + +const EARL_SUBJECT_IRI = 'https://github.com/jolicode/structured-data'; +const EARL_ASSERTOR_IRI = 'https://github.com/xavierlacot'; + +/** + * The W3C test suites the EARL report covers, keyed by the PHPUnit test class that + * runs them. The manifest IRIs are the ones the W3C implementation report + * consolidates (https://w3c.github.io/json-ld-api/reports/): an assertion must + * reference the test exactly as the manifest names it, which the fixture file + * names alone cannot give. + * + * A function rather than a constant: Castor loads the task files in alphabetical + * order, so the cache directory constants of qa.php are not defined yet when this + * file is parsed. + * + * @return array + */ +function earlSuites(): array +{ + return [ + 'ExpanderTest' => [ + 'name' => 'expand', + 'manifest' => CACHE_DIR_W3C_TEST_SUITE . '/tests/expand-manifest.jsonld', + 'iri' => 'https://w3c.github.io/json-ld-api/tests/expand-manifest', + ], + 'CompactorTest' => [ + 'name' => 'compact', + 'manifest' => CACHE_DIR_W3C_TEST_SUITE . '/tests/compact-manifest.jsonld', + 'iri' => 'https://w3c.github.io/json-ld-api/tests/compact-manifest', + ], + 'FlattenerTest' => [ + 'name' => 'flatten', + 'manifest' => CACHE_DIR_W3C_TEST_SUITE . '/tests/flatten-manifest.jsonld', + 'iri' => 'https://w3c.github.io/json-ld-api/tests/flatten-manifest', + ], + 'FramerTest' => [ + 'name' => 'frame', + 'manifest' => CACHE_DIR_W3C_FRAMING_TEST_SUITE . '/tests/frame-manifest.jsonld', + 'iri' => 'https://w3c.github.io/json-ld-framing/tests/frame-manifest', + ], + ]; +} + +#[AsTask(name: 'earl', description: 'Generate the W3C EARL conformance report of the JSON-LD algorithms, for https://w3c.github.io/json-ld-api/reports/')] +function earl( + #[AsOption(name: 'release', mode: InputOption::VALUE_REQUIRED, description: 'The library version the report describes (defaults to the closest git tag)')] + ?string $release = null, + #[AsOption(name: 'output', mode: InputOption::VALUE_REQUIRED, description: 'Where to write the Turtle report (defaults to var/cache/earl/jolicode-structured-data-earl.ttl)')] + ?string $output = null, +): int { + io()->title('Generating the W3C EARL conformance report'); + + if (!is_dir(toolsDir() . '/phpunit/vendor')) { + install(); + } + + if (suiteFixturesAreMissing()) { + phpunitPrepare(); + } + + fs()->mkdir(CACHE_DIR_EARL); + $junitFile = CACHE_DIR_EARL . '/junit.xml'; + fs()->remove($junitFile); + + io()->section('Running the W3C test suites'); + + $command = [ + 'php', + '-d memory_limit=-1', + toolsDir() . '/phpunit/vendor/bin/phpunit', + '--log-junit', + $junitFile, + '--no-progress', + ]; + + // One --group per suite: PHPUnit does not split a comma-separated list. + foreach (earlSuites() as $suite) { + $command[] = '--group'; + $command[] = $suite['name']; + } + + $command[] = 'tests/Algorithms'; + + // A failing test is not a failure of this task: it is what the report is for, + // and it shows up as an "earl:failed" outcome. + exit_code($command); + + if (!fs()->exists($junitFile)) { + throw new \RuntimeException(\sprintf('PHPUnit did not write its JUnit log to "%s".', $junitFile)); + } + + $outcomes = earlOutcomesFromJunit($junitFile); + $release ??= earlDefaultRelease(); + $date = new \DateTimeImmutable('now', new \DateTimeZone('UTC')); + $output ??= \sprintf('%s/jolicode-structured-data-earl.ttl', CACHE_DIR_EARL); + + $assertions = []; + $summary = []; + + foreach (earlSuites() as $testClass => $suite) { + $results = $outcomes[$testClass] ?? []; + $summary[$suite['name']] = ['passed' => 0, 'failed' => 0, 'inapplicable' => 0, 'untested' => 0]; + + foreach (earlManifestEntries($suite['manifest']) as $entry) { + // A test that was not run is either out of scope (it only applies to + // JSON-LD 1.0 processors) or genuinely untested: the distinction matters + // in the consolidated report. + $outcome = $results[$entry['test']] ?? ($entry['jsonLd10Only'] ? 'inapplicable' : 'untested'); + ++$summary[$suite['name']][$outcome]; + $assertions[] = ['test' => $suite['iri'] . $entry['id'], 'outcome' => $outcome]; + } + } + + fs()->dumpFile($output, earlTurtle($assertions, $release, $date)); + + io()->section('Outcomes per suite'); + $rows = []; + + foreach ($summary as $suite => $counts) { + $rows[] = [$suite, $counts['passed'], $counts['failed'], $counts['inapplicable'], $counts['untested'], array_sum($counts)]; + } + + io()->table(['Suite', 'Passed', 'Failed', 'Inapplicable (JSON-LD 1.0 only)', 'Untested', 'Manifest entries'], $rows); + io()->success(\sprintf('EARL report for release %s written to %s', $release, $output)); + io()->writeln('Submit it with a pull request adding the file to the "reports/" directory of https://github.com/w3c/json-ld-api.'); + + return 0; +} + +/** + * Reads the outcome of every W3C fixture from the JUnit log, keyed by the short + * name of the test class, then by the fixture input file name. + * + * @return array> + */ +function earlOutcomesFromJunit(string $junitFile): array +{ + $xml = simplexml_load_file($junitFile); + + if (false === $xml) { + throw new \RuntimeException(\sprintf('Could not parse the JUnit log "%s".', $junitFile)); + } + + $outcomes = []; + + foreach ($xml->xpath('//testcase') ?: [] as $testCase) { + $class = (string) $testCase['class']; + $shortClass = substr($class, (int) strrpos($class, '\\') + 1); + + if (!isset(earlSuites()[$shortClass])) { + continue; + } + + if (!preg_match('/ with data set "(.+)"$/', (string) $testCase['name'], $matches)) { + continue; + } + + if (isset($testCase->failure) || isset($testCase->error)) { + $outcome = 'failed'; + } elseif (isset($testCase->skipped)) { + $outcome = 'untested'; + } else { + $outcome = 'passed'; + } + + $outcomes[$shortClass][$matches[1]] = $outcome; + } + + return $outcomes; +} + +/** + * The tests a W3C manifest lists: the fragment identifying each one, the PHPUnit + * data set name it runs as, and whether it only applies to JSON-LD 1.0 processors. + * + * The data set name follows the convention of AbstractJsonLdTestCase: the expected + * output file with "-out" replaced by "-in" (several manifest entries share an + * input file but not an expected output), or the input file for a negative test. + * + * @return list + */ +function earlManifestEntries(string $manifestFile): array +{ + $content = file_get_contents($manifestFile); + + if (false === $content) { + throw new \RuntimeException(\sprintf('Could not read the W3C manifest "%s". Run "castor qa:phpunit:prepare --force" to download it.', $manifestFile)); + } + + $manifest = json_decode($content, true, 512, \JSON_THROW_ON_ERROR); + + if (!\is_array($manifest) || !\is_array($manifest['sequence'] ?? null)) { + throw new \RuntimeException(\sprintf('The W3C manifest "%s" has no "sequence" entry.', $manifestFile)); + } + + $entries = []; + + foreach ($manifest['sequence'] as $test) { + if (!\is_array($test) || !\is_string($test['@id'] ?? null) || !\is_string($test['input'] ?? null)) { + continue; + } + + $option = \is_array($test['option'] ?? null) ? $test['option'] : []; + + $entries[] = [ + 'id' => $test['@id'], + 'test' => \is_string($test['expect'] ?? null) + ? str_replace('-out', '-in', basename($test['expect'])) + : basename($test['input']), + 'jsonLd10Only' => 'json-ld-1.0' === ($option['specVersion'] ?? null), + ]; + } + + return $entries; +} + +function earlDefaultRelease(): string +{ + $tag = trim(capture(['git', 'describe', '--tags', '--abbrev=0'], context()->withAllowFailure()->withQuiet())); + + return '' === $tag ? 'dev-main' : ltrim($tag, 'v'); +} + +/** + * @param list $assertions + */ +function earlTurtle(array $assertions, string $release, \DateTimeImmutable $date): string +{ + $lines = [ + '@prefix dc: .', + '@prefix doap: .', + '@prefix earl: .', + '@prefix foaf: .', + '@prefix xsd: .', + '', + \sprintf('<%s> a doap:Project, earl:TestSubject, earl:Software ;', EARL_SUBJECT_IRI), + ' doap:name "jolicode/structured-data" ;', + ' dc:title "jolicode/structured-data" ;', + ' doap:description "A PHP toolkit to validate and convert structured data: Schema.org and Google Rich Results validation, microdata/RDFa/JSON-LD extraction, and the W3C JSON-LD 1.1 algorithms."@en ;', + \sprintf(' doap:homepage <%s> ;', EARL_SUBJECT_IRI), + \sprintf(' doap:license <%s/blob/main/LICENSE> ;', EARL_SUBJECT_IRI), + ' doap:programming-language "PHP" ;', + \sprintf(' doap:developer <%s>, ;', EARL_ASSERTOR_IRI), + \sprintf(' dc:creator <%s> ;', EARL_ASSERTOR_IRI), + ' doap:release [', + \sprintf(' doap:name "jolicode/structured-data %s" ;', $release), + \sprintf(' doap:revision "%s" ;', $release), + \sprintf(' doap:created "%s"^^xsd:date', $date->format('Y-m-d')), + ' ] .', + '', + \sprintf('<%s> a foaf:Person, earl:Assertor ;', EARL_ASSERTOR_IRI), + ' foaf:name "Xavier Lacot" ;', + \sprintf(' foaf:homepage <%s> .', EARL_ASSERTOR_IRI), + '', + ' a foaf:Person ;', + ' foaf:name "Hédic Guibert" ;', + ' foaf:homepage .', + '', + ]; + + $timestamp = $date->format('Y-m-d\TH:i:s\Z'); + + foreach ($assertions as $assertion) { + $lines[] = '[ a earl:Assertion ;'; + $lines[] = \sprintf(' earl:assertedBy <%s> ;', EARL_ASSERTOR_IRI); + $lines[] = \sprintf(' earl:subject <%s> ;', EARL_SUBJECT_IRI); + $lines[] = \sprintf(' earl:test <%s> ;', $assertion['test']); + $lines[] = \sprintf(' earl:result [ a earl:TestResult ; earl:outcome earl:%s ; dc:date "%s"^^xsd:dateTime ] ;', $assertion['outcome'], $timestamp); + $lines[] = ' earl:mode earl:automatic ] .'; + $lines[] = ''; + } + + return implode("\n", $lines); +} diff --git a/.castor/qa.php b/.castor/qa.php index 3f3275e1..327b4fc3 100644 --- a/.castor/qa.php +++ b/.castor/qa.php @@ -76,7 +76,9 @@ function toolsDir(): string function suiteFixturesAreMissing(): bool { return !fs()->exists(\sprintf('%s/tests/flatten/output', CACHE_DIR_W3C_TEST_SUITE)) - || !fs()->exists(\sprintf('%s/tests/frame/output', CACHE_DIR_W3C_FRAMING_TEST_SUITE)); + || !fs()->exists(\sprintf('%s/tests/frame/output', CACHE_DIR_W3C_FRAMING_TEST_SUITE)) + || !fs()->exists(\sprintf('%s/tests/expand-manifest.jsonld', CACHE_DIR_W3C_TEST_SUITE)) + || !fs()->exists(\sprintf('%s/tests/frame-manifest.jsonld', CACHE_DIR_W3C_FRAMING_TEST_SUITE)); } #[AsTask(description: 'Installs qa tooling')] @@ -201,6 +203,19 @@ function phpunitPrepare( $zip->close(); foreach (Algorithms::algorithmNames() as $algorithm) { + // The manifest is what the EARL conformance report is built from (see + // "castor qa:earl"): it lists every test with its IRI, which the fixture + // file names alone cannot give. + $manifest = \sprintf('%s-manifest.jsonld', $algorithm); + + if (fs()->exists(\sprintf('%s/json-ld-api-%s/tests/%s', CACHE_DIR_W3C_TEST_SUITE, $ref, $manifest))) { + fs()->copy( + \sprintf('%s/json-ld-api-%s/tests/%s', CACHE_DIR_W3C_TEST_SUITE, $ref, $manifest), + \sprintf('%s/tests/%s', CACHE_DIR_W3C_TEST_SUITE, $manifest), + true, + ); + } + foreach (['-in.jsonld' => 'input', '-out.jsonld' => 'output', '-context.jsonld' => 'context'] as $suffix => $directory) { $targetDirectory = \sprintf('%s/tests/%s/%s', CACHE_DIR_W3C_TEST_SUITE, $algorithm, $directory); fs()->mkdir($targetDirectory); @@ -243,6 +258,12 @@ function phpunitPrepare( $framingZip->extractTo(CACHE_DIR_W3C_FRAMING_TEST_SUITE); $framingZip->close(); + fs()->copy( + \sprintf('%s/json-ld-framing-%s/tests/frame-manifest.jsonld', CACHE_DIR_W3C_FRAMING_TEST_SUITE, $framingRef), + \sprintf('%s/tests/frame-manifest.jsonld', CACHE_DIR_W3C_FRAMING_TEST_SUITE), + true, + ); + foreach (['-in.jsonld' => 'input', '-out.jsonld' => 'output', '-frame.jsonld' => 'frame'] as $suffix => $directory) { $targetDirectory = \sprintf('%s/tests/frame/%s', CACHE_DIR_W3C_FRAMING_TEST_SUITE, $directory); fs()->mkdir($targetDirectory); diff --git a/CHANGELOG.md b/CHANGELOG.md index 59ae585e..70b1d8fe 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## [Unreleased] +### Added + +- `castor qa:earl` runs the W3C test suites and writes the EARL conformance report + consolidated by the W3C JSON-LD implementation report. The W3C manifests are now kept + with the downloaded test suites. + ### Fixed - Framing in JSON-LD 1.1 mode dropped a property whose only value was a node reduced diff --git a/README.md b/README.md index c8b711b8..ec4d4481 100644 --- a/README.md +++ b/README.md @@ -398,6 +398,7 @@ Command | Description `castor qa:cs` | Fixes coding standards `castor qa:phpstan` | Runs PHPStan `castor qa:all` | Runs all QA tasks +`castor qa:earl` | Runs the W3C test suites and writes the EARL conformance report (see [Conformance](#conformance)) The following commands are available to run the tests: From 3255422493284854cfebedaed206d8a7b9cdb2ae Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:48:31 +0100 Subject: [PATCH 05/11] Document the benchmark figures and run the worker benchmark with the validators --- .castor/qa.php | 12 +++ BENCHMARKS.md | 99 +++++++++++++++++++ CHANGELOG.md | 3 + README.md | 2 + .../Benchmark/WorkerValidationBench.php | 2 +- 5 files changed, 117 insertions(+), 1 deletion(-) create mode 100644 BENCHMARKS.md diff --git a/.castor/qa.php b/.castor/qa.php index 327b4fc3..19344ca7 100644 --- a/.castor/qa.php +++ b/.castor/qa.php @@ -24,6 +24,7 @@ use JoliCode\StructuredData\Audit\AuditOptions; use JoliCode\StructuredData\JsonLd\Algorithms; +use JoliCode\StructuredData\Tests\Validation\Benchmark\WorkerValidationBench; use JoliCode\StructuredData\Validator; use JoliCode\StructuredData\Vocabularies\Generators\Google\Filesystem as GoogleFilesystem; use JoliCode\StructuredData\Vocabularies\Generators\SchemaOrg\Filesystem as SchemaOrgFilesystem; @@ -612,6 +613,7 @@ function benchValidators( toolsDir() . '/phpbench/vendor/bin/phpbench', 'run', 'tests/Validation/Benchmark/JsonLdValidatorBench.php', + 'tests/Validation/Benchmark/WorkerValidationBench.php', '--no-interaction', '--report=readable', '--output=console', @@ -634,6 +636,16 @@ function benchValidators( $htmlAverage / 1_000_000, )); + // The two figures above audit the same document over and over, so the + // content-keyed caches of the Validator serve most of the work. The worker + // benchmark audits a stream of distinct documents and is the figure to quote + // for a crawler or a queue consumer: every audit is a cache miss. + $workerAverage = averageValidatorBenchStat($results, 'benchDistinctDocumentsStream'); + io()->success(\sprintf( + 'In a long-lived worker auditing distinct documents (no cache hit), it took %.6F seconds per document.', + $workerAverage / 1_000_000 / WorkerValidationBench::DOCUMENTS_PER_ITERATION, + )); + $htmlReportPath = rootDir() . '/var/cache/benchmark-results-validators.html'; io()->info(\sprintf('Open HTML benchmark report: file://%s', $htmlReportPath)); } diff --git a/BENCHMARKS.md b/BENCHMARKS.md new file mode 100644 index 00000000..052001e5 --- /dev/null +++ b/BENCHMARKS.md @@ -0,0 +1,99 @@ +# Benchmarks + +The figures below come from `castor qa:bench:all`, run on 2026-11-13 on a developer +laptop, with PHP 8.5 in CLI, opcache and JIT disabled. They are +[PHPBench](https://github.com/phpbench/phpbench) *mode* values: the most frequent +measurement over the iterations, with the relative standard deviation next to it. +Memory is the peak of the benchmark process. Take them as orders of magnitude: the +CI runs below are the reference to compare against over time. + +The same benchmarks run every Sunday in CI, on PHP 8.4 and 8.5, and their HTML reports +are attached to the scheduled run as the `benchmark-reports-php*` artifacts. + +## Validating documents + +`Validator::audit()` runs the whole pipeline: extraction of the JSON-LD, microdata and +RDFa blocks, JSON-LD expansion, mapping to the schema.org vocabulary, then the +schema.org and Google validators. + +### A stream of distinct documents + +This is the figure to quote for a crawler, a queue consumer or any long-lived process: +one `Validator` audits 25 documents that all differ from each other, so no +content-keyed cache can serve them. + +| Scenario | Document | Time per document | Peak memory | +| --- | --- | --- | --- | +| 25 distinct variants of the Google *Book* fixture | 9 KB JSON-LD, 10 nested types | 12.7 ms | 20.6 MB | + +The 25 documents took 318 ms in total (±0.25 %). + +### The same document, again and again + +These subjects audit the same document on every revolution. The extraction and +expansion results are cached by content, so they measure the validators and the +mapping more than the full pipeline, and they are the lower bound of what an audit +costs. + +| Document | Size | Time per audit | Peak memory | +| --- | --- | --- | --- | +| schema.org fixture, a single type | 0.4 KB JSON-LD | 1.5 ms | 5.2 MB | +| schema.org fixture, nested types | 6 KB JSON-LD | 3.3 ms | 5.8 MB | +| Google *Book* fixture | 9 KB JSON-LD | 12.6 ms | 8.1 MB | +| jolicode.com homepage | 139 KB HTML | 6.8 ms | 6.6 MB | +| jolicampus.com homepage | 95 KB HTML | 5.5 ms | 6.5 MB | +| Google structured data introduction | 187 KB HTML | 10.5 ms | 6.5 MB | + +The HTML pages are real pages, downloaded by `castor qa:phpunit:download-fixtures` +from hosts JoliCode owns or operates (plus the Google documentation page), and never +committed. + +## JSON-LD algorithms + +The inputs are fixtures of the W3C test suites, except where noted. The context +processor benchmarks measure the context processing step alone. + +| Algorithm | Input | Time | Peak memory | +| --- | --- | --- | --- | +| Context processing | inline context | 11 µs | 3.9 MB | +| Context processing | scoped contexts | 24 µs | 3.9 MB | +| Context processing | nested contexts | 12 µs | 3.9 MB | +| Expansion | minimal document (`expand/0002`) | 224 µs | 3.9 MB | +| Expansion | context-heavy document (`expand/0036`) | 409 µs | 3.9 MB | +| Expansion | nested `@graph` (`expand/pr25`) | 829 µs | 3.9 MB | +| Expansion | 8 nodes each repeating the schema.org context | 3.1 ms | 5.1 MB | +| Compaction | inline context | 215 µs | 3.9 MB | +| Compaction | into the schema.org context | 13.4 ms | 10.2 MB | +| Flattening | minimal document | 266 µs | 3.9 MB | +| Flattening | nested lists | 600 µs | 3.9 MB | +| Framing | by type, schema.org context | 16.2 ms | 10.5 MB | +| Framing | embedded node, schema.org context | 16.2 ms | 10.5 MB | + +Compaction into the schema.org context and framing with it both cost around 15 ms: +that is the price of building the inverse context of the roughly 3,000 schema.org +terms, which the other subjects never need. Expanding *with* the schema.org context +is cheap in comparison, because the processed context is served from the static +vocabulary files the library ships with. The "repeated remote context" subject is the +regression guard for that path. + +## Reproducing + +```bash +castor qa:install # phpbench and the other QA tools +castor qa:phpunit:prepare # the W3C test suites +castor qa:phpunit:download-fixtures # the HTML pages +castor qa:bench:all +``` + +`castor qa:bench:validators -d` additionally breaks the HTML pipeline down step by +step (format detection, extraction, parsing, mapping, validation); it is slow. + +For finer time units than the default seconds, call PHPBench directly: + +```bash +tools/phpbench/vendor/bin/phpbench run tests/Algorithms/Benchmark --report=readable --time-unit=microseconds +tools/phpbench/vendor/bin/phpbench run tests/Validation/Benchmark/JsonLdValidatorBench.php tests/Validation/Benchmark/WorkerValidationBench.php --report=readable --time-unit=milliseconds +``` + +For the record, the full PHPUnit suite (1,496 tests, 3,317 assertions, W3C suites +included) runs in about 20 seconds on the same machine. diff --git a/CHANGELOG.md b/CHANGELOG.md index 70b1d8fe..84d2f3ab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,9 @@ - `castor qa:earl` runs the W3C test suites and writes the EARL conformance report consolidated by the W3C JSON-LD implementation report. The W3C manifests are now kept with the downloaded test suites. +- `BENCHMARKS.md` documents the benchmark figures and what each of them measures. + `castor qa:bench:validators` now also runs the worker benchmark, which audits a stream + of distinct documents and is the figure to quote for a crawler. ### Fixed diff --git a/README.md b/README.md index ec4d4481..dd240055 100644 --- a/README.md +++ b/README.md @@ -426,6 +426,8 @@ Command | Description `castor qa:bench:validators` | Runs the validators benchmark `castor qa:bench:validators -d` | Runs the detailed and slow validators benchmark +The latest figures, and what each of them measures, are in [BENCHMARKS.md](BENCHMARKS.md). + ## Vocabulary generation commands The validation classes shipped in `src/Vocabularies/Generated` are generated from the diff --git a/tests/Validation/Benchmark/WorkerValidationBench.php b/tests/Validation/Benchmark/WorkerValidationBench.php index 3d74efba..bab6e604 100644 --- a/tests/Validation/Benchmark/WorkerValidationBench.php +++ b/tests/Validation/Benchmark/WorkerValidationBench.php @@ -21,7 +21,7 @@ */ class WorkerValidationBench { - private const DOCUMENTS_PER_ITERATION = 25; + public const DOCUMENTS_PER_ITERATION = 25; private Validator $validator; From db91bd2b38cf4593e3241e2891953f6d59185eb9 Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:48:40 +0100 Subject: [PATCH 06/11] Rewrite the README opening with badges, positioning and a comparison table --- README.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index dd240055..e20831b2 100644 --- a/README.md +++ b/README.md @@ -8,8 +8,11 @@
+[![CI](https://github.com/jolicode/structured-data/actions/workflows/ci.yml/badge.svg)](https://github.com/jolicode/structured-data/actions/workflows/ci.yml) +[![W3C JSON-LD 1.1 test suites](https://img.shields.io/badge/W3C_JSON--LD_1.1-test_suites_passing-brightgreen)](#conformance) +[![PHPStan level 9](https://img.shields.io/badge/PHPStan-level_9-brightgreen)](phpstan.neon) [![PHP Version Require](http://poser.pugx.org/jolicode/structured-data/require/php)](https://packagist.org/packages/jolicode/structured-data) -[![Monthly Downloads](http://poser.pugx.org/jolicode/structured-data/d/monthly)](https://packagist.org/packages/jolicode/structured-data) +[![License](http://poser.pugx.org/jolicode/structured-data/license)](LICENSE)
@@ -20,6 +23,67 @@ It includes: - a Google validator, which tells you whether your structured data is eligible for [Google Rich Results](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data); - an extractor for JSON-LD, microdata and RDFa embedded in HTML documents. +It is used in production by [redirection.io](https://redirection.io/), which audits the +structured data of the pages it crawls with it. + +## Why this library + +Structured data is usually validated in a browser, with Google's +[Rich Results Test](https://search.google.com/test/rich-results) or +[validator.schema.org](https://validator.schema.org/), or not at all. Neither tool has an +API, so nothing checks the template you just changed, the pages you deploy, or the +millions of pages a crawler visits. This library brings that check into PHP: + +- **Google Rich Results eligibility, offline.** The Google validator reproduces the + required and recommended properties of every type the Google documentation describes, + including the rules the documentation only states in prose (a `price` needs a + `priceCurrency`, a finite return window needs `merchantReturnDays`...), and applies + them the way Google does: to the schema.org subtypes of the documented types, and to + every entity of the page, however deeply it is nested. No request leaves your process. +- **Exact JSON-LD 1.1.** The four W3C algorithms pass the official test suites (see + [Conformance](#conformance)), so a document is validated on what it means rather than + on how it was written: compact IRIs, nested and scoped contexts, `@graph`, aliases and + `@reverse` are all resolved before validation. +- **One pipeline for JSON-LD, microdata and RDFa.** Everything found in the HTML is + extracted, expanded and validated the same way, and a page mixing valid and broken + blocks still yields what can be used, with a warning for the rest. +- **Safe on pages you do not control.** No network request and no file read unless you + opt in with an allow-list (see [Loading remote contexts](#loading-remote-contexts)). + Hostile nesting depths and malformed documents are refused instead of crashing the + process. +- **Built for workers.** One `Validator` audits a stream of documents with bounded + memory and results that do not depend on what was audited before. A full audit of a + heavy JSON-LD document takes about 13 ms (see [BENCHMARKS.md](BENCHMARKS.md)). +- **Diagnostics you can act on.** Every message carries its severity, its path in the + document, its line range, and a link to the Google documentation it comes from. +- **Vocabularies you can audit.** The schema.org classes are generated from the official + release file, the Google rules from a crawled and curated copy of the documentation, and + CI checks that regeneration is reproducible. The W3C suites, the Google documentation + crawl and the mutation tests are re-run every week to catch drift. + +How it compares with what you would use otherwise to *validate* structured data: + +| | [Rich Results Test](https://search.google.com/test/rich-results) | [humanmade/schema-org-validator](https://github.com/humanmade/schema-org-validator) | jolicode/structured-data | +| --- | --- | --- | --- | +| Runs | in a browser, no API | in PHP | in PHP | +| Input | a public URL, or pasted code | a JSON-LD document | an HTML page (JSON-LD, microdata, RDFa) or a JSON-LD document | +| JSON-LD | fully processed | read as written: names are resolved, contexts are not | expanded with the W3C JSON-LD 1.1 algorithms before validation | +| Google rules | the reference | 23 profiles transcribed by hand | 36 types generated from a crawl of the documentation, drift-checked weekly | +| Validation issues location | highlighted in the tool | a JSON pointer | a path in the document, and the position of the block in the HTML | +| Remote `@context` | fetched by Google | not loaded | can be loaded. By default, denied unless allow-listed | +| License | - | GPL-2.0 | MIT | + +The other PHP libraries in this space do a different job, and combine well with this one. +[spatie/schema-org](https://github.com/spatie/schema-org) writes JSON-LD; this library +checks what it wrote. [brick/schema](https://github.com/brick/schema) and +[crwlrsoft/schema-org](https://github.com/crwlrsoft/schema-org) read structured data from +HTML into PHP objects and accept whatever they find; this library tells you what is wrong with +it. [ml/json-ld](https://github.com/lanthaler/JsonLD) and +[digitalbazaar/php-json-ld](https://github.com/digitalbazaar/php-json-ld) are JSON-LD +processors of the 1.0 era, which load remote contexts by default; neither appears in the +[W3C JSON-LD 1.1 implementation report](https://w3c.github.io/json-ld-api/reports/), +which lists no PHP processor at all so far. + ## Installation Install the library with [Composer](https://getcomposer.org/): From bcfaa50063cf79f694cad5b1cc238b537bf965ba Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:48:47 +0100 Subject: [PATCH 07/11] Extract nested top-level microdata items and the content attribute of any element --- CHANGELOG.md | 4 ++ src/Extraction/MicrodataExtractor.php | 13 +++++- tests/Validation/ExtractorTest.php | 63 +++++++++++++++++++++++++++ 3 files changed, 79 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 84d2f3ab..342a2056 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,10 @@ ### Fixed +- Microdata: a top-level item (an `itemscope` without `itemprop`) placed inside another + item's element was dropped, as was the `content` attribute of any element but `` + (``, which has no `href`). Both are common on real + pages, and Google reads them. - Framing in JSON-LD 1.1 mode dropped a property whose only value was a node reduced to a pruned blank node identifier (W3C test `frame#tp046`): the empty node object is now kept, as `{}`. diff --git a/src/Extraction/MicrodataExtractor.php b/src/Extraction/MicrodataExtractor.php index b8eabf86..f415d1ff 100644 --- a/src/Extraction/MicrodataExtractor.php +++ b/src/Extraction/MicrodataExtractor.php @@ -73,7 +73,11 @@ public function extractStructuredDataContent(string $body): array continue; } - if (!$this->hasAncestorItemScope($itemScope)) { + // An item without itemprop is a top-level item wherever it sits, even + // inside another item's element, as the specification defines it. An + // item with itemprop but no enclosing item is kept as a top-level item + // too, rather than dropped. + if (!$itemScope->hasAttribute('itemprop') || !$this->hasAncestorItemScope($itemScope)) { $topLevelItems[] = $itemScope; } } @@ -304,6 +308,13 @@ private function extractPropertyValue(\DOMElement $propertyNode): ?string return trim($propertyNode->getAttribute('datetime')); } + // The specification only reads "content" on , but Google reads it on + // any element, and pages rely on it (a without href, + // for instance). + if ($propertyNode->hasAttribute('content')) { + return trim($propertyNode->getAttribute('content')); + } + $text = trim($propertyNode->textContent); return '' === $text ? null : $text; diff --git a/tests/Validation/ExtractorTest.php b/tests/Validation/ExtractorTest.php index 78113c3e..41b65d2d 100644 --- a/tests/Validation/ExtractorTest.php +++ b/tests/Validation/ExtractorTest.php @@ -96,6 +96,69 @@ public function testItExtractsEachTopLevelMicrodataItemAsASeparateElement(): voi $this->assertStringContainsString('"name":"Acme Org"', $elements[1]->content); } + public function testItExtractsATopLevelMicrodataItemNestedInAnotherItemsElement(): void + { + // A BreadcrumbList without itemprop, inside the VideoObject's element: it + // is a top-level item of its own, and the VideoObject gets none of its + // properties. + $extractor = new Extractor(); + + $document = <<<'HTML' + + + +
+ + + + + + + +
+ + +HTML; + + $elements = $extractor->extract($document); + + $this->assertCount(2, $elements); + $this->assertStringContainsString('"@type":"VideoObject"', $elements[0]->content); + $this->assertStringContainsString('"name":"A video"', $elements[0]->content); + $this->assertStringNotContainsString('itemListElement', $elements[0]->content); + $this->assertStringContainsString('"@type":"BreadcrumbList"', $elements[1]->content); + $this->assertStringContainsString('"name":"A channel"', $elements[1]->content); + } + + public function testItReadsTheContentAttributeOfAnyMicrodataPropertyElement(): void + { + // The specification only defines "content" on , but Google reads it + // everywhere, and real pages name authors with . + $extractor = new Extractor(); + + $document = <<<'HTML' + + + +
+ + Pop +
+ + +HTML; + + $elements = $extractor->extract($document); + + $this->assertCount(1, $elements); + $this->assertStringContainsString('"url":"https://example.com/@channel"', $elements[0]->content); + $this->assertStringContainsString('"name":"Rick Astley"', $elements[0]->content); + $this->assertStringContainsString('"genre":"Music"', $elements[0]->content); + } + public function testItFallsBackToRdfaWhenNoJsonLdOrMicrodataIsPresent(): void { $extractor = new Extractor(); From 9c930cb5d9e637a7163c4bb6cf9ff19e89575a1a Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:49:22 +0100 Subject: [PATCH 08/11] Validate schema.org subtypes and nested entities as Google does --- CHANGELOG.md | 10 + generators/Google/Generator.php | 9 + .../structured-data/AggregateRating.json | 1 + resources/google/structured-data/Answer.json | 1 + resources/google/structured-data/Comment.json | 1 + resources/google/structured-data/Event.json | 1 + .../google/structured-data/ImageObject.json | 1 + .../google/structured-data/ItemList.json | 1 + .../google/structured-data/Question.json | 1 + resources/google/structured-data/README.md | 3 + resources/google/structured-data/Review.json | 1 + .../SpeakableSpecification.json | 1 + .../Generated/Google/AggregateRating.php | 3 + src/Vocabularies/Generated/Google/Answer.php | 3 + src/Vocabularies/Generated/Google/Article.php | 3 + .../Generated/Google/BlogPosting.php | 3 + .../Generated/Google/BookEdition.php | 3 + .../Generated/Google/BookWork.php | 3 + .../Generated/Google/BreadcrumbList.php | 3 + .../Generated/Google/ClaimReview.php | 3 + src/Vocabularies/Generated/Google/Comment.php | 3 + src/Vocabularies/Generated/Google/Course.php | 3 + .../Generated/Google/DataFeed.php | 3 + src/Vocabularies/Generated/Google/Dataset.php | 3 + .../Google/DiscussionForumPosting.php | 3 + .../Google/EmployerAggregateRating.php | 3 + src/Vocabularies/Generated/Google/Event.php | 3 + src/Vocabularies/Generated/Google/FAQPage.php | 3 + .../Generated/Google/ImageObject.php | 3 + .../Generated/Google/ItemList.php | 3 + .../Generated/Google/JobPosting.php | 3 + src/Vocabularies/Generated/Google/Library.php | 3 + .../Generated/Google/LibrarySystem.php | 3 + .../Generated/Google/LocalBusiness.php | 3 + .../Generated/Google/MathSolver.php | 3 + .../Generated/Google/MobileApplication.php | 3 + src/Vocabularies/Generated/Google/Movie.php | 3 + .../Generated/Google/NewsArticle.php | 3 + .../Generated/Google/OnlineStore.php | 3 + .../Generated/Google/Organization.php | 3 + .../Generated/Google/ProductGroup.php | 3 + .../Google/ProductMerchantListing.php | 3 + .../Generated/Google/ProductSnippet.php | 3 + .../Generated/Google/ProfilePage.php | 3 + src/Vocabularies/Generated/Google/QAPage.php | 3 + .../Generated/Google/Question.php | 3 + src/Vocabularies/Generated/Google/Quiz.php | 3 + src/Vocabularies/Generated/Google/Recipe.php | 3 + src/Vocabularies/Generated/Google/Review.php | 3 + .../Generated/Google/SocialMediaPosting.php | 3 + .../Generated/Google/SoftwareApplication.php | 3 + .../Google/SpeakableSpecification.php | 3 + .../Generated/Google/SpecialAnnouncement.php | 3 + .../Generated/Google/VacationRental.php | 3 + .../Generated/Google/VideoObject.php | 3 + .../Generated/Google/WebApplication.php | 3 + src/Vocabularies/Validators/Google/Stack.php | 233 ++++++++++++------ .../Google/ValidationPropertiesNormalizer.php | 28 ++- .../Validators/SchemaOrgTypeHierarchy.php | 96 ++++++++ .../GoogleValidatorInfrastructureTest.php | 74 ++++++ .../Validation/SchemaOrgTypeHierarchyTest.php | 44 ++++ .../Validation/fixtures/google-baseline.json | 39 ++- .../google/article-about-event.jsonld | 35 +++ .../article-comments-not-promoted.jsonld | 27 ++ .../fixtures/google/event-subtype.jsonld | 18 ++ .../google/howto-steps-not-carousel.jsonld | 22 ++ 66 files changed, 700 insertions(+), 79 deletions(-) create mode 100644 src/Vocabularies/Validators/SchemaOrgTypeHierarchy.php create mode 100644 tests/Validation/SchemaOrgTypeHierarchyTest.php create mode 100644 tests/Validation/fixtures/google/article-about-event.jsonld create mode 100644 tests/Validation/fixtures/google/article-comments-not-promoted.jsonld create mode 100644 tests/Validation/fixtures/google/event-subtype.jsonld create mode 100644 tests/Validation/fixtures/google/howto-steps-not-carousel.jsonld diff --git a/CHANGELOG.md b/CHANGELOG.md index 342a2056..0f44d669 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,16 @@ ### Fixed +- Google validator: the schema.org subtypes of a documented type are now validated with + its rules, as Google does (a `BusinessEvent` is an `Event`, a `Restaurant` a + `LocalBusiness`, a `TechArticle` an `Article`). The rule files can refuse subtypes + (`ItemList`) or exclude some of them (`Event` excludes `CourseInstance`, + `PublicationEvent`...). +- Google validator: an entity nested under a property its parent does not document (an + event in the `about` of an article, a video in a course) was never validated. It is now + validated as a rich result of its own, as Google reports it, when its type is one Google + documents on its own; the types Google only documents as parts of another one + (`Comment`, `Answer`, `AggregateRating`, `ImageObject`...) are left alone. - Microdata: a top-level item (an `itemscope` without `itemprop`) placed inside another item's element was dropped, as was the `content` attribute of any element but `` (``, which has no `href`). Both are common on real diff --git a/generators/Google/Generator.php b/generators/Google/Generator.php index d8eb12e5..64bbc33c 100644 --- a/generators/Google/Generator.php +++ b/generators/Google/Generator.php @@ -32,6 +32,9 @@ * documentation?: string, * specialRules?: list, * supportedTypes: list, + * standalone?: bool, + * acceptsSubtypes?: bool, + * excludedSubtypes?: list, * properties?: array, * } * @phpstan-type GoogleFile GoogleDefinition|array{subtypes: list} @@ -139,6 +142,12 @@ private function generateClass(array $type, bool $hasMultipleDefinitions = false ->makePublic(), $this->factory->classConst('SPECIAL_RULE_KEYS', $type['specialRules'] ?? []) ->makePublic(), + $this->factory->classConst('STANDALONE', $type['standalone'] ?? true) + ->makePublic(), + $this->factory->classConst('ACCEPTS_SUBTYPES', $type['acceptsSubtypes'] ?? true) + ->makePublic(), + $this->factory->classConst('EXCLUDED_SUBTYPES', $type['excludedSubtypes'] ?? []) + ->makePublic(), $this->factory->classConst('PROPERTIES', $properties) ->makePublic(), ]); diff --git a/resources/google/structured-data/AggregateRating.json b/resources/google/structured-data/AggregateRating.json index 500af9cc..7ca18c2f 100644 --- a/resources/google/structured-data/AggregateRating.json +++ b/resources/google/structured-data/AggregateRating.json @@ -1,6 +1,7 @@ { "name": "AggregateRating", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/review-snippet", + "standalone": false, "specialRules": [], "supportedTypes": [ "AggregateRating" diff --git a/resources/google/structured-data/Answer.json b/resources/google/structured-data/Answer.json index 96bbe4b1..2d86c327 100644 --- a/resources/google/structured-data/Answer.json +++ b/resources/google/structured-data/Answer.json @@ -1,6 +1,7 @@ { "name": "Answer", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/qapage#answer", + "standalone": false, "specialRules": [], "supportedTypes": [ "Answer" diff --git a/resources/google/structured-data/Comment.json b/resources/google/structured-data/Comment.json index 5624020b..21a888e2 100644 --- a/resources/google/structured-data/Comment.json +++ b/resources/google/structured-data/Comment.json @@ -1,6 +1,7 @@ { "name": "Comment", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/qapage#comment", + "standalone": false, "specialRules": [], "supportedTypes": [ "Comment" diff --git a/resources/google/structured-data/Event.json b/resources/google/structured-data/Event.json index af892f44..c76cd382 100644 --- a/resources/google/structured-data/Event.json +++ b/resources/google/structured-data/Event.json @@ -1,6 +1,7 @@ { "name": "Event", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/event", + "excludedSubtypes": ["CourseInstance", "DeliveryEvent", "PublicationEvent", "UserInteraction"], "specialRules": [], "supportedTypes": [ "Event" diff --git a/resources/google/structured-data/ImageObject.json b/resources/google/structured-data/ImageObject.json index 3fcfe010..6aa6f836 100644 --- a/resources/google/structured-data/ImageObject.json +++ b/resources/google/structured-data/ImageObject.json @@ -1,6 +1,7 @@ { "name": "ImageObject", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/image-license-metadata", + "standalone": false, "specialRules": [], "supportedTypes": [ "ImageObject" diff --git a/resources/google/structured-data/ItemList.json b/resources/google/structured-data/ItemList.json index 6fc23060..56b9dd90 100644 --- a/resources/google/structured-data/ItemList.json +++ b/resources/google/structured-data/ItemList.json @@ -1,6 +1,7 @@ { "name": "ItemList", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/carousel", + "acceptsSubtypes": false, "specialRules": [], "supportedTypes": [ "ItemList" diff --git a/resources/google/structured-data/Question.json b/resources/google/structured-data/Question.json index 9fd0fc7d..8261921e 100644 --- a/resources/google/structured-data/Question.json +++ b/resources/google/structured-data/Question.json @@ -1,6 +1,7 @@ { "name": "Question", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/qapage#question", + "standalone": false, "specialRules": [], "supportedTypes": [ "Question" diff --git a/resources/google/structured-data/README.md b/resources/google/structured-data/README.md index 6ef3e16e..d93f1e4d 100644 --- a/resources/google/structured-data/README.md +++ b/resources/google/structured-data/README.md @@ -41,6 +41,9 @@ For a complete update workflow, use the dedicated upgrade guidelines at `../UPGR - **documentation**: A URL (with anchor) pointing to the Google structured-data documentation. - **specialRules**: An array of special-rule keys applied for this type (e.g., `"google.breadcrumb.last_item_optional"`). These keys are resolved by the SpecialRulesRegistry at validation time. - **supportedTypes**: Defines what the `@type` entry must be (or must be one of, if in an array). +- **acceptsSubtypes**: Optional, `true` by default. Google applies most of its rules to the schema.org subtypes of the documented type as well (a `BusinessEvent` is validated as an `Event`, a `Restaurant` as a `LocalBusiness`). Set it to `false` when the rules only make sense for the exact type (`ItemList`: a `HowToStep` is not a carousel). +- **excludedSubtypes**: Optional. The schema.org subtypes (and their own subtypes) the rules do not apply to, when `acceptsSubtypes` is left to `true` (`Event`: a `CourseInstance` or a `PublicationEvent` is not an event people attend). +- **standalone**: Optional, `true` by default. Google reports every entity of a page as a rich result candidate, wherever it is nested, so a type found under a property its parent does not document is validated on its own. Set it to `false` for the types Google only documents as parts of another one (`Comment`, `Answer`, `AggregateRating`...), which must not be reported as rich results when found elsewhere. - **value**: Used when a specific value is expected for a property. If set, `supportedTypes` must be a DataType (usually `Text` or `URL`, but not exclusively). - **@target**: Used when a property accepts multiple types with different property sets. Defines properties for a targeted type. See `Book.json` for an example. - **properties**: The validation properties for a given type. diff --git a/resources/google/structured-data/Review.json b/resources/google/structured-data/Review.json index a5550263..23624bfa 100644 --- a/resources/google/structured-data/Review.json +++ b/resources/google/structured-data/Review.json @@ -1,6 +1,7 @@ { "name": "Review", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/review-snippet", + "standalone": false, "specialRules": [], "supportedTypes": [ "Review" diff --git a/resources/google/structured-data/SpeakableSpecification.json b/resources/google/structured-data/SpeakableSpecification.json index f8c4ad1e..998357e0 100644 --- a/resources/google/structured-data/SpeakableSpecification.json +++ b/resources/google/structured-data/SpeakableSpecification.json @@ -1,6 +1,7 @@ { "name": "SpeakableSpecification", "documentation": "https://developers.google.com/search/docs/appearance/structured-data/speakable", + "standalone": false, "specialRules": [ "google.speakable.cssselector_or_xpath" ], diff --git a/src/Vocabularies/Generated/Google/AggregateRating.php b/src/Vocabularies/Generated/Google/AggregateRating.php index 108ea8c4..f7b096c8 100644 --- a/src/Vocabularies/Generated/Google/AggregateRating.php +++ b/src/Vocabularies/Generated/Google/AggregateRating.php @@ -16,6 +16,9 @@ final class AggregateRating public const SUPPORTED_TYPES = ['AggregateRating']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/review-snippet'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = false; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'itemReviewed' => [ 'name' => 'itemReviewed', diff --git a/src/Vocabularies/Generated/Google/Answer.php b/src/Vocabularies/Generated/Google/Answer.php index aeb6845c..8fa2e818 100644 --- a/src/Vocabularies/Generated/Google/Answer.php +++ b/src/Vocabularies/Generated/Google/Answer.php @@ -16,6 +16,9 @@ final class Answer public const SUPPORTED_TYPES = ['Answer']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/qapage#answer'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = false; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'text' => [ 'name' => 'text', diff --git a/src/Vocabularies/Generated/Google/Article.php b/src/Vocabularies/Generated/Google/Article.php index 9ce2ffa0..a258da49 100644 --- a/src/Vocabularies/Generated/Google/Article.php +++ b/src/Vocabularies/Generated/Google/Article.php @@ -16,6 +16,9 @@ final class Article public const SUPPORTED_TYPES = ['Article', 'NewsArticle', 'BlogPosting']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/article#article-objects'; public const SPECIAL_RULE_KEYS = ['google.article.author_url_or_sameas']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'author' => [ 'name' => 'author', diff --git a/src/Vocabularies/Generated/Google/BlogPosting.php b/src/Vocabularies/Generated/Google/BlogPosting.php index f1353f9e..fbd5849d 100644 --- a/src/Vocabularies/Generated/Google/BlogPosting.php +++ b/src/Vocabularies/Generated/Google/BlogPosting.php @@ -16,6 +16,9 @@ final class BlogPosting public const SUPPORTED_TYPES = ['Article', 'NewsArticle', 'BlogPosting']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/article#article-objects'; public const SPECIAL_RULE_KEYS = ['google.article.author_url_or_sameas']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'author' => [ 'name' => 'author', diff --git a/src/Vocabularies/Generated/Google/BookEdition.php b/src/Vocabularies/Generated/Google/BookEdition.php index 1d181f08..8ded1858 100644 --- a/src/Vocabularies/Generated/Google/BookEdition.php +++ b/src/Vocabularies/Generated/Google/BookEdition.php @@ -16,6 +16,9 @@ final class BookEdition extends Book public const SUPPORTED_TYPES = ['Book']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/book#book-edition'; public const SPECIAL_RULE_KEYS = ['google.book.offer_pricing_by_category']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ '@id' => [ 'name' => '@id', diff --git a/src/Vocabularies/Generated/Google/BookWork.php b/src/Vocabularies/Generated/Google/BookWork.php index 9b2b34c2..e9b67ef9 100644 --- a/src/Vocabularies/Generated/Google/BookWork.php +++ b/src/Vocabularies/Generated/Google/BookWork.php @@ -16,6 +16,9 @@ final class BookWork extends Book public const SUPPORTED_TYPES = ['Book']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/book#book-work'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ '@id' => [ 'name' => '@id', diff --git a/src/Vocabularies/Generated/Google/BreadcrumbList.php b/src/Vocabularies/Generated/Google/BreadcrumbList.php index 0261fd99..fe67a0d3 100644 --- a/src/Vocabularies/Generated/Google/BreadcrumbList.php +++ b/src/Vocabularies/Generated/Google/BreadcrumbList.php @@ -16,6 +16,9 @@ final class BreadcrumbList public const SUPPORTED_TYPES = ['BreadcrumbList']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/breadcrumb#json-ld'; public const SPECIAL_RULE_KEYS = ['google.breadcrumb.last_item_optional']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'itemListElement' => [ 'name' => 'itemListElement', diff --git a/src/Vocabularies/Generated/Google/ClaimReview.php b/src/Vocabularies/Generated/Google/ClaimReview.php index 3f55381c..3b085a1f 100644 --- a/src/Vocabularies/Generated/Google/ClaimReview.php +++ b/src/Vocabularies/Generated/Google/ClaimReview.php @@ -16,6 +16,9 @@ final class ClaimReview public const SUPPORTED_TYPES = ['ClaimReview']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/factcheck'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'claimReviewed' => [ 'name' => 'claimReviewed', diff --git a/src/Vocabularies/Generated/Google/Comment.php b/src/Vocabularies/Generated/Google/Comment.php index 2ac6bf6e..cf2b423a 100644 --- a/src/Vocabularies/Generated/Google/Comment.php +++ b/src/Vocabularies/Generated/Google/Comment.php @@ -16,6 +16,9 @@ final class Comment public const SUPPORTED_TYPES = ['Comment']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/qapage#comment'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = false; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'text' => [ 'name' => 'text', diff --git a/src/Vocabularies/Generated/Google/Course.php b/src/Vocabularies/Generated/Google/Course.php index 3478c2d9..2cd5ea4f 100644 --- a/src/Vocabularies/Generated/Google/Course.php +++ b/src/Vocabularies/Generated/Google/Course.php @@ -16,6 +16,9 @@ final class Course public const SUPPORTED_TYPES = ['Course']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/course'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/DataFeed.php b/src/Vocabularies/Generated/Google/DataFeed.php index aa7da36e..7d1b6912 100644 --- a/src/Vocabularies/Generated/Google/DataFeed.php +++ b/src/Vocabularies/Generated/Google/DataFeed.php @@ -16,6 +16,9 @@ final class DataFeed public const SUPPORTED_TYPES = ['DataFeed']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/book#datafeed-entity'; public const SPECIAL_RULE_KEYS = ['google.book.offer_pricing_by_category']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'dataFeedElement' => [ 'name' => 'dataFeedElement', diff --git a/src/Vocabularies/Generated/Google/Dataset.php b/src/Vocabularies/Generated/Google/Dataset.php index 267802ce..83e99316 100644 --- a/src/Vocabularies/Generated/Google/Dataset.php +++ b/src/Vocabularies/Generated/Google/Dataset.php @@ -16,6 +16,9 @@ final class Dataset public const SUPPORTED_TYPES = ['Dataset']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/dataset'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'description' => [ 'name' => 'description', diff --git a/src/Vocabularies/Generated/Google/DiscussionForumPosting.php b/src/Vocabularies/Generated/Google/DiscussionForumPosting.php index 0daeee69..d73a7385 100644 --- a/src/Vocabularies/Generated/Google/DiscussionForumPosting.php +++ b/src/Vocabularies/Generated/Google/DiscussionForumPosting.php @@ -16,6 +16,9 @@ final class DiscussionForumPosting public const SUPPORTED_TYPES = ['DiscussionForumPosting', 'SocialMediaPosting']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/discussion-forum'; public const SPECIAL_RULE_KEYS = ['google.discussion_forum.content_or_url']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'author' => [ 'name' => 'author', diff --git a/src/Vocabularies/Generated/Google/EmployerAggregateRating.php b/src/Vocabularies/Generated/Google/EmployerAggregateRating.php index 18dff5f3..a980d7c5 100644 --- a/src/Vocabularies/Generated/Google/EmployerAggregateRating.php +++ b/src/Vocabularies/Generated/Google/EmployerAggregateRating.php @@ -16,6 +16,9 @@ final class EmployerAggregateRating public const SUPPORTED_TYPES = ['EmployerAggregateRating']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/employer-rating'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'itemReviewed' => [ 'name' => 'itemReviewed', diff --git a/src/Vocabularies/Generated/Google/Event.php b/src/Vocabularies/Generated/Google/Event.php index 85b8f312..4ac68b47 100644 --- a/src/Vocabularies/Generated/Google/Event.php +++ b/src/Vocabularies/Generated/Google/Event.php @@ -16,6 +16,9 @@ final class Event public const SUPPORTED_TYPES = ['Event']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/event'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = ['CourseInstance', 'DeliveryEvent', 'PublicationEvent', 'UserInteraction']; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/FAQPage.php b/src/Vocabularies/Generated/Google/FAQPage.php index ea86eb69..9f344867 100644 --- a/src/Vocabularies/Generated/Google/FAQPage.php +++ b/src/Vocabularies/Generated/Google/FAQPage.php @@ -16,6 +16,9 @@ final class FAQPage public const SUPPORTED_TYPES = ['FAQPage']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/faqpage'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'mainEntity' => [ 'name' => 'mainEntity', diff --git a/src/Vocabularies/Generated/Google/ImageObject.php b/src/Vocabularies/Generated/Google/ImageObject.php index 6bfbe2a2..cca32e2a 100644 --- a/src/Vocabularies/Generated/Google/ImageObject.php +++ b/src/Vocabularies/Generated/Google/ImageObject.php @@ -16,6 +16,9 @@ final class ImageObject public const SUPPORTED_TYPES = ['ImageObject']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/image-license-metadata'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = false; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'contentUrl' => [ 'name' => 'contentUrl', diff --git a/src/Vocabularies/Generated/Google/ItemList.php b/src/Vocabularies/Generated/Google/ItemList.php index df20607b..9b9c57b4 100644 --- a/src/Vocabularies/Generated/Google/ItemList.php +++ b/src/Vocabularies/Generated/Google/ItemList.php @@ -16,6 +16,9 @@ final class ItemList public const SUPPORTED_TYPES = ['ItemList']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/carousel'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = false; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'itemListElement' => [ 'name' => 'itemListElement', diff --git a/src/Vocabularies/Generated/Google/JobPosting.php b/src/Vocabularies/Generated/Google/JobPosting.php index d0605fc7..3078337e 100644 --- a/src/Vocabularies/Generated/Google/JobPosting.php +++ b/src/Vocabularies/Generated/Google/JobPosting.php @@ -16,6 +16,9 @@ final class JobPosting public const SUPPORTED_TYPES = ['JobPosting']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/job-posting'; public const SPECIAL_RULE_KEYS = ['google.job_posting.remote_job_location_requirements', 'google.job_posting.experience_in_place_of_education']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'title' => [ 'name' => 'title', diff --git a/src/Vocabularies/Generated/Google/Library.php b/src/Vocabularies/Generated/Google/Library.php index cfd5e868..7e703357 100644 --- a/src/Vocabularies/Generated/Google/Library.php +++ b/src/Vocabularies/Generated/Google/Library.php @@ -16,6 +16,9 @@ final class Library public const SUPPORTED_TYPES = ['Library']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/book#library-member'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ '@id' => [ 'name' => '@id', diff --git a/src/Vocabularies/Generated/Google/LibrarySystem.php b/src/Vocabularies/Generated/Google/LibrarySystem.php index 27671a6e..151bb230 100644 --- a/src/Vocabularies/Generated/Google/LibrarySystem.php +++ b/src/Vocabularies/Generated/Google/LibrarySystem.php @@ -16,6 +16,9 @@ final class LibrarySystem public const SUPPORTED_TYPES = ['LibrarySystem']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/book#librarysystem'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ '@id' => [ 'name' => '@id', diff --git a/src/Vocabularies/Generated/Google/LocalBusiness.php b/src/Vocabularies/Generated/Google/LocalBusiness.php index 3068144d..ff28b0eb 100644 --- a/src/Vocabularies/Generated/Google/LocalBusiness.php +++ b/src/Vocabularies/Generated/Google/LocalBusiness.php @@ -16,6 +16,9 @@ final class LocalBusiness public const SUPPORTED_TYPES = ['LocalBusiness']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/local-business'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'address' => [ 'name' => 'address', diff --git a/src/Vocabularies/Generated/Google/MathSolver.php b/src/Vocabularies/Generated/Google/MathSolver.php index c3ea93a1..939eb2d9 100644 --- a/src/Vocabularies/Generated/Google/MathSolver.php +++ b/src/Vocabularies/Generated/Google/MathSolver.php @@ -16,6 +16,9 @@ final class MathSolver public const SUPPORTED_TYPES = ['MathSolver']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/math-solvers'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/MobileApplication.php b/src/Vocabularies/Generated/Google/MobileApplication.php index e7a6785d..3f43c528 100644 --- a/src/Vocabularies/Generated/Google/MobileApplication.php +++ b/src/Vocabularies/Generated/Google/MobileApplication.php @@ -16,6 +16,9 @@ final class MobileApplication public const SUPPORTED_TYPES = ['MobileApplication']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/software-app'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/Movie.php b/src/Vocabularies/Generated/Google/Movie.php index e3ec0736..357ccce3 100644 --- a/src/Vocabularies/Generated/Google/Movie.php +++ b/src/Vocabularies/Generated/Google/Movie.php @@ -16,6 +16,9 @@ final class Movie public const SUPPORTED_TYPES = ['Movie']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/movie'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'image' => [ 'name' => 'image', diff --git a/src/Vocabularies/Generated/Google/NewsArticle.php b/src/Vocabularies/Generated/Google/NewsArticle.php index cb176755..7eee4807 100644 --- a/src/Vocabularies/Generated/Google/NewsArticle.php +++ b/src/Vocabularies/Generated/Google/NewsArticle.php @@ -16,6 +16,9 @@ final class NewsArticle public const SUPPORTED_TYPES = ['Article', 'NewsArticle', 'BlogPosting']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/article#article-objects'; public const SPECIAL_RULE_KEYS = ['google.article.author_url_or_sameas']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'author' => [ 'name' => 'author', diff --git a/src/Vocabularies/Generated/Google/OnlineStore.php b/src/Vocabularies/Generated/Google/OnlineStore.php index 68d81d72..7294c8bd 100644 --- a/src/Vocabularies/Generated/Google/OnlineStore.php +++ b/src/Vocabularies/Generated/Google/OnlineStore.php @@ -16,6 +16,9 @@ final class OnlineStore public const SUPPORTED_TYPES = ['Organization', 'OnlineStore']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/organization'; public const SPECIAL_RULE_KEYS = ['google.organization.return_policy', 'google.organization.tax_id_country_consistency', 'google.organization.member_tier_loyalty_points']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'address' => [ 'name' => 'address', diff --git a/src/Vocabularies/Generated/Google/Organization.php b/src/Vocabularies/Generated/Google/Organization.php index 8735358f..8bf42554 100644 --- a/src/Vocabularies/Generated/Google/Organization.php +++ b/src/Vocabularies/Generated/Google/Organization.php @@ -16,6 +16,9 @@ final class Organization public const SUPPORTED_TYPES = ['Organization', 'OnlineStore']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/organization'; public const SPECIAL_RULE_KEYS = ['google.organization.return_policy', 'google.organization.tax_id_country_consistency', 'google.organization.member_tier_loyalty_points']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'address' => [ 'name' => 'address', diff --git a/src/Vocabularies/Generated/Google/ProductGroup.php b/src/Vocabularies/Generated/Google/ProductGroup.php index c5a73689..e53f4e13 100644 --- a/src/Vocabularies/Generated/Google/ProductGroup.php +++ b/src/Vocabularies/Generated/Google/ProductGroup.php @@ -16,6 +16,9 @@ final class ProductGroup public const SUPPORTED_TYPES = ['ProductGroup']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/product-variants'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/ProductMerchantListing.php b/src/Vocabularies/Generated/Google/ProductMerchantListing.php index e04b2937..56365320 100644 --- a/src/Vocabularies/Generated/Google/ProductMerchantListing.php +++ b/src/Vocabularies/Generated/Google/ProductMerchantListing.php @@ -16,6 +16,9 @@ final class ProductMerchantListing extends Product public const SUPPORTED_TYPES = ['Product']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/merchant-listing'; public const SPECIAL_RULE_KEYS = ['google.product.merchant_listing_price_positive', 'google.product.merchant_listing_price_currency', 'google.product.merchant_listing_return_policy']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/ProductSnippet.php b/src/Vocabularies/Generated/Google/ProductSnippet.php index 994ba8c1..0632a0a5 100644 --- a/src/Vocabularies/Generated/Google/ProductSnippet.php +++ b/src/Vocabularies/Generated/Google/ProductSnippet.php @@ -16,6 +16,9 @@ final class ProductSnippet extends Product public const SUPPORTED_TYPES = ['Product']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/product-snippet'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/ProfilePage.php b/src/Vocabularies/Generated/Google/ProfilePage.php index 9b3b4510..6c64be12 100644 --- a/src/Vocabularies/Generated/Google/ProfilePage.php +++ b/src/Vocabularies/Generated/Google/ProfilePage.php @@ -16,6 +16,9 @@ final class ProfilePage public const SUPPORTED_TYPES = ['ProfilePage']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/profile-page'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'mainEntity' => [ 'name' => 'mainEntity', diff --git a/src/Vocabularies/Generated/Google/QAPage.php b/src/Vocabularies/Generated/Google/QAPage.php index e16f9402..6ad524e5 100644 --- a/src/Vocabularies/Generated/Google/QAPage.php +++ b/src/Vocabularies/Generated/Google/QAPage.php @@ -16,6 +16,9 @@ final class QAPage public const SUPPORTED_TYPES = ['QAPage']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/qapage'; public const SPECIAL_RULE_KEYS = ['google.qapage.answer_comment_count_consistency']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'mainEntity' => [ 'name' => 'mainEntity', diff --git a/src/Vocabularies/Generated/Google/Question.php b/src/Vocabularies/Generated/Google/Question.php index 8da43559..0d5da17e 100644 --- a/src/Vocabularies/Generated/Google/Question.php +++ b/src/Vocabularies/Generated/Google/Question.php @@ -16,6 +16,9 @@ final class Question public const SUPPORTED_TYPES = ['Question']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/qapage#question'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = false; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'answerCount' => [ 'name' => 'answerCount', diff --git a/src/Vocabularies/Generated/Google/Quiz.php b/src/Vocabularies/Generated/Google/Quiz.php index 491f0b36..eb9a8852 100644 --- a/src/Vocabularies/Generated/Google/Quiz.php +++ b/src/Vocabularies/Generated/Google/Quiz.php @@ -16,6 +16,9 @@ final class Quiz public const SUPPORTED_TYPES = ['Quiz']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/education-qa'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'hasPart' => [ 'name' => 'hasPart', diff --git a/src/Vocabularies/Generated/Google/Recipe.php b/src/Vocabularies/Generated/Google/Recipe.php index cfda6746..ba31813d 100644 --- a/src/Vocabularies/Generated/Google/Recipe.php +++ b/src/Vocabularies/Generated/Google/Recipe.php @@ -16,6 +16,9 @@ final class Recipe public const SUPPORTED_TYPES = ['Recipe']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/recipe'; public const SPECIAL_RULE_KEYS = ['google.recipe.calories_requires_yield']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/Review.php b/src/Vocabularies/Generated/Google/Review.php index 34db9178..754188b3 100644 --- a/src/Vocabularies/Generated/Google/Review.php +++ b/src/Vocabularies/Generated/Google/Review.php @@ -16,6 +16,9 @@ final class Review public const SUPPORTED_TYPES = ['Review']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/review-snippet'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = false; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'author' => [ 'name' => 'author', diff --git a/src/Vocabularies/Generated/Google/SocialMediaPosting.php b/src/Vocabularies/Generated/Google/SocialMediaPosting.php index 553fc3d1..ecfb9adf 100644 --- a/src/Vocabularies/Generated/Google/SocialMediaPosting.php +++ b/src/Vocabularies/Generated/Google/SocialMediaPosting.php @@ -16,6 +16,9 @@ final class SocialMediaPosting public const SUPPORTED_TYPES = ['DiscussionForumPosting', 'SocialMediaPosting']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/discussion-forum'; public const SPECIAL_RULE_KEYS = ['google.discussion_forum.content_or_url']; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'author' => [ 'name' => 'author', diff --git a/src/Vocabularies/Generated/Google/SoftwareApplication.php b/src/Vocabularies/Generated/Google/SoftwareApplication.php index a40f3e5b..8510b230 100644 --- a/src/Vocabularies/Generated/Google/SoftwareApplication.php +++ b/src/Vocabularies/Generated/Google/SoftwareApplication.php @@ -16,6 +16,9 @@ final class SoftwareApplication public const SUPPORTED_TYPES = ['SoftwareApplication']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/software-app'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/SpeakableSpecification.php b/src/Vocabularies/Generated/Google/SpeakableSpecification.php index 082e0754..66bdf7e8 100644 --- a/src/Vocabularies/Generated/Google/SpeakableSpecification.php +++ b/src/Vocabularies/Generated/Google/SpeakableSpecification.php @@ -16,6 +16,9 @@ final class SpeakableSpecification public const SUPPORTED_TYPES = ['SpeakableSpecification']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/speakable'; public const SPECIAL_RULE_KEYS = ['google.speakable.cssselector_or_xpath']; + public const STANDALONE = false; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'cssSelector' => [ 'name' => 'cssSelector', diff --git a/src/Vocabularies/Generated/Google/SpecialAnnouncement.php b/src/Vocabularies/Generated/Google/SpecialAnnouncement.php index dc949316..c1679510 100644 --- a/src/Vocabularies/Generated/Google/SpecialAnnouncement.php +++ b/src/Vocabularies/Generated/Google/SpecialAnnouncement.php @@ -16,6 +16,9 @@ final class SpecialAnnouncement public const SUPPORTED_TYPES = ['SpecialAnnouncement']; public const DOCUMENTATION = 'https://schema.org/SpecialAnnouncement'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/VacationRental.php b/src/Vocabularies/Generated/Google/VacationRental.php index 4b558e6a..963d9b41 100644 --- a/src/Vocabularies/Generated/Google/VacationRental.php +++ b/src/Vocabularies/Generated/Google/VacationRental.php @@ -16,6 +16,9 @@ final class VacationRental public const SUPPORTED_TYPES = ['VacationRental']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/vacation-rental'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'containsPlace' => [ 'name' => 'containsPlace', diff --git a/src/Vocabularies/Generated/Google/VideoObject.php b/src/Vocabularies/Generated/Google/VideoObject.php index 271ddd1f..493a7aad 100644 --- a/src/Vocabularies/Generated/Google/VideoObject.php +++ b/src/Vocabularies/Generated/Google/VideoObject.php @@ -16,6 +16,9 @@ final class VideoObject public const SUPPORTED_TYPES = ['VideoObject']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/video'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Generated/Google/WebApplication.php b/src/Vocabularies/Generated/Google/WebApplication.php index 179f33bb..2b593e9b 100644 --- a/src/Vocabularies/Generated/Google/WebApplication.php +++ b/src/Vocabularies/Generated/Google/WebApplication.php @@ -16,6 +16,9 @@ final class WebApplication public const SUPPORTED_TYPES = ['WebApplication']; public const DOCUMENTATION = 'https://developers.google.com/search/docs/appearance/structured-data/software-app'; public const SPECIAL_RULE_KEYS = []; + public const STANDALONE = true; + public const ACCEPTS_SUBTYPES = true; + public const EXCLUDED_SUBTYPES = []; public const PROPERTIES = [ 'name' => [ 'name' => 'name', diff --git a/src/Vocabularies/Validators/Google/Stack.php b/src/Vocabularies/Validators/Google/Stack.php index 84ad480b..0ce24b5a 100644 --- a/src/Vocabularies/Validators/Google/Stack.php +++ b/src/Vocabularies/Validators/Google/Stack.php @@ -14,20 +14,33 @@ use JoliCode\StructuredData\Mapper\MappedProperty; use JoliCode\StructuredData\Mapper\MappedType; use JoliCode\StructuredData\Vocabularies\Generated\GeneratedClassesRegistry; +use JoliCode\StructuredData\Vocabularies\Validators\SchemaOrgTypeHierarchy; /** + * Finds the Google validation rules that apply to the type being validated. + * + * A root type is validated by the class named after it, or after its nearest + * schema.org ancestor when Google documents the subtypes through their parent + * (a BusinessEvent is an Event, a Restaurant a LocalBusiness). A nested type is + * validated by the rules its parent documents for the property it sits in; when + * the parent documents no such property, the nested type starts over as a root + * if Google documents its type as a rich result of its own, as Google does with + * every entity of the page, wherever it is nested. + * * @phpstan-import-type ValidationProperty from ValidationPropertiesNormalizer * @phpstan-import-type ValidationProperties from ValidationPropertiesNormalizer * @phpstan-import-type TargetBlock from ValidationPropertiesNormalizer + * + * @phpstan-type Resolution array{class: ?string, standalone: bool, validationType: ValidationProperty|TargetBlock|null} */ class Stack { public const BASE_NAMESPACE = 'JoliCode\\StructuredData\\Vocabularies\\Generated\\Google'; - private ?string $resolvedValidationTypeCacheKey = null; + private ?string $resolutionCacheKey = null; - /** @var ValidationProperty|TargetBlock|null */ - private ?array $resolvedValidationTypeCache = null; + /** @var Resolution|null */ + private ?array $resolutionCache = null; public function __construct( private ?MappedType $currentType = null, @@ -65,9 +78,18 @@ public function newProperty(MappedProperty $property): self return $this; } + /** + * The validation class whose rules apply to the current type: the one of the + * root, or the one the current type (or one of its ancestors in the document) + * started over with. + */ public function getValidationClass(): ?string { - return $this->validationClass; + if (null === $this->currentType || null === $this->currentType->getParentProperty()) { + return $this->validationClass; + } + + return $this->resolve()['class']; } /** @@ -80,17 +102,13 @@ public function getValidationClass(): ?string */ public function getTypeValidationProperties(): ?array { - $currentType = $this->getCurrentType(); + $resolution = $this->resolve(); - if (!$currentType->getParentProperty()) { - if (null === $this->validationClass) { - return null; - } - - return $this->validationClass::PROPERTIES; + if ($resolution['standalone']) { + return null === $resolution['class'] ? null : $resolution['class']::PROPERTIES; } - $validationType = $this->resolveValidationType(); + $validationType = $resolution['validationType']; // Data Types are handled when we validate properties if (!$validationType || $this->isADataType($validationType)) { @@ -113,17 +131,13 @@ public function getTypeValidationProperties(): ?array */ public function getNextValidationProperty(string $propertyKey): ?array { - $currentType = $this->getCurrentType(); + $resolution = $this->resolve(); - if (!$currentType->getParentProperty()) { - if (null === $this->validationClass) { - return null; - } - - return $this->validationClass::PROPERTIES[$propertyKey] ?? null; + if ($resolution['standalone']) { + return null === $resolution['class'] ? null : ($resolution['class']::PROPERTIES[$propertyKey] ?? null); } - $validationType = $this->resolveValidationType(); + $validationType = $resolution['validationType']; if (!isset($validationType['properties'])) { return null; @@ -132,90 +146,167 @@ public function getNextValidationProperty(string $propertyKey): ?array return ValidationPropertiesNormalizer::nestedProperties($validationType)[$propertyKey] ?? null; } - private function initialize(MappedType $type): self + /** + * Whether the rules of a validation class apply to the given subtype of the + * type it is named after. + */ + public static function acceptsSubtype(string $validationClass, string $typeLabel): bool { - $this->resetResolutionCache(); - $typeLabel = $type->getType(); - - if (!\is_string($typeLabel)) { - $this->validationClass = null; - - return $this; + if (\defined($validationClass . '::ACCEPTS_SUBTYPES') && !$validationClass::ACCEPTS_SUBTYPES) { + return false; } - $validationClass = \sprintf('%s\\%s', self::BASE_NAMESPACE, $typeLabel); - - if (!GeneratedClassesRegistry::has($validationClass)) { - $this->validationClass = null; - - return $this; + if (\defined($validationClass . '::EXCLUDED_SUBTYPES') && SchemaOrgTypeHierarchy::isA($typeLabel, $validationClass::EXCLUDED_SUBTYPES)) { + return false; } - if (\defined($validationClass . '::CHILDREN')) { - $this->validationClass = $this->resolveChildValidationClass($type, $validationClass); - - return $this; - } + return true; + } - $this->validationClass = \defined($validationClass . '::PROPERTIES') ? $validationClass : null; + private function initialize(MappedType $type): self + { + $this->resetResolutionCache(); + $this->validationClass = $this->resolveValidationClassFor($type); return $this; } /** - * Build the currently inspected validation type by walking up the parent chain and handling special properties. + * Resolves the rules of the current type by walking down from the root: at each + * property of the path, the definition the parent documents for it, or, when + * there is none, a fresh start from the class of the nested type. * - * @return ValidationProperty|TargetBlock|null + * @return Resolution */ - private function resolveValidationType(): ?array + private function resolve(): array { - if (null === $this->validationClass) { - return null; + $currentType = $this->getCurrentType(); + + if (null === $currentType->getParentProperty()) { + return ['class' => $this->validationClass, 'standalone' => true, 'validationType' => null]; } $cacheKey = $this->getResolutionCacheKey(); - if ($cacheKey === $this->resolvedValidationTypeCacheKey) { - return $this->resolvedValidationTypeCache; + if ($cacheKey === $this->resolutionCacheKey && null !== $this->resolutionCache) { + return $this->resolutionCache; } - $path = $this->buildPathToCurrentType(); - - $validationProperties = $this->validationClass::PROPERTIES; + $class = $this->validationClass; + $definitions = null === $class ? null : $class::PROPERTIES; + $standalone = false; $validationType = null; - foreach ($path as $segment) { - $searchedKey = $segment['propertyKey']; - $type = $segment['type']; - - $validationProperties = ValidationPropertiesNormalizer::normalizeProperties($validationProperties); - - $validationType = $validationProperties[$searchedKey] ?? null; + foreach ($this->buildPathToCurrentType() as $segment) { + $validationType = null === $definitions + ? null + : (ValidationPropertiesNormalizer::normalizeProperties($definitions)[$segment['propertyKey']] ?? null); if (null === $validationType) { - $this->resolvedValidationTypeCacheKey = $cacheKey; - $this->resolvedValidationTypeCache = null; + // The parent documents nothing for this property (or is not documented + // itself): Google still treats the nested entity as a rich result of its + // own when it documents its type as one. + $class = $this->resolveStandaloneValidationClassFor($segment['type']); + $standalone = null !== $class; + $definitions = null === $class ? null : $class::PROPERTIES; - return null; + continue; } + $standalone = false; + if ($this->isADataType($validationType)) { - $this->resolvedValidationTypeCacheKey = $cacheKey; - $this->resolvedValidationTypeCache = $validationType; + $definitions = null; - return $validationType; + continue; } - ValidationPropertiesNormalizer::handleSpecialProperties($type, $validationType); + ValidationPropertiesNormalizer::handleSpecialProperties($segment['type'], $validationType); $validationType['properties'] = ValidationPropertiesNormalizer::normalizeProperties($validationType['properties'] ?? []); - $validationProperties = $validationType['properties']; + $definitions = $validationType['properties']; + } + + $this->resolutionCacheKey = $cacheKey; + + return $this->resolutionCache = [ + 'class' => $class, + 'standalone' => $standalone, + 'validationType' => $validationType, + ]; + } + + /** + * The validation class of a type taken on its own: the class named after the + * type or after its nearest schema.org ancestor, narrowed down to the child + * class matching the payload when the class has several. + */ + private function resolveValidationClassFor(MappedType $type): ?string + { + // A multi-typed entry is validated once per type, through single-typed + // clones; the original, still multi-typed, is what the path to a nested + // type goes through, and the first of its types that Google documents + // tells which rules the nested type is reached by. + foreach ((array) $type->getType() as $typeLabel) { + $validationClass = $this->findValidationClass($typeLabel); + + if (null === $validationClass) { + continue; + } + + if (\defined($validationClass . '::CHILDREN')) { + return $this->resolveChildValidationClass($type, $validationClass); + } + + if (\defined($validationClass . '::PROPERTIES')) { + return $validationClass; + } + } + + return null; + } + + /** + * Same as resolveValidationClassFor(), for a type found nested where its + * parent documents nothing: only the types Google reports as rich results of + * their own apply there, not the ones that only exist within another type. + */ + private function resolveStandaloneValidationClassFor(MappedType $type): ?string + { + $validationClass = $this->resolveValidationClassFor($type); + + if (null === $validationClass) { + return null; + } + + if (\defined($validationClass . '::STANDALONE') && !$validationClass::STANDALONE) { + return null; } - $this->resolvedValidationTypeCacheKey = $cacheKey; - $this->resolvedValidationTypeCache = $validationType; + return $validationClass; + } + + /** + * The class named after the type, or after the nearest of its schema.org + * ancestors whose class accepts subtypes, this one not being excluded. + */ + private function findValidationClass(string $typeLabel): ?string + { + foreach (SchemaOrgTypeHierarchy::selfAndAncestors($typeLabel) as $index => $label) { + $validationClass = \sprintf('%s\\%s', self::BASE_NAMESPACE, $label); + + if (!GeneratedClassesRegistry::has($validationClass)) { + continue; + } + + if (0 === $index || self::acceptsSubtype($validationClass, $typeLabel)) { + return $validationClass; + } + + return null; + } - return $validationType; + return null; } /** @@ -320,8 +411,6 @@ private function getCurrentType(): MappedType return $this->currentType; } - // These methods handle the special cases. They will update the "properties" entry by importing new ones into it. - // If multiple types are found on the MappedType, all the potentially needed properties are imported. /** * @param ValidationProperty|TargetBlock $testedType */ @@ -344,7 +433,7 @@ private function getResolutionCacheKey(): string private function resetResolutionCache(): void { - $this->resolvedValidationTypeCacheKey = null; - $this->resolvedValidationTypeCache = null; + $this->resolutionCacheKey = null; + $this->resolutionCache = null; } } diff --git a/src/Vocabularies/Validators/Google/ValidationPropertiesNormalizer.php b/src/Vocabularies/Validators/Google/ValidationPropertiesNormalizer.php index 33fdff58..7712ebdf 100644 --- a/src/Vocabularies/Validators/Google/ValidationPropertiesNormalizer.php +++ b/src/Vocabularies/Validators/Google/ValidationPropertiesNormalizer.php @@ -13,6 +13,7 @@ use JoliCode\StructuredData\Mapper\MappedType; use JoliCode\StructuredData\Vocabularies\Generated\GeneratedClassesRegistry; +use JoliCode\StructuredData\Vocabularies\Validators\SchemaOrgTypeHierarchy; /** * Normalizes the hand-written Google validation property maps: flattens the @@ -139,17 +140,12 @@ private static function setImportedProperties(MappedType $mappedType, array &$va $validationClass = self::getImportedClass($supportedType); - $matchingTypes = array_intersect( - (array) $mappedType->getType(), - $validationClass::SUPPORTED_TYPES, - ); - // A mismatch is not an authoring error of the validation spec: it happens // whenever the audited document nests an unexpected type where the import // is declared (e.g. a Person under Answer.comment, which imports @Comment). // In that case there simply is nothing to import, and the document must // keep being validated - never crash the audit. - if ([] !== $matchingTypes) { + if (self::supportsType($validationClass, $mappedType)) { $validationType['properties'] = array_merge( $validationType['properties'] ?? [], $validationClass::PROPERTIES, @@ -185,6 +181,26 @@ private static function setTargettedProperties(MappedType $mappedType, array &$v } } + /** + * Whether the validation class covers one of the types of the mapped type, + * subtypes included when the class accepts them (an @Event import applies to a + * BusinessEvent). + */ + private static function supportsType(string $validationClass, MappedType $mappedType): bool + { + foreach ((array) $mappedType->getType() as $typeLabel) { + if (\in_array($typeLabel, $validationClass::SUPPORTED_TYPES, true)) { + return true; + } + + if (SchemaOrgTypeHierarchy::isA($typeLabel, $validationClass::SUPPORTED_TYPES) && Stack::acceptsSubtype($validationClass, $typeLabel)) { + return true; + } + } + + return false; + } + private static function getImportedClass(string $importedType): string { $validationClass = str_replace('@', '', $importedType); diff --git a/src/Vocabularies/Validators/SchemaOrgTypeHierarchy.php b/src/Vocabularies/Validators/SchemaOrgTypeHierarchy.php new file mode 100644 index 00000000..68d30cb0 --- /dev/null +++ b/src/Vocabularies/Validators/SchemaOrgTypeHierarchy.php @@ -0,0 +1,96 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace JoliCode\StructuredData\Vocabularies\Validators; + +use JoliCode\StructuredData\Vocabularies\Generated\GeneratedClassesRegistry; + +/** + * The schema.org type hierarchy, as recorded by the generated vocabulary classes. + */ +final class SchemaOrgTypeHierarchy +{ + private const TYPE_NAMESPACE = 'JoliCode\\StructuredData\\Vocabularies\\Generated\\SchemaOrg\\Type'; + + /** @var array> */ + private static array $selfAndAncestorsByType = []; + + /** + * The type itself, then its ancestors, nearest first. Types at the same + * distance come in alphabetical order, so a type with several supertypes + * always resolves the same way. A type the vocabulary does not know has no + * ancestor. + * + * @return list + */ + public static function selfAndAncestors(string $typeLabel): array + { + if (isset(self::$selfAndAncestorsByType[$typeLabel])) { + return self::$selfAndAncestorsByType[$typeLabel]; + } + + $ordered = [$typeLabel]; + $seen = [$typeLabel => true]; + $level = [$typeLabel]; + + while ([] !== $level) { + $nextLevel = []; + + foreach ($level as $label) { + foreach (self::parentsOf($label) as $parent) { + if (!isset($seen[$parent])) { + $seen[$parent] = true; + $nextLevel[] = $parent; + } + } + } + + sort($nextLevel); + array_push($ordered, ...$nextLevel); + $level = $nextLevel; + } + + return self::$selfAndAncestorsByType[$typeLabel] = $ordered; + } + + /** + * Whether the type is, or descends from, one of the given types. + * + * @param list $typeLabels + */ + public static function isA(string $typeLabel, array $typeLabels): bool + { + return [] !== array_intersect(self::selfAndAncestors($typeLabel), $typeLabels); + } + + /** + * @return list + */ + private static function parentsOf(string $typeLabel): array + { + $class = \sprintf('%s\\%sModel', self::TYPE_NAMESPACE, $typeLabel); + + if (!GeneratedClassesRegistry::has($class) || !\defined($class . '::PARENTS')) { + return []; + } + + $parents = []; + + /** @var class-string $parentClass */ + foreach ($class::PARENTS as $parentClass) { + if (\defined($parentClass . '::LABEL') && \is_string($parentClass::LABEL)) { + $parents[] = $parentClass::LABEL; + } + } + + return $parents; + } +} diff --git a/tests/Validation/Google/GoogleValidatorInfrastructureTest.php b/tests/Validation/Google/GoogleValidatorInfrastructureTest.php index a4526025..c356383b 100644 --- a/tests/Validation/Google/GoogleValidatorInfrastructureTest.php +++ b/tests/Validation/Google/GoogleValidatorInfrastructureTest.php @@ -87,6 +87,80 @@ public function testStackResolvesProductSubtypeToMerchantListingWhenMerchantSign ); } + public function testStackResolvesASchemaOrgSubtypeToTheClassOfTheTypeGoogleDocuments(): void + { + $type = new MappedType(sourceFormat: 'json-ld', type: 'BusinessEvent', properties: [ + 'name' => new MappedProperty('name'), + ]); + + $stack = (new Stack())->newType($type); + + $this->assertSame(Stack::BASE_NAMESPACE . '\\Event', $stack->getValidationClass()); + $this->assertArrayHasKey('startDate', $stack->getTypeValidationProperties() ?? []); + } + + public function testStackIgnoresTheSubtypesTheRuleFileExcludes(): void + { + // A CourseInstance is an Event for schema.org, not for Google. + $type = new MappedType(sourceFormat: 'json-ld', type: 'CourseInstance', properties: [ + 'courseMode' => new MappedProperty('courseMode'), + ]); + + $stack = (new Stack())->newType($type); + + $this->assertNull($stack->getValidationClass()); + $this->assertNull($stack->getTypeValidationProperties()); + } + + public function testStackIgnoresEverySubtypeWhenTheRuleFileRefusesThem(): void + { + // A HowToStep is an ItemList for schema.org, not a carousel for Google. + $type = new MappedType(sourceFormat: 'json-ld', type: 'HowToStep', properties: [ + 'text' => new MappedProperty('text'), + ]); + + $stack = (new Stack())->newType($type); + + $this->assertNull($stack->getValidationClass()); + } + + public function testStackValidatesATypeNestedUnderAnUndocumentedPropertyOnItsOwn(): void + { + // Article documents nothing for "about": the event found there is a rich + // result of its own, and so are its documented nested properties. + $article = new MappedType(sourceFormat: 'json-ld', type: 'Article'); + $about = new MappedProperty('about', $article); + $event = new MappedType(sourceFormat: 'json-ld', type: 'BusinessEvent', parent: $article, parentProperty: $about); + $location = new MappedProperty('location', $event); + $place = new MappedType(sourceFormat: 'json-ld', type: 'Place', parent: $event, parentProperty: $location); + + $stack = (new Stack())->newType($article); + $this->assertSame(Stack::BASE_NAMESPACE . '\\Article', $stack->getValidationClass()); + + $stack->newType($event); + $this->assertSame(Stack::BASE_NAMESPACE . '\\Event', $stack->getValidationClass()); + $this->assertArrayHasKey('offers', $stack->getTypeValidationProperties() ?? []); + + $stack->newType($place); + $this->assertSame(Stack::BASE_NAMESPACE . '\\Event', $stack->getValidationClass()); + $this->assertArrayHasKey('address', $stack->getTypeValidationProperties() ?? []); + } + + public function testStackKeepsANestedOnlyTypeOutOfUndocumentedProperties(): void + { + // Google only documents Comment as a part of a discussion forum posting or + // a Q&A page: a comment under an article is not a rich result. + $article = new MappedType(sourceFormat: 'json-ld', type: 'Article'); + $commentProperty = new MappedProperty('comment', $article); + $comment = new MappedType(sourceFormat: 'json-ld', type: 'Comment', parent: $article, parentProperty: $commentProperty); + + $stack = (new Stack())->newType($article); + $stack->newType($comment); + + $this->assertNull($stack->getValidationClass()); + $this->assertNull($stack->getTypeValidationProperties()); + } + public function testAuditSurvivesAnUnexpectedNestedTypeWhereAnImportIsDeclared(): void { // Answer.comment declares supportedTypes ["@Comment"]: the property spec is diff --git a/tests/Validation/SchemaOrgTypeHierarchyTest.php b/tests/Validation/SchemaOrgTypeHierarchyTest.php new file mode 100644 index 00000000..219986d3 --- /dev/null +++ b/tests/Validation/SchemaOrgTypeHierarchyTest.php @@ -0,0 +1,44 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace JoliCode\StructuredData\Tests\Validation; + +use JoliCode\StructuredData\Vocabularies\Validators\SchemaOrgTypeHierarchy; +use PHPUnit\Framework\TestCase; + +class SchemaOrgTypeHierarchyTest extends TestCase +{ + public function testItListsTheTypeThenItsAncestorsNearestFirst(): void + { + $this->assertSame(['BusinessEvent', 'Event', 'Thing'], SchemaOrgTypeHierarchy::selfAndAncestors('BusinessEvent')); + $this->assertSame(['Restaurant', 'FoodEstablishment', 'LocalBusiness', 'Organization', 'Place', 'Thing'], SchemaOrgTypeHierarchy::selfAndAncestors('Restaurant')); + } + + public function testItOrdersTheSupertypesOfTheSameDistanceAlphabetically(): void + { + // LocalBusiness is both an Organization and a Place. + $this->assertSame(['LocalBusiness', 'Organization', 'Place', 'Thing'], SchemaOrgTypeHierarchy::selfAndAncestors('LocalBusiness')); + } + + public function testATypeTheVocabularyDoesNotKnowHasNoAncestor(): void + { + $this->assertSame(['NotASchemaOrgType'], SchemaOrgTypeHierarchy::selfAndAncestors('NotASchemaOrgType')); + } + + public function testIsAMatchesTheTypeItselfAndItsAncestors(): void + { + $this->assertTrue(SchemaOrgTypeHierarchy::isA('Event', ['Event'])); + $this->assertTrue(SchemaOrgTypeHierarchy::isA('BroadcastEvent', ['PublicationEvent'])); + $this->assertTrue(SchemaOrgTypeHierarchy::isA('Restaurant', ['LocalBusiness', 'Event'])); + $this->assertFalse(SchemaOrgTypeHierarchy::isA('Person', ['Organization'])); + $this->assertFalse(SchemaOrgTypeHierarchy::isA('Event', ['BusinessEvent'])); + } +} diff --git a/tests/Validation/fixtures/google-baseline.json b/tests/Validation/fixtures/google-baseline.json index b7029f8a..8a56261e 100644 --- a/tests/Validation/fixtures/google-baseline.json +++ b/tests/Validation/fixtures/google-baseline.json @@ -1,4 +1,14 @@ { + "article-about-event.jsonld": { + "errors": [ + "[Google error] about.location: Missing required property: \"address\" for the type \"Place\"" + ], + "warnings": [ + "[Google warning] about: Missing recommended property: \"offers\" for the type \"BusinessEvent\"", + "[Google warning] about: Missing recommended property: \"organizer\" for the type \"BusinessEvent\"" + ], + "documentIssues": [] + }, "article-author-missing-url-and-sameas.jsonld": { "errors": [], "warnings": [ @@ -11,6 +21,11 @@ "warnings": [], "documentIssues": [] }, + "article-comments-not-promoted.jsonld": { + "errors": [], + "warnings": [], + "documentIssues": [] + }, "article-image-object-missing-url.jsonld": { "errors": [], "warnings": [ @@ -154,7 +169,14 @@ }, "course-info.jsonld": { "errors": [], - "warnings": [], + "warnings": [ + "[Google warning] video: Missing recommended property: at least one of the following properties should be present \"creator, author\"", + "[Google warning] video: Missing recommended property: \"duration\" for the type \"VideoObject\"", + "[Google warning] video: Missing recommended property: \"embedUrl\" for the type \"VideoObject\"", + "[Google warning] video: Missing recommended property: \"expires\" for the type \"VideoObject\"", + "[Google warning] video: Missing recommended property: \"regionsAllowed\" for the type \"VideoObject\"", + "[Google warning] video: Missing recommended property: \"ineligibleRegion\" for the type \"VideoObject\"" + ], "documentIssues": [] }, "course-missing-provider.jsonld": { @@ -255,6 +277,16 @@ ], "documentIssues": [] }, + "event-subtype.jsonld": { + "errors": [ + "[Google error] location: Missing required property: \"address\" for the type \"Place\"" + ], + "warnings": [ + "[Google warning] BusinessEvent: Missing recommended property: \"offers\" for the type \"BusinessEvent\"", + "[Google warning] BusinessEvent: Missing recommended property: \"organizer\" for the type \"BusinessEvent\"" + ], + "documentIssues": [] + }, "event.jsonld": { "errors": [], "warnings": [], @@ -289,6 +321,11 @@ "warnings": [], "documentIssues": [] }, + "howto-steps-not-carousel.jsonld": { + "errors": [], + "warnings": [], + "documentIssues": [] + }, "image-license-metadata-missing-required.jsonld": { "errors": [ "[Google error] ImageObject: Missing required property: at least one of the following properties must be present \"creator, creditText, copyrightNotice, license\" for the type \"ImageObject\"" diff --git a/tests/Validation/fixtures/google/article-about-event.jsonld b/tests/Validation/fixtures/google/article-about-event.jsonld new file mode 100644 index 00000000..4e3c46f7 --- /dev/null +++ b/tests/Validation/fixtures/google/article-about-event.jsonld @@ -0,0 +1,35 @@ +{ + "@context": "https://schema.org", + "@type": "Article", + "headline": "Our take on SymfonyLive Paris 2023", + "image": ["https://example.com/social-preview/symfonylive-2023.png"], + "datePublished": "2023-03-27", + "dateModified": "2023-03-27", + "author": { + "@type": "Person", + "name": "Loïck Piera", + "url": "https://example.com/team/loick-piera" + }, + "about": { + "@type": "BusinessEvent", + "name": "SymfonyLive Paris", + "startDate": "2023-03-23", + "endDate": "2023-03-24", + "description": "Two days of talks about the Symfony framework.", + "image": "https://example.com/events/symfonylive-2023.jpg", + "eventStatus": "https://schema.org/EventScheduled", + "location": { + "@type": "Place", + "name": "Paris" + }, + "performer": { + "@type": "Person", + "name": "Bastien Jaillot" + }, + "attendee": { + "@type": "Organization", + "name": "JoliCode", + "url": "https://example.com/" + } + } +} diff --git a/tests/Validation/fixtures/google/article-comments-not-promoted.jsonld b/tests/Validation/fixtures/google/article-comments-not-promoted.jsonld new file mode 100644 index 00000000..584c915f --- /dev/null +++ b/tests/Validation/fixtures/google/article-comments-not-promoted.jsonld @@ -0,0 +1,27 @@ +{ + "@context": "https://schema.org", + "@type": "BlogPosting", + "headline": "A post with comments", + "image": ["https://example.com/posts/comments.png"], + "datePublished": "2024-05-02", + "dateModified": "2024-05-03", + "author": { + "@type": "Person", + "name": "Jane Doe", + "url": "https://example.com/team/jane-doe" + }, + "comment": [ + { + "@type": "Comment", + "text": "Great post!" + }, + { + "@type": "Comment", + "text": "I disagree with the second part.", + "author": { + "@type": "Person", + "name": "John" + } + } + ] +} diff --git a/tests/Validation/fixtures/google/event-subtype.jsonld b/tests/Validation/fixtures/google/event-subtype.jsonld new file mode 100644 index 00000000..fd93ffdc --- /dev/null +++ b/tests/Validation/fixtures/google/event-subtype.jsonld @@ -0,0 +1,18 @@ +{ + "@context": "https://schema.org", + "@type": "BusinessEvent", + "name": "SymfonyLive Paris", + "startDate": "2023-03-23", + "endDate": "2023-03-24", + "description": "Two days of talks about the Symfony framework.", + "image": "https://example.com/events/symfonylive-2023.jpg", + "eventStatus": "https://schema.org/EventScheduled", + "location": { + "@type": "Place", + "name": "Paris" + }, + "performer": { + "@type": "Person", + "name": "Bastien Jaillot" + } +} diff --git a/tests/Validation/fixtures/google/howto-steps-not-carousel.jsonld b/tests/Validation/fixtures/google/howto-steps-not-carousel.jsonld new file mode 100644 index 00000000..9c9802a1 --- /dev/null +++ b/tests/Validation/fixtures/google/howto-steps-not-carousel.jsonld @@ -0,0 +1,22 @@ +{ + "@context": "https://schema.org", + "@type": "HowTo", + "name": "How to tie a bow tie", + "step": [ + { + "@type": "HowToStep", + "name": "Drape the tie", + "text": "Drape the tie around your neck, one end longer than the other." + }, + { + "@type": "HowToSection", + "name": "The knot", + "itemListElement": [ + { + "@type": "HowToStep", + "text": "Cross the long end over the short one." + } + ] + } + ] +} From 60b6f78e43b754a0d4c43ec3ad797eee2dd491ed Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:49:32 +0100 Subject: [PATCH 09/11] Stop reporting the missing address sub-properties of an event location --- CHANGELOG.md | 3 +++ resources/google/structured-data/Event.json | 10 +++++----- src/Vocabularies/Generated/Google/Event.php | 10 +++++----- 3 files changed, 13 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0f44d669..3eb03c73 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ ### Fixed +- Google validator: the address sub-properties of an event location (`streetAddress`, + `addressRegion`...) are no longer reported when missing: the documentation only shows + them in an example, and Google does not report them. - Google validator: the schema.org subtypes of a documented type are now validated with its rules, as Google does (a `BusinessEvent` is an `Event`, a `Restaurant` a `LocalBusiness`, a `TechArticle` an `Article`). The rule files can refuse subtypes diff --git a/resources/google/structured-data/Event.json b/resources/google/structured-data/Event.json index c76cd382..51158e0b 100644 --- a/resources/google/structured-data/Event.json +++ b/resources/google/structured-data/Event.json @@ -51,35 +51,35 @@ "properties": { "streetAddress": { "name": "streetAddress", - "severity": "recommended", + "severity": "optional", "supportedTypes": [ "Text" ] }, "addressLocality": { "name": "addressLocality", - "severity": "recommended", + "severity": "optional", "supportedTypes": [ "Text" ] }, "addressRegion": { "name": "addressRegion", - "severity": "recommended", + "severity": "optional", "supportedTypes": [ "Text" ] }, "postalCode": { "name": "postalCode", - "severity": "recommended", + "severity": "optional", "supportedTypes": [ "Text" ] }, "addressCountry": { "name": "addressCountry", - "severity": "recommended", + "severity": "optional", "supportedTypes": [ "Text" ] diff --git a/src/Vocabularies/Generated/Google/Event.php b/src/Vocabularies/Generated/Google/Event.php index 4ac68b47..bc596567 100644 --- a/src/Vocabularies/Generated/Google/Event.php +++ b/src/Vocabularies/Generated/Google/Event.php @@ -64,35 +64,35 @@ final class Event 'properties' => [ 'streetAddress' => [ 'name' => 'streetAddress', - 'severity' => 'recommended', + 'severity' => 'optional', 'supportedTypes' => [ 'Text', ], ], 'addressLocality' => [ 'name' => 'addressLocality', - 'severity' => 'recommended', + 'severity' => 'optional', 'supportedTypes' => [ 'Text', ], ], 'addressRegion' => [ 'name' => 'addressRegion', - 'severity' => 'recommended', + 'severity' => 'optional', 'supportedTypes' => [ 'Text', ], ], 'postalCode' => [ 'name' => 'postalCode', - 'severity' => 'recommended', + 'severity' => 'optional', 'supportedTypes' => [ 'Text', ], ], 'addressCountry' => [ 'name' => 'addressCountry', - 'severity' => 'recommended', + 'severity' => 'optional', 'supportedTypes' => [ 'Text', ], From b5929ecc0c81fa43502910667a1f869cbc8c2cb6 Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:49:43 +0100 Subject: [PATCH 10/11] Merge the blocks describing the same node before judging what is missing --- CHANGELOG.md | 5 + README.md | 12 + src/Mapper/MappedError.php | 11 + src/Mapper/MappedErrorTemplate.php | 1 + src/Mapper/MappedProperty.php | 5 + src/Mapper/MappedType.php | 12 + src/Mapper/MappedTypeMerger.php | 352 ++++++++++++++++++ .../ValidationSnippetTemplateApplier.php | 1 + .../ValidationSnippetTemplateBuilder.php | 1 + src/Validator.php | 56 ++- .../Validators/AbstractValidator.php | 3 +- .../Validators/Google/GoogleValidator.php | 14 +- tests/Validation/SharedIdentifierTest.php | 136 +++++++ .../Validation/fixtures/google-baseline.json | 33 ++ ...two-blocks-same-id-conflicting-values.html | 37 ++ .../google/event-two-blocks-same-id.html | 35 ++ 16 files changed, 706 insertions(+), 8 deletions(-) create mode 100644 src/Mapper/MappedTypeMerger.php create mode 100644 tests/Validation/SharedIdentifierTest.php create mode 100644 tests/Validation/fixtures/google/event-two-blocks-same-id-conflicting-values.html create mode 100644 tests/Validation/fixtures/google/event-two-blocks-same-id.html diff --git a/CHANGELOG.md b/CHANGELOG.md index 3eb03c73..9ee43dc4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,11 @@ ### Fixed +- The blocks of a document that share an identifier (a JSON-LD `@id`, a microdata + `itemid`) describe one node for Google, whatever their format, with the union of their + properties. A property one block omits is no longer reported missing when another block + provides it; each block keeps its own diagnostics and positions otherwise. Values the + blocks disagree on are reported as a document warning, since Google keeps them all. - Google validator: the address sub-properties of an event location (`streetAddress`, `addressRegion`...) are no longer reported when missing: the documentation only shows them in an example, and Google does not report them. diff --git a/README.md b/README.md index e20831b2..b8ea4c36 100644 --- a/README.md +++ b/README.md @@ -143,6 +143,18 @@ The validator accepts the following data formats: - microdata - RDFa (schema.org-style RDFa only) +### Blocks describing the same node + +Google reads a page as one graph: the blocks that share an identifier (a JSON-LD `@id`, +a microdata `itemid`) are one node holding the union of their properties, whatever their +format, and a property one block omits is not missing when another block provides it. +The validator does the same. Each block is still audited on its own, with its positions +in the document, but the "missing property" issues that another block resolves are not +reported, and the audit is valid when the merged node is. When the blocks disagree on a +value, Google keeps every value and reports nothing; the disagreement is reported as a +document warning, outside the Google diagnostics. Blank node identifiers are local to +their block and never merge. + ### Using the validator #### Basic usage diff --git a/src/Mapper/MappedError.php b/src/Mapper/MappedError.php index 51363b34..ae45990d 100644 --- a/src/Mapper/MappedError.php +++ b/src/Mapper/MappedError.php @@ -25,6 +25,12 @@ public function __construct( private string $ranges, private MappedType|MappedProperty|null $parent = null, private ?string $documentationLink = null, + /** + * The property (or the alternatives, comma-separated) whose absence this + * error reports, when it reports an absence: such an error can be + * resolved by another block of the document describing the same node. + */ + private ?string $missingProperty = null, ) { } @@ -96,6 +102,11 @@ public function getDocumentationLink(): ?string return $this->documentationLink; } + public function getMissingProperty(): ?string + { + return $this->missingProperty; + } + public function getPath(): string { $parentPath = $this->parent?->getPath(); diff --git a/src/Mapper/MappedErrorTemplate.php b/src/Mapper/MappedErrorTemplate.php index 0a783fcd..b4c5d10e 100644 --- a/src/Mapper/MappedErrorTemplate.php +++ b/src/Mapper/MappedErrorTemplate.php @@ -21,6 +21,7 @@ public function __construct( public string $severity, public ?string $validatorName, public ?string $documentationLink, + public ?string $missingProperty = null, ) { } } diff --git a/src/Mapper/MappedProperty.php b/src/Mapper/MappedProperty.php index d5ca38e8..b31b295c 100644 --- a/src/Mapper/MappedProperty.php +++ b/src/Mapper/MappedProperty.php @@ -151,6 +151,11 @@ public function addError(MappedError $error): void $this->errors[] = $error; } + public function removeError(MappedError $error): void + { + $this->errors = array_values(array_filter($this->errors, static fn (MappedError $candidate): bool => $candidate !== $error)); + } + /** * @return array */ diff --git a/src/Mapper/MappedType.php b/src/Mapper/MappedType.php index 3f17e557..90b1bbad 100644 --- a/src/Mapper/MappedType.php +++ b/src/Mapper/MappedType.php @@ -211,6 +211,12 @@ public function addError(MappedError $error): void } } + public function removeError(MappedError $error): void + { + $this->errors = array_values(array_filter($this->errors, static fn (MappedError $candidate): bool => $candidate !== $error)); + $this->mergedErrors = null; + } + public function addChildrenError(MappedError $error): void { $this->childrenErrors[] = $error; @@ -220,6 +226,12 @@ public function addChildrenError(MappedError $error): void } } + public function removeChildrenError(MappedError $error): void + { + $this->childrenErrors = array_values(array_filter($this->childrenErrors, static fn (MappedError $candidate): bool => $candidate !== $error)); + $this->mergedErrors = null; + } + /** * @return array */ diff --git a/src/Mapper/MappedTypeMerger.php b/src/Mapper/MappedTypeMerger.php new file mode 100644 index 00000000..9cd406a1 --- /dev/null +++ b/src/Mapper/MappedTypeMerger.php @@ -0,0 +1,352 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace JoliCode\StructuredData\Mapper; + +use JoliCode\StructuredData\JsonLd\Algorithms\Http\IriResolver; +use JoliCode\StructuredData\JsonLd\Algorithms\JsonLd\Keyword; + +/** + * Reconciles the structured data blocks of a document that describe the same + * node. + * + * Google reads a page as one graph: the blocks sharing an identifier (a JSON-LD + * "@id", a microdata "itemid") are one node holding the union of their + * properties, whatever their format, and a property one block omits is not + * missing when another block provides it. The blocks are still audited one by + * one, with their positions in the document; the merged node only tells which + * of their "missing property" issues Google would not report. + * + * @phpstan-type Conflict array{key: string, properties: list, values: list} + */ +final class MappedTypeMerger +{ + /** + * Groups the types describing the same node: the ones sharing an absolute + * identifier. Blank node identifiers are local to their block and never + * merge. + * + * @param array $types + * + * @return array> the groups of two types or more, indexed by identifier + */ + public static function groupByIdentifier(array $types): array + { + $groups = []; + + foreach ($types as $type) { + $identifier = $type->getProperty(Keyword::ID->value)?->getValue(); + + if (!\is_string($identifier) || IriResolver::isBlankNodeIdentifier($identifier) || !IriResolver::isAbsoluteIri($identifier)) { + continue; + } + + $groups[$identifier][] = $type; + } + + return array_filter($groups, static fn (array $group): bool => isset($group[1])); + } + + /** + * Builds the node Google sees: a fresh type, free of any error, holding the + * union of the members' types and properties. Equal scalar values are kept + * once, nested nodes are all kept, as in a graph. + * + * @param list $members + * + * @return array{type: MappedType, conflicts: list} + */ + public static function merge(array $members): array + { + $merged = new MappedType(sourceFormat: $members[0]->getSourceFormat(), type: self::unionOfTypes($members)); + + /** @var array> $sources */ + $sources = []; + + foreach ($members as $member) { + foreach ($member->getProperties() as $key => $property) { + $sources[$key][] = $property; + } + } + + $conflicts = []; + + foreach ($sources as $key => $properties) { + $property = new MappedProperty($key, $merged); + $values = []; + $scalars = []; + + foreach ($properties as $source) { + foreach ($source->getKeyRanges() as $range) { + $property->addKeyRange($range); + } + + foreach ($source->getValueRanges() as $range) { + $property->addValueRange($range); + } + + foreach (self::valuesOf($source) as $value) { + if ($value instanceof MappedType) { + $values[] = self::copyType($value, $merged, $property); + + continue; + } + + if (\is_scalar($value)) { + if (\in_array($value, $scalars, true)) { + continue; + } + + $scalars[] = $value; + } + + $values[] = $value; + } + } + + $property->setValue(isset($values[1]) ? $values : ($values[0] ?? null)); + $merged->setProperty($key, $property); + + if (isset($scalars[1]) && '@' !== $key[0]) { + $conflicts[] = ['key' => $key, 'properties' => $properties, 'values' => $scalars]; + } + } + + return ['type' => $merged, 'conflicts' => $conflicts]; + } + + /** + * Withdraws, from the members, the "missing property" issues the merged node + * does not have: another block provides what they report missing. The + * members' validity and severities are recomputed afterwards. + * + * @param list $members + * + * @return list the withdrawn issues + */ + public static function withdrawIssuesResolvedBy(MappedType $merged, array $members): array + { + $remaining = []; + + foreach ($merged->getMergedErrors() as $error) { + if (null !== $error->getMissingProperty()) { + $remaining[self::issueKey($error)] = true; + } + } + + $withdrawn = []; + + foreach ($members as $member) { + foreach ($member->getMergedErrors() as $error) { + if (null === $error->getMissingProperty() || isset($remaining[self::issueKey($error)])) { + continue; + } + + self::withdraw($member, $error); + $withdrawn[] = $error; + } + + self::recompute($member); + } + + return $withdrawn; + } + + /** + * @param list $members + * + * @return string|list|null + */ + private static function unionOfTypes(array $members): string|array|null + { + $labels = []; + + foreach ($members as $member) { + foreach ((array) $member->getType() as $label) { + if (!\in_array($label, $labels, true)) { + $labels[] = $label; + } + } + } + + return match (\count($labels)) { + 0 => null, + 1 => $labels[0], + default => $labels, + }; + } + + /** + * The values of a property, one by one: a multi-valued property is a list, + * a keyword-keyed value (a language map, a list object) is one opaque value. + * + * @return list + */ + private static function valuesOf(MappedProperty $property): array + { + $value = $property->getValue(); + + if (\is_array($value) && array_is_list($value)) { + return $value; + } + + return [$value]; + } + + private static function copyType(MappedType $source, MappedType $parent, MappedProperty $parentProperty): MappedType + { + $copy = new MappedType( + sourceFormat: $source->getSourceFormat(), + type: $source->getType(), + originalType: $source->getOriginalType(), + name: $source->getName(), + parent: $parent, + parentProperty: $parentProperty, + ); + + foreach ($source->getKeyRanges() as $range) { + $copy->addKeyRange($range); + } + + foreach ($source->getValueRanges() as $range) { + $copy->addValueRange($range); + } + + foreach ($source->getProperties() as $key => $property) { + $copy->setProperty($key, self::copyProperty($property, $copy)); + } + + return $copy; + } + + private static function copyProperty(MappedProperty $source, MappedType $owner): MappedProperty + { + $copy = new MappedProperty($source->getKey(), $owner, $source->getOriginalKey()); + + foreach ($source->getKeyRanges() as $range) { + $copy->addKeyRange($range); + } + + foreach ($source->getValueRanges() as $range) { + $copy->addValueRange($range); + } + + $copy->setValue(self::copyValue($source->getValue(), $owner, $copy)); + + return $copy; + } + + private static function copyValue(mixed $value, MappedType $owner, MappedProperty $property): mixed + { + if ($value instanceof MappedType) { + return self::copyType($value, $owner, $property); + } + + if (\is_array($value)) { + $copied = []; + + foreach ($value as $key => $entry) { + $copied[$key] = self::copyValue($entry, $owner, $property); + } + + return $copied; + } + + return $value; + } + + /** + * What makes two "missing property" issues the same across the members and + * the merged node: where in the node they are (relative to the root, whose + * label may differ), what is missing, and how badly. + */ + private static function issueKey(MappedError $error): string + { + $target = $error->getParent(); + $path = $target instanceof MappedType && null === $target->getParentProperty() + ? '' + : ($target?->getPath() ?? ''); + + return $path . '|' . $error->getMissingProperty() . '|' . $error->getSeverity(); + } + + /** + * Removes the error from the whole tree of the type: the error of a + * multi-typed entry is raised on a short-lived clone and copied onto the + * entry, so its own parent cannot be trusted to find where it is held. + */ + private static function withdraw(MappedType $type, MappedError $error): void + { + $type->removeError($error); + $type->removeChildrenError($error); + + foreach ($type->getProperties() as $property) { + $property->removeError($error); + + foreach (self::valuesOf($property) as $value) { + if ($value instanceof MappedType) { + self::withdraw($value, $error); + } + } + } + } + + /** + * Recomputes the validity and severity of a type tree from the errors it + * still holds: a type is valid when it has no error of its own and its + * nested types are valid, and carries the highest severity found on it or + * below it. + */ + private static function recompute(MappedType $type): bool + { + $valid = [] === $type->getErrors(); + + foreach ($type->getProperties() as $property) { + $propertyValid = [] === $property->getErrors(); + $property->setErrorSeverity(self::highestSeverity($property->getErrors())); + + foreach (self::valuesOf($property) as $value) { + if ($value instanceof MappedType && !self::recompute($value)) { + $propertyValid = false; + } + } + + $property->setIsValid($propertyValid); + + if (!$propertyValid) { + $valid = false; + } + } + + $type->setIsValid($valid); + $type->setErrorSeverity(self::highestSeverity($type->getMergedErrors())); + + return $valid; + } + + /** + * @param array $errors + */ + private static function highestSeverity(array $errors): ?string + { + $severity = null; + + foreach ($errors as $error) { + if (MappedError::SEVERITY_ERROR === $error->getSeverity()) { + return MappedError::SEVERITY_ERROR; + } + + $severity = $error->getSeverity(); + } + + return $severity; + } +} diff --git a/src/Mapper/ValidationSnippetTemplateApplier.php b/src/Mapper/ValidationSnippetTemplateApplier.php index 2ed6af5a..ee2a6a0c 100644 --- a/src/Mapper/ValidationSnippetTemplateApplier.php +++ b/src/Mapper/ValidationSnippetTemplateApplier.php @@ -92,6 +92,7 @@ private static function replayMappedError(MappedType|MappedProperty $target, Map ranges: MappedErrorFormatter::formatRanges($target->getValueRanges()), parent: $target, documentationLink: $errorTemplate->documentationLink, + missingProperty: $errorTemplate->missingProperty, ); $target->addError($error); diff --git a/src/Mapper/ValidationSnippetTemplateBuilder.php b/src/Mapper/ValidationSnippetTemplateBuilder.php index 84f44885..19058177 100644 --- a/src/Mapper/ValidationSnippetTemplateBuilder.php +++ b/src/Mapper/ValidationSnippetTemplateBuilder.php @@ -94,6 +94,7 @@ private static function buildErrorTemplates(array $errors): array severity: $error->getSeverity(), validatorName: $error->getValidatorName(), documentationLink: $error->getDocumentationLink(), + missingProperty: $error->getMissingProperty(), ); } diff --git a/src/Validator.php b/src/Validator.php index 160856ac..f51711f4 100644 --- a/src/Validator.php +++ b/src/Validator.php @@ -25,9 +25,12 @@ use JoliCode\StructuredData\JsonLd\Parser\JsonLdParser; use JoliCode\StructuredData\Mapper\DocumentError; use JoliCode\StructuredData\Mapper\DocumentIssueInterface; +use JoliCode\StructuredData\Mapper\DocumentWarning; use JoliCode\StructuredData\Mapper\MappedError; +use JoliCode\StructuredData\Mapper\MappedErrorFormatter; use JoliCode\StructuredData\Mapper\MappedProperty; use JoliCode\StructuredData\Mapper\MappedType; +use JoliCode\StructuredData\Mapper\MappedTypeMerger; use JoliCode\StructuredData\Mapper\ValidationMapper; use JoliCode\StructuredData\Mapper\ValidationSnippetCache; use JoliCode\StructuredData\Mapper\ValidationSnippetTemplateApplier; @@ -238,11 +241,62 @@ public function audit(string $document, bool $reportPendingVocabularyUsage = fal } } - $documentIssues = $this->mapDocumentIssuesToMappedErrors($documentIssues); + $documentIssues = $this->mapDocumentIssuesToMappedErrors([ + ...$documentIssues, + ...$this->reconcileTypesSharingAnIdentifier($types), + ]); return new Audit($types, $documentIssues); } + /** + * Google reads the page as one graph: the blocks sharing an identifier are one + * node, whatever their format, and a property one block omits is not missing + * when another block provides it. Each block keeps its own audit and + * positions; the node Google sees is validated apart, and the "missing + * property" issues it does not have are withdrawn from the blocks. + * + * Google keeps every value when the blocks disagree on one, and reports + * nothing: the disagreement is reported as a document warning, outside the + * Google verdict. + * + * @param array $types + * + * @return list + */ + private function reconcileTypesSharingAnIdentifier(array $types): array + { + $issues = []; + + foreach (MappedTypeMerger::groupByIdentifier($types) as $identifier => $members) { + $merged = MappedTypeMerger::merge($members); + + $this->validateType($merged['type']); + MappedTypeMerger::withdrawIssuesResolvedBy($merged['type'], $members); + + foreach ($merged['conflicts'] as $conflict) { + $ranges = array_map( + static fn (MappedProperty $property): string => MappedErrorFormatter::formatRanges($property->getValueRanges()), + $conflict['properties'], + ); + + $issues[] = new DocumentWarning( + 'Document', + \sprintf( + 'The "%s" of "%s" has a different value in each of the %d blocks describing it (%s): Google merges them and keeps every value.', + $conflict['key'], + $identifier, + \count($conflict['properties']), + implode(', ', array_map(static fn (mixed $value): string => json_encode($value, \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE) ?: '', $conflict['values'])), + ), + implode(', ', array_filter($ranges)), + ); + } + } + + return $issues; + } + /** * @param array $expandedJsonLd * diff --git a/src/Vocabularies/Validators/AbstractValidator.php b/src/Vocabularies/Validators/AbstractValidator.php index 1a96702a..c10a93a8 100644 --- a/src/Vocabularies/Validators/AbstractValidator.php +++ b/src/Vocabularies/Validators/AbstractValidator.php @@ -99,7 +99,7 @@ protected function validatePropertyCasing(MappedType $type, MappedProperty $prop ]; } - protected function addMappedError(MappedType|MappedProperty $target, string $message, MappedType $typeWithError, string $severity, ?string $documentationLink = null): MappedError + protected function addMappedError(MappedType|MappedProperty $target, string $message, MappedType $typeWithError, string $severity, ?string $documentationLink = null, ?string $missingProperty = null): MappedError { $typeLabel = MappedErrorFormatter::formatTypeLabel($typeWithError->getType()); $range = MappedErrorFormatter::formatRanges($target->getValueRanges()); @@ -113,6 +113,7 @@ protected function addMappedError(MappedType|MappedProperty $target, string $mes $range, parent: $target, documentationLink: $documentationLink, + missingProperty: $missingProperty, ); $target->addError($error); diff --git a/src/Vocabularies/Validators/Google/GoogleValidator.php b/src/Vocabularies/Validators/Google/GoogleValidator.php index 3a8a471a..2a657142 100644 --- a/src/Vocabularies/Validators/Google/GoogleValidator.php +++ b/src/Vocabularies/Validators/Google/GoogleValidator.php @@ -310,13 +310,14 @@ private function validateRequiredProperty(MappedType $type, array $missingProper $expectedProperties = $missingProperty['value'] ?? []; if (!$this->hasAnyPropertyKey($type, $expectedProperties)) { + $alternatives = implode(', ', array_keys($expectedProperties)); $message = \sprintf( 'Missing required property: at least one of the following properties must be present "%s" for the type "%s"', - implode(', ', array_keys($expectedProperties)), + $alternatives, $this->getTypeLabel($type), ); - $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_ERROR, $this->resolveDocumentationLink($missingProperty)); + $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_ERROR, $this->resolveDocumentationLink($missingProperty), $alternatives); } return; @@ -324,7 +325,7 @@ private function validateRequiredProperty(MappedType $type, array $missingProper $message = \sprintf('Missing required property: "%s" for the type "%s"', $missingProperty['name'], $this->getTypeLabel($type)); - $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_ERROR, $this->resolveDocumentationLink($missingProperty)); + $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_ERROR, $this->resolveDocumentationLink($missingProperty), $missingProperty['name']); } /** @@ -341,12 +342,13 @@ private function validateRecommendedProperty(MappedType $type, array $missingPro $expectedProperties = $missingProperty['value'] ?? []; if (!$this->hasAnyPropertyKey($type, $expectedProperties)) { + $alternatives = implode(', ', array_keys($expectedProperties)); $message = \sprintf( 'Missing recommended property: at least one of the following properties should be present "%s"', - implode(', ', array_keys($expectedProperties)), + $alternatives, ); - $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_WARNING, $this->resolveDocumentationLink($missingProperty)); + $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_WARNING, $this->resolveDocumentationLink($missingProperty), $alternatives); } return; @@ -354,7 +356,7 @@ private function validateRecommendedProperty(MappedType $type, array $missingPro $message = \sprintf('Missing recommended property: "%s" for the type "%s"', $missingProperty['name'], $this->getTypeLabel($type)); - $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_WARNING, $this->resolveDocumentationLink($missingProperty)); + $errors[] = $this->addMappedError($type, $message, $type, MappedError::SEVERITY_WARNING, $this->resolveDocumentationLink($missingProperty), $missingProperty['name']); } /** diff --git a/tests/Validation/SharedIdentifierTest.php b/tests/Validation/SharedIdentifierTest.php new file mode 100644 index 00000000..73c22e1f --- /dev/null +++ b/tests/Validation/SharedIdentifierTest.php @@ -0,0 +1,136 @@ + + * + * For the full copyright and license information, please view the LICENSE + * file that was distributed with this source code. + */ + +namespace JoliCode\StructuredData\Tests\Validation; + +use JoliCode\StructuredData\Audit\AuditOptions; +use JoliCode\StructuredData\Mapper\MappedProperty; +use JoliCode\StructuredData\Mapper\MappedType; +use JoliCode\StructuredData\Mapper\MappedTypeMerger; +use JoliCode\StructuredData\Validator; +use JoliCode\StructuredData\Vocabularies\Validators\Google\GoogleValidator; +use PHPUnit\Framework\TestCase; + +/** + * The blocks of a document sharing an identifier describe one node for Google: + * a property one block omits is not missing when another block provides it. + */ +class SharedIdentifierTest extends TestCase +{ + private const FIXTURE = __DIR__ . '/fixtures/google/event-two-blocks-same-id.html'; + + public function testAPropertyProvidedByAnotherBlockIsNotMissing(): void + { + $validator = new Validator(); + $validator->setValidator(GoogleValidator::class); + + $audit = $validator->audit((string) file_get_contents(self::FIXTURE)); + + $this->assertTrue($audit->isValid()); + $this->assertSame([], $audit->getDiagnostic(new AuditOptions(severity: AuditOptions::SEVERITY_ERROR))); + + // What no block provides is still reported, by each block. + /** @var list $warnings */ + $warnings = $audit->getDiagnostic(new AuditOptions(severity: AuditOptions::SEVERITY_WARNING)); + $this->assertCount(8, $warnings); + $this->assertCount(2, array_filter($warnings, static fn (string $message): bool => str_contains($message, '"offers"'))); + $this->assertSame([], array_filter($warnings, static fn (string $message): bool => str_contains($message, '"image"') || str_contains($message, '"description"'))); + + // The withdrawn errors no longer weigh on the blocks' severity. + foreach ($audit->getTypes() as $type) { + $this->assertSame('warning', $type->getErrorSeverity()); + } + } + + public function testTheReconciliationSurvivesTheSnippetCache(): void + { + $validator = new Validator(); + $validator->setValidator(GoogleValidator::class); + $document = (string) file_get_contents(self::FIXTURE); + + /** @var list $first */ + $first = $validator->audit($document)->getDiagnostic(); + /** @var list $second */ + $second = $validator->audit($document)->getDiagnostic(); + + $this->assertCount(8, $first); + $this->assertSame($first, $second); + } + + public function testDisagreeingValuesAreReportedAsADocumentWarningOnly(): void + { + $validator = new Validator(); + $validator->setValidator(GoogleValidator::class); + + $audit = $validator->audit((string) file_get_contents(__DIR__ . '/fixtures/google/event-two-blocks-same-id-conflicting-values.html')); + + $this->assertTrue($audit->isValid()); + + /** @var list $documentIssues */ + $documentIssues = $audit->getDiagnostic(new AuditOptions(severity: AuditOptions::SEVERITY_DOCUMENT)); + $this->assertCount(2, $documentIssues); + $this->assertStringContainsString('The "description" of "https://example.com/events/symfonylive-2026" has a different value in each of the 2 blocks', $documentIssues[0]); + $this->assertStringContainsString('"startDate"', $documentIssues[1]); + + // Google reports nothing about it: the Google diagnostics stay the same. + /** @var list $googleMessages */ + $googleMessages = $audit->getDiagnostic(new AuditOptions(validator: AuditOptions::VALIDATOR_GOOGLE)); + $this->assertSame([], array_filter($googleMessages, static fn (string $message): bool => str_contains($message, 'different value'))); + } + + public function testBlocksWithDifferentOrBlankIdentifiersAreNotMerged(): void + { + $validator = new Validator(); + $validator->setValidator(GoogleValidator::class); + + $document = <<<'HTML' + + +HTML; + + $audit = $validator->audit($document); + + $this->assertFalse($audit->isValid()); + /** @var list $errors */ + $errors = $audit->getDiagnostic(new AuditOptions(severity: AuditOptions::SEVERITY_ERROR)); + $this->assertCount(3, $errors); + } + + public function testGroupingIgnoresTypesWithoutAnAbsoluteIdentifier(): void + { + $withId = static function (string $id): MappedType { + $type = new MappedType(sourceFormat: 'json-ld', type: 'Event'); + $property = new MappedProperty('@id', $type); + $property->setValue($id); + $type->setProperty('@id', $property); + + return $type; + }; + + $groups = MappedTypeMerger::groupByIdentifier([ + $withId('https://example.com/a'), + $withId('https://example.com/a'), + $withId('https://example.com/b'), + $withId('_:b0'), + $withId('_:b0'), + $withId('relative/path'), + $withId('relative/path'), + new MappedType(sourceFormat: 'json-ld', type: 'Event'), + ]); + + $this->assertSame(['https://example.com/a'], array_keys($groups)); + $this->assertCount(2, $groups['https://example.com/a']); + } +} diff --git a/tests/Validation/fixtures/google-baseline.json b/tests/Validation/fixtures/google-baseline.json index 8a56261e..5921e8b5 100644 --- a/tests/Validation/fixtures/google-baseline.json +++ b/tests/Validation/fixtures/google-baseline.json @@ -287,6 +287,39 @@ ], "documentIssues": [] }, + "event-two-blocks-same-id-conflicting-values.html": { + "errors": [], + "warnings": [ + "[Google warning] Event: Missing recommended property: \"eventStatus\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"offers\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"organizer\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"performer\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"eventStatus\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"offers\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"organizer\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"performer\" for the type \"Event\"", + "[Document warning] The \"description\" of \"https:\/\/example.com\/events\/symfonylive-2026\" has a different value in each of the 2 blocks describing it (\"Two days of talks about the Symfony framework.\", \"Another description\"): Google merges them and keeps every value.", + "[Document warning] The \"startDate\" of \"https:\/\/example.com\/events\/symfonylive-2026\" has a different value in each of the 2 blocks describing it (\"2026-03-22T08:55:00+01:00\", \"2026-03-26T09:00:00+01:00\"): Google merges them and keeps every value." + ], + "documentIssues": [ + "[Document warning] The \"description\" of \"https:\/\/example.com\/events\/symfonylive-2026\" has a different value in each of the 2 blocks describing it (\"Two days of talks about the Symfony framework.\", \"Another description\"): Google merges them and keeps every value.", + "[Document warning] The \"startDate\" of \"https:\/\/example.com\/events\/symfonylive-2026\" has a different value in each of the 2 blocks describing it (\"2026-03-22T08:55:00+01:00\", \"2026-03-26T09:00:00+01:00\"): Google merges them and keeps every value." + ] + }, + "event-two-blocks-same-id.html": { + "errors": [], + "warnings": [ + "[Google warning] Event: Missing recommended property: \"eventStatus\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"offers\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"organizer\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"performer\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"eventStatus\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"offers\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"organizer\" for the type \"Event\"", + "[Google warning] Event: Missing recommended property: \"performer\" for the type \"Event\"" + ], + "documentIssues": [] + }, "event.jsonld": { "errors": [], "warnings": [], diff --git a/tests/Validation/fixtures/google/event-two-blocks-same-id-conflicting-values.html b/tests/Validation/fixtures/google/event-two-blocks-same-id-conflicting-values.html new file mode 100644 index 00000000..e818ec90 --- /dev/null +++ b/tests/Validation/fixtures/google/event-two-blocks-same-id-conflicting-values.html @@ -0,0 +1,37 @@ + + + + + Same event, two formats, two start dates + + + +
+

SymfonyLive Paris 2026

+

Another description

+ + + +
+ + diff --git a/tests/Validation/fixtures/google/event-two-blocks-same-id.html b/tests/Validation/fixtures/google/event-two-blocks-same-id.html new file mode 100644 index 00000000..f861597d --- /dev/null +++ b/tests/Validation/fixtures/google/event-two-blocks-same-id.html @@ -0,0 +1,35 @@ + + + + + Same event, two formats + + + +
+

SymfonyLive Paris 2026

+ + + +
+ + From ec5651d02cea36702a0d1fc34944ea79ac227f45 Mon Sep 17 00:00:00 2001 From: Xavier Lacot Date: Fri, 13 Nov 2026 15:49:51 +0100 Subject: [PATCH 11/11] Stop deduplicating the document warnings written in the baseline files --- .castor/qa.php | 23 ++++------------------- 1 file changed, 4 insertions(+), 19 deletions(-) diff --git a/.castor/qa.php b/.castor/qa.php index 19344ca7..760383c9 100644 --- a/.castor/qa.php +++ b/.castor/qa.php @@ -519,27 +519,12 @@ function updateBaseline( severity: AuditOptions::SEVERITY_ERROR, )); - $remainingDocumentIssues = $documentIssues; - $warningsWithoutExtraction = []; - - foreach ($warningMessages as $warningMessage) { - $matchingDocumentIssueKey = array_find_key( - $remainingDocumentIssues, - static fn (string $documentIssue): bool => $documentIssue === $warningMessage, - ); - - if ($matchingDocumentIssueKey) { - unset($remainingDocumentIssues[$matchingDocumentIssueKey]); - - continue; - } - - $warningsWithoutExtraction[] = $warningMessage; - } - + // A document issue is an error or a warning too, and the tests compare the + // errors and the warnings as the audit reports them, document issues + // included: the baseline lists it on both sides. $baseline[$file->getFilename()] = [ 'errors' => $errorMessages, - 'warnings' => $warningsWithoutExtraction, + 'warnings' => $warningMessages, 'documentIssues' => $documentIssues, ]; }