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
31 changes: 16 additions & 15 deletions .castor/earl.php
Original file line number Diff line number Diff line change
Expand Up @@ -258,28 +258,29 @@ function earlTurtle(array $assertions, string $release, \DateTimeImmutable $date
'@prefix foaf: <http://xmlns.com/foaf/0.1/> .',
'@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .',
'',
// Within each node, the rdf:type ("a") comes first, then the properties in
// alphabetical order.
\sprintf('<%s> a doap:Project, earl:TestSubject, earl:Software ;', EARL_SUBJECT_IRI),
' doap:name "jolicode/structured-data" ;',
\sprintf(' dc:creator <%s> ;', EARL_ASSERTOR_IRI),
' 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:developer <%s> ;', EARL_ASSERTOR_IRI),
\sprintf(' doap:homepage <%s> ;', EARL_SUBJECT_IRI),
' doap:implements <https://www.w3.org/TR/json-ld11/>, <https://www.w3.org/TR/json-ld11-api/>, <https://www.w3.org/TR/json-ld11-framing/> ;',
\sprintf(' doap:license <%s/blob/main/LICENSE> ;', EARL_SUBJECT_IRI),
' doap:name "jolicode/structured-data" ;',
' doap:programming-language "PHP" ;',
\sprintf(' doap:developer <%s>, <https://github.com/HedicGuibert> ;', EARL_ASSERTOR_IRI),
\sprintf(' dc:creator <%s> ;', EARL_ASSERTOR_IRI),
' doap:release [',
\sprintf(' doap:created "%s"^^xsd:date ;', $date->format('Y-m-d')),
\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(' doap:revision "%s"', $release),
' ] ;',
' doap:shortdesc "JSON-LD 1.1 processor and structured data validator for PHP"@en .',
'',
\sprintf('<%s> a foaf:Person, earl:Assertor ;', EARL_ASSERTOR_IRI),
' foaf:name "Xavier Lacot" ;',
\sprintf(' foaf:homepage <%s> .', EARL_ASSERTOR_IRI),
'',
'<https://github.com/HedicGuibert> a foaf:Person ;',
' foaf:name "Hédic Guibert" ;',
' foaf:homepage <https://github.com/HedicGuibert> .',
' foaf:homepage <https://lacot.org/> ;',
\sprintf(' foaf:made <%s> ;', EARL_ASSERTOR_IRI),
' foaf:name "Xavier Lacot" .',
'',
];

Expand All @@ -288,10 +289,10 @@ function earlTurtle(array $assertions, string $release, \DateTimeImmutable $date
foreach ($assertions as $assertion) {
$lines[] = '[ a earl:Assertion ;';
$lines[] = \sprintf(' earl:assertedBy <%s> ;', EARL_ASSERTOR_IRI);
$lines[] = ' earl:mode earl:automatic ;';
$lines[] = \sprintf(' earl:result [ a earl:TestResult ; dc:date "%s"^^xsd:dateTime ; earl:outcome earl:%s ] ;', $timestamp, $assertion['outcome']);
$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[] = \sprintf(' earl:test <%s> ] .', $assertion['test']);
$lines[] = '';
}

Expand Down
2 changes: 1 addition & 1 deletion .castor/qa.php
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@
// upstream change cannot break an unrelated PR. The weekly scheduled CI run is what
// surfaces upstream drift: bump this SHA (and rerun `castor qa:phpunit:prepare --force`)
// to pick up new W3C tests.
const W3C_TEST_SUITE_REF = '92f07705a0c0ac27aa9bc6fe1322dcc9fad0114d';
const W3C_TEST_SUITE_REF = '61305e9c7b7d3d79178baefdb34bc1d47464c783';

// Commit of https://github.com/w3c/json-ld-framing the framing test suite is pinned to.
const W3C_FRAMING_TEST_SUITE_REF = '3bf782ba9a40dd1b143435abe386d38df64f2b47';
Expand Down
2 changes: 1 addition & 1 deletion .github/SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ job of a validator is to inspect input you did not write). The following are in
we take them seriously:

- Server-Side Request Forgery through remote `@context` resolution. Remote loading is
**off by default**; see the "Loading remote contexts" section of the [README](../README.md).
**off by default**; see [Loading remote contexts](../docs/remote-contexts.md).
- Denial of service through hostile documents (deeply nested input, oversized responses,
context recursion).
- Local file or stream-wrapper access through crafted URLs.
Expand Down
90 changes: 87 additions & 3 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,8 +11,10 @@ Everybody should be able to help. Here's how you can do it:
Here's some tips to make you the best contributor ever:

* [Rules](#rules)
* [Setting up](#setting-up)
* [Green tests](#green-tests)
* [Standard code](#standard-code)
* [Commands reference](#commands-reference)
* [Keeping your fork up-to-date](#keeping-your-fork-up-to-date)

## Rules
Expand Down Expand Up @@ -47,6 +49,21 @@ which gives the context and/or explains why you are creating it.
Your work will then be reviewed as soon as possible (suggestions about some
changes, improvements or alternatives may be given).

## Setting up

The tooling runs with the PHP task runner [Castor](https://github.com/jolicode/castor/).
Downloading the W3C test suites also needs the
[ZipArchive PHP extension](https://www.php.net/manual/en/class.ziparchive.php).

Clone the repository, then install the library's dependencies and the QA tooling:

```shell
composer install # the library's own dependencies (Composer, not Castor)
castor qa:install # the QA tooling: php-cs-fixer, phpstan, phpunit, phpbench, infection
```

All the tasks are defined in the `.castor` directory, one file per namespace.

## Green tests

Run the tests using the following command:
Expand All @@ -68,10 +85,12 @@ This project includes two main validators: the schema.org validator and the Goog

### Updating validators

When adding or updating validator support (new types, schema versions, special validation rules):
The validation classes shipped in `src/Vocabularies/Generated` are generated from the
vocabulary definitions (see [Vocabulary generation](#vocabulary-generation)). When adding or
updating validator support (new types, schema versions, special validation rules):

- **Google validator** updates are based on the [Google structured-data documentation](https://developers.google.com/search/docs/advanced/structured-data/intro-structured-data). For special rules or complex validation logic, see the existing rule implementations in `src/Vocabularies/Validators/Google/SpecialRules/`.
- **Schema.org validator** updates follow [official schema.org releases](https://schema.org/docs/releases.html).
- **Google validator** updates track the [Google structured-data documentation](https://developers.google.com/search/docs/appearance/structured-data/intro-structured-data), which evolves continuously. For special rules or complex validation logic, see the existing rule implementations in `src/Vocabularies/Validators/Google/SpecialRules/`.
- **Schema.org validator** updates are driven by the [official schema.org releases](https://schema.org/docs/releases.html). When upgrading, always review the release notes and check that the changes to the `schema-org-baseline.json` test fixture reflect real schema.org changes.

For comprehensive upgrade procedures for either validator, refer to:
- [Google validator upgrade guidelines](resources/google/UPGRADE_GUIDELINES.md)
Expand All @@ -86,6 +105,71 @@ our coding standards:
castor qa:cs
```

## Commands reference

### QA

Command | Description
---- | -----
`castor qa:install` | Installs the QA tooling
`castor qa:update` | Updates the QA tooling
`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](docs/json-ld.md#conformance))

### Tests

Command | Description
---- | -----
`castor qa:phpunit:prepare` | Downloads the W3C tests suite
`castor qa:phpunit:run` | Runs PHPUnit
`castor qa:phpunit:coverage` | Runs PHPUnit with code coverage (requires the pcov or xdebug extension)
`castor qa:infection` | Runs Infection mutation testing on the validator and mapper layers (requires the pcov or xdebug extension)

The W3C test suite is pinned to a known-good upstream commit (see `W3C_TEST_SUITE_REF` in `.castor/qa.php`).
To re-download it, or to test against the upstream main branch:

```shell
castor qa:phpunit:prepare --force
castor qa:phpunit:prepare --force --ref main
```

### Benchmarks

Command | Description
---- | -----
`castor qa:bench:all` | Runs all the benchmarks
`castor qa:bench:algorithms` | Runs the JSON-LD manipulation algorithms benchmark
`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).

### Demo website

These commands build the [demo website](website/README.md), that runs the validator in the browser:

Command | Description
---- | -----
`castor website:build` | Builds the demo website: its assets, and PHP as WebAssembly with the validator
`castor website:check` | Checks, in node, that what is built boots, and audits a document
`castor website:serve` | Serves the demo website

### Vocabulary generation

These commands refresh the validation classes shipped in `src/Vocabularies/Generated`:

Command | Description
---- | -----
`castor schema-org:update-version` | Bump the schema.org version to the latest release published on GitHub
`castor schema-org:download` | Download the schema.org types definition file and JSON-LD context
`castor schema-org:generate` | Generate the schema.org validation classes
`castor schema-org:download-examples` | Refresh the schema.org examples used by the tests
`castor google:download` | Crawl the Google structured-data documentation
`castor google:generate` | Generate the Google validation classes
`castor google:check` | Check the Google documentation coverage against the curated manifest

## Keeping your fork up-to-date

To keep your fork up-to-date, you should track the upstream (original) one
Expand Down
Loading
Loading