Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 14 additions & 2 deletions .castor/qa.php
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,7 @@
use JoliCode\StructuredData\Audit\AuditOptions;
use JoliCode\StructuredData\JsonLd\Algorithms;
use JoliCode\StructuredData\Tests\Validation\Benchmark\WorkerValidationBench;
use JoliCode\StructuredData\Tests\Validation\SnapshotDocumentLoader;
use JoliCode\StructuredData\Validator;
use JoliCode\StructuredData\Vocabularies\Generators\Google\Filesystem as GoogleFilesystem;
use JoliCode\StructuredData\Vocabularies\Generators\SchemaOrg\Filesystem as SchemaOrgFilesystem;
Expand Down Expand Up @@ -500,12 +501,17 @@ function updateBaseline(
string $baselinePath,
): void {
$finder = finder()->files()->in($path)->sortByName();
$validator = new Validator();
// Resolve the remote contexts as the tests do, from the committed snapshots:
// the default loader refuses every host.
$validator = new Validator(documentLoader: new SnapshotDocumentLoader());
$validator->setValidator($specificValidator);
$baseline = [];

foreach ($finder as $file) {
$audit = $validator->audit($file->getContents());
// Audit as the tests do: the baselines also record the usages of the
// pending.schema.org vocabulary (this option only affects the schema.org
// validator).
$audit = $validator->audit($file->getContents(), reportPendingVocabularyUsage: true);
/** @var array<string> $documentIssues */
$documentIssues = $audit->getDiagnostic(new AuditOptions(
severity: AuditOptions::SEVERITY_DOCUMENT,
Expand All @@ -522,6 +528,12 @@ function updateBaseline(
// 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.
// The tests compare sorted lists: sorting here keeps the files stable, so a
// regeneration only shows the diagnostics that actually changed.
sort($errorMessages);
sort($warningMessages);
sort($documentIssues);

$baseline[$file->getFilename()] = [
'errors' => $errorMessages,
'warnings' => $warningMessages,
Expand Down
176 changes: 111 additions & 65 deletions .castor/validate.php
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,18 @@
*/

use Castor\Attribute\AsArgument;
use Castor\Attribute\AsOption;
use Castor\Attribute\AsTask;

use function Castor\http_request;
use function Castor\io;

use JoliCode\StructuredData\Audit\AuditOptions;
use JoliCode\StructuredData\Audit\Item;
use JoliCode\StructuredData\Mapper\MappedError;
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 Symfony\Component\Console\Command\Command;
Expand All @@ -30,8 +33,10 @@ function check(
string $fileOrUrl,
#[AsArgument(name: 'validator', description: 'The specific validator to use. Accepted values are: "schema-org", "schemaorg", "google".')]
false|string $specificValidator = false,
#[AsOption(name: 'no-merge', description: 'Audit every block on its own, instead of merging the blocks sharing an identifier as Google does')]
bool $noMerge = false,
): int {
return runValidation($fileOrUrl, $specificValidator, false);
return runValidation($fileOrUrl, $specificValidator, false, !$noMerge);
}

#[AsTask(name: 'validate', description: 'Fully validate a local file or a remote URL')]
Expand All @@ -40,8 +45,10 @@ function validate(
string $fileOrUrl,
#[AsArgument(name: 'validator', description: 'The specific validator to use. Accepted values are: "schema-org", "schemaorg", "google".')]
false|string $specificValidator = false,
#[AsOption(name: 'no-merge', description: 'Audit every block on its own, instead of merging the blocks sharing an identifier as Google does')]
bool $noMerge = false,
): int {
return runValidation($fileOrUrl, $specificValidator, true);
return runValidation($fileOrUrl, $specificValidator, true, !$noMerge);
}

/**
Expand Down Expand Up @@ -72,7 +79,7 @@ function resolveInput(string $fileOrUrl): string
return $content;
}

function runValidation(string $fileOrUrl, false|string $specificValidator, bool $withDetails): int
function runValidation(string $fileOrUrl, false|string $specificValidator, bool $withDetails, bool $merge): int
{
io()->title(sprintf($withDetails ? 'Validating %s' : 'Checking %s', $fileOrUrl));

Expand Down Expand Up @@ -100,9 +107,9 @@ function runValidation(string $fileOrUrl, false|string $specificValidator, bool
return Command::INVALID;
}

$audit = $validator->audit($document);
$types = $audit->getTypes();
$typesCount = count($types);
$audit = $validator->audit($document, mergeNodesSharingAnIdentifier: $merge);
$typesCount = count($audit->getTypes());
$items = $audit->getItems();

if (0 === $typesCount) {
io()->warning('No schema.org types were found in the provided document.');
Expand All @@ -116,71 +123,25 @@ function runValidation(string $fileOrUrl, false|string $specificValidator, bool
io()->info(sprintf('%d schema.org types were found in the provided document.', $typesCount));
}

if (count($items) !== $typesCount) {
io()->info(sprintf(
'The blocks sharing an identifier are merged, as Google does: they describe %d %s. Use --no-merge to audit every block on its own.',
count($items),
1 === count($items) ? 'node' : 'nodes',
));
}

if ($withDetails) {
foreach ($types as $index => $type) {
foreach ($items as $index => $item) {
io()->section(sprintf('<fg=blue>Type</> <fg=magenta;options=bold>N°</> <fg=blue>%d</>', $index + 1));

displayType($type);
io()->writeln('');

$hasGoogleErrors = false;
$hasGoogleWarnings = false;
$hasSchemaOrgErrors = false;
$hasSchemaOrgWarnings = false;

if ($errors = $type->getMergedErrors()) {
foreach ($errors as $error) {
if (MappedError::SEVERITY_ERROR === $error->getSeverity()) {
io()->writeln(sprintf('<fg=magenta;options=bold>%s</>', $error->getFormattedMessage()));

if (GoogleValidator::VALIDATOR_NAME === $error->getValidatorName()) {
$hasGoogleErrors = true;
} else {
$hasSchemaOrgErrors = true;
}
} else {
io()->writeln(sprintf('<fg=yellow;options=bold>%s</>', $error->getFormattedMessage()));

if (GoogleValidator::VALIDATOR_NAME === $error->getValidatorName()) {
$hasGoogleWarnings = true;
} else {
$hasSchemaOrgWarnings = true;
}
}

io()->writeln(sprintf(
"<fg=cyan>The above %s was raised for %s%s\nFound on input positions %s (line:col)</>",
$error->getSeverity(),
$error->getType() ? sprintf('the type "%s"', $error->getType()) : 'an unknown type (with no @type property)',
$error->getProperty() ? sprintf(' on its "%s" property', $error->getProperty()) : '',
$error->getRanges(),
));
io()->writeln('');
}
} else {
io()->writeln('<fg=cyan>Type is fully valid!</>');
io()->writeln('');
}

$googleSpecific = strtolower(GoogleValidator::VALIDATOR_NAME) === $specificValidator;

if (!$specificValidator || $googleSpecific) {
io()->writeln(sprintf(
'<fg=cyan>Google Validation</>: <fg=%s;options=bold>%s</>',
$hasGoogleErrors ? 'magenta' : ($hasGoogleWarnings ? 'yellow' : 'blue'),
$hasGoogleErrors ? 'FAILURE' : ($hasGoogleWarnings ? 'WARNINGS' : 'PASSES'),
));
}

if (!$googleSpecific) {
io()->writeln(sprintf(
'<fg=cyan>Schema.org Validation</>: <fg=%s;options=bold>%s</>',
$hasSchemaOrgErrors ? 'magenta' : ($hasSchemaOrgWarnings ? 'yellow' : 'blue'),
$hasSchemaOrgErrors ? 'FAILURE' : ($hasSchemaOrgWarnings ? 'WARNINGS' : 'PASSES'),
));
if ($item->isMerged()) {
displaySources($item);
}

displayType($item->getType());
io()->writeln('');
displayDiagnostics($item->getType(), $specificValidator);
}
}

Expand Down Expand Up @@ -216,6 +177,91 @@ function runValidation(string $fileOrUrl, false|string $specificValidator, bool
return Command::SUCCESS;
}

function displaySources(Item $item): void
{
$sources = $item->getSources();

io()->writeln(sprintf('<fg=cyan>Merged from %d blocks sharing the identifier "%s":</>', count($sources), $item->getIdentifier()));

foreach ($sources as $source) {
$line = ($source->getValueRanges()[0] ?? null)?->start?->line;

io()->writeln(sprintf(
'<fg=cyan> * a %s block%s</>',
$source->getSourceFormat(),
null !== $line ? sprintf(' on line %d', $line) : '',
));
}

io()->writeln('');
}

function displayDiagnostics(MappedType $type, false|string $specificValidator): void
{
$hasGoogleErrors = false;
$hasGoogleWarnings = false;
$hasSchemaOrgErrors = false;
$hasSchemaOrgWarnings = false;

if ($errors = $type->getMergedErrors()) {
foreach ($errors as $error) {
// The values the merged blocks disagree on weigh on no verdict.
$isMergeIssue = MappedTypeMerger::VALIDATOR_NAME === $error->getValidatorName();
$isGoogleIssue = GoogleValidator::VALIDATOR_NAME === $error->getValidatorName();

if (MappedError::SEVERITY_ERROR === $error->getSeverity()) {
io()->writeln(sprintf('<fg=magenta;options=bold>%s</>', $error->getFormattedMessage()));

if ($isGoogleIssue) {
$hasGoogleErrors = true;
} elseif (!$isMergeIssue) {
$hasSchemaOrgErrors = true;
}
} else {
io()->writeln(sprintf('<fg=yellow;options=bold>%s</>', $error->getFormattedMessage()));

if ($isGoogleIssue) {
$hasGoogleWarnings = true;
} elseif (!$isMergeIssue) {
$hasSchemaOrgWarnings = true;
}
}

io()->writeln(sprintf(
"<fg=cyan>The above %s was raised for %s%s\nFound on input positions %s (line:col)</>",
$error->getSeverity(),
$error->getType() ? sprintf('the type "%s"', $error->getType()) : 'an unknown type (with no @type property)',
$error->getProperty() ? sprintf(' on its "%s" property', $error->getProperty()) : '',
$error->getRanges(),
));
io()->writeln('');
}
} else {
io()->writeln('<fg=cyan>Type is fully valid!</>');
io()->writeln('');
}

$googleSpecific = strtolower(GoogleValidator::VALIDATOR_NAME) === $specificValidator;

if (!$specificValidator || $googleSpecific) {
io()->writeln(sprintf(
'<fg=cyan>Google Validation</>: <fg=%s;options=bold>%s</>',
$hasGoogleErrors ? 'magenta' : ($hasGoogleWarnings ? 'yellow' : 'blue'),
$hasGoogleErrors ? 'FAILURE' : ($hasGoogleWarnings ? 'WARNINGS' : 'PASSES'),
));
}

if (!$googleSpecific) {
io()->writeln(sprintf(
'<fg=cyan>Schema.org Validation</>: <fg=%s;options=bold>%s</>',
$hasSchemaOrgErrors ? 'magenta' : ($hasSchemaOrgWarnings ? 'yellow' : 'blue'),
$hasSchemaOrgErrors ? 'FAILURE' : ($hasSchemaOrgWarnings ? 'WARNINGS' : 'PASSES'),
));
}

io()->writeln('');
}

function displayType(MappedType $type, int $level = 0): void
{
$prefix = str_repeat(' ', $level);
Expand Down
15 changes: 10 additions & 5 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,14 +10,19 @@
- `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.
- 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. The audit now merges them into one item, validated as a whole: a property one
block omits is no longer reported missing when another block provides it, and the issues
of the node are reported once. `Audit::getItems()` lists the items, each with its node
and its source blocks, which keep their own audit; `Audit::getTypes()` still lists the
blocks. Values the blocks disagree on are a warning of the merged item (validator
`Merge`, `AuditOptions::VALIDATOR_MERGE`), since Google keeps them all. The merge is on
by default; pass `mergeNodesSharingAnIdentifier: false` to `Validator::audit()`, or
`--no-merge` to `castor validate` and `castor check`, to audit every block on its own.

### 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.
Expand Down
49 changes: 43 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,12 +148,41 @@ The validator accepts the following data formats:
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.

By default, the validator does the same. The audit is made of items, one per node, listed
by `Audit::getItems()`: the blocks sharing an identifier make one item, the others one
item each. The diagnostics of the audit (`isValid()`, `getDiagnostic()`) are the ones of
the items, so an issue of a merged node is reported once, with the positions of every
block it comes from.

```php
foreach ($audit->getItems() as $item) {
$item->getType(); // the node: merged from several blocks, or the block itself
$item->isMerged(); // true when the node comes from several blocks
$item->getIdentifier(); // its absolute "@id" or "itemid", if any
$item->getSources(); // the blocks it comes from
}
```

Each source block keeps its own audit, as if it were alone in the document: a block may
report a property another block provides, while the merged item, which makes the verdict,
does not. `Audit::getTypes()` still lists the blocks.

When the blocks disagree on a value, Google keeps every value and reports nothing; the
validator raises a warning on the property of the merged node, with the `Merge` validator
name (`AuditOptions::VALIDATOR_MERGE`), outside the Google diagnostics. Blank node
identifiers are local to their block and never merge, and identifiers are compared as
written. Only the top-level node of each block is merged: nested nodes sharing an
identifier are not.

Google is not the only consumer of structured data, though. To audit every block on its
own, with no merge, disable the option:

```php
$audit = $validator->audit($document, mergeNodesSharingAnIdentifier: false);
```

Each block is then an item of its own.

### Using the validator

Expand Down Expand Up @@ -250,6 +279,14 @@ castor validate <file-or-url> google
castor validate <file-or-url> schema-org
```

The blocks sharing an identifier are merged, as Google does (see
[Blocks describing the same node](#blocks-describing-the-same-node)); pass `--no-merge`
to audit every block on its own:

```bash
castor validate --no-merge <file-or-url>
```

Sample result of the validate command:
<img width="822" height="749" alt="Output of the castor validate command" src="https://github.com/user-attachments/assets/97912eb8-1e11-4ba9-8cc1-ac0b6248d816" />

Expand Down
Loading
Loading