To validate a document, use the JoliCode\StructuredData\Validator class. It accepts
JSON-LD, microdata and RDFa (schema.org-style RDFa only), either as a JSON-LD document or
embedded in an HTML page.
audit() takes the document itself, as a string - never a URL, never a file path.
This library deliberately does not guess what a string is, and never fetches anything on
your behalf. Guessing is a security hazard: an application that forwards user input to a
validator would silently offer an attacker a way to reach its internal network
(http://127.0.0.1:9200/, cloud metadata endpoints), or to read local files through a
path or a stream wrapper (/var/www/.env, file://, phar://).
Whether a document may be fetched, from where, and under which restrictions is a decision only your application can make. So your application is the one that fetches:
// From a local file - the path comes from you, not from a user
$document = file_get_contents('/path/to/document.html');
// From the network - your HTTP client, your allow-list, your timeouts
$document = $httpClient->request('GET', $trustedUrl)->getContent();
$audit = $validator->audit($document);The same rule applies to the @context URLs found inside a document: see
Loading remote contexts.
audit() returns a JoliCode\StructuredData\Audit\Audit object:
isValid()returns true if no errors are detected;isFullyValid()returns true if no errors, no warnings, and no malformed (hence unusable) data structures were detected;getDiagnostic()returns the messages (errors and warnings).
Keep in mind that a schema.org type is considered valid even with warnings!
use JoliCode\StructuredData\Validator;
$validator = new Validator();
$audit = $validator->audit($document);
if (!$audit->isValid()) {
foreach ($audit->getDiagnostic() as $message) {
// [Google warning] DataFeed.dataFeedElement.workExample: Missing recommended property: "sameAs" for the type "Book"
// [Google error] DataFeed.dataFeedElement.workExample.potentialAction.expectsAcceptanceOf: Missing required property: "price" for the type "Offer" when "category" is "purchase" or "rental".
echo $message;
}
}getDiagnostic() accepts an optional JoliCode\StructuredData\Audit\AuditOptions object,
which lets you filter or group the results, or change the return format. See its PHPDoc
for details.
To access the full parsed PHP tree, use getTypes() and inspect the underlying
MappedType objects directly. These are low-level objects, but they are the most detailed
information you can get, and they preserve the type hierarchy of the document. For an idea
of what you can do with them, look at the output of the castor validate command.
If you are only interested in the results of a single validator, call setValidator()
before auditing:
use JoliCode\StructuredData\Validator;
use JoliCode\StructuredData\Vocabularies\Validators\Google\GoogleValidator;
$validator = new Validator();
$validator->setValidator(GoogleValidator::class);
$validator->audit($document);Terms hosted under pending.schema.org are still under
development and may change or be removed. Using them is legitimate, so the validator
accepts them silently by default; opt in to $reportPendingVocabularyUsage to get a
warning for each of these usages instead:
$audit = $validator->audit($document, reportPendingVocabularyUsage: true);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.
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.
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:
$audit = $validator->audit($document, mergeNodesSharingAnIdentifier: false);Each block is then an item of its own.
From a clone of this repository, with Castor
installed, two commands validate a document from the command line or in CI. castor check
gives a short verdict, castor validate a parsed and colored full audit (it can be pretty
verbose!). Both return a meaningful exit code.
castor check <file-or-url>
castor validate <file-or-url>
castor validate <file-or-url> google # a single validator: google or schema-org
castor validate --no-merge <file-or-url> # audit every block on its ownUnlike the Validator::audit() API, these commands do accept a file path or a URL,
and will read or fetch it for you. That is safe here precisely because the argument comes
from the operator running the command, not from a document being processed - exactly the
distinction drawn in Accepted inputs.