wikibase / constraints
Extension to manage constraints in Wikibase.
Installs: 77
Dependents: 0
Suggesters: 0
Security: 0
Stars: 12
Watchers: 23
Forks: 3
Type:mediawiki-extension
Requires
- php: >=7.4.0
- data-values/common: ^1.0.0|^0.4.0|^0.3.0
- data-values/data-values: ^3.0.0|^2.0.0|^1.0.0
- data-values/geo: ^4.2.1|^3.0.1|^2.1.2
- data-values/number: ^0.12.3|^0.11.0
- data-values/serialization: ^1.2.4|^1.2.1
- data-values/time: ^1.0.4
- serialization/serialization: ^3.2.1|^4.0.0
- wikimedia/purtle: ^1.0.7
Requires (Dev)
- dev-master
- dev-REL1_41
- dev-wmf/1.44.0-wmf.1
- dev-wmf/branch_cut_pretest
- dev-wmf/next
- dev-REL1_39
- dev-REL1_42
- dev-wmf/1.43.0-wmf.28
- dev-REL1_43
- dev-wmf/1.43.0-wmf.27
- dev-wmf/1.43.0-wmf.26
- dev-wmf/1.43.0-wmf.24
- dev-wmf/1.43.0-wmf.25
- dev-wmf/1.43.0-wmf.23
- dev-wmf/1.43.0-wmf.22
- dev-wmf/1.43.0-wmf.21
- dev-wmf/1.43.0-wmf.20
- dev-wmf/1.43.0-wmf.19
- dev-wmf/1.43.0-wmf.18
- dev-wmf/1.43.0-wmf.17
- dev-wmf/1.43.0-wmf.16
- dev-wmf/1.43.0-wmf.15
- dev-wmf/1.43.0-wmf.12
- dev-wmf/1.43.0-wmf.13
- dev-wmf/1.43.0-wmf.14
- dev-wmf/1.43.0-wmf.11
- dev-REL1_40
- dev-wmf/1.43.0-wmf.10
- dev-wmf/1.43.0-wmf.9
- dev-wmf/1.43.0-wmf.8
- dev-wmf/1.43.0-wmf.7
- dev-wmf/1.43.0-wmf.6
- dev-wmf/1.43.0-wmf.5
- dev-wmf/1.43.0-wmf.4
- dev-wmf/1.43.0-wmf.3
- dev-wmf/1.43.0-wmf.2
- dev-wmf/1.43.0-wmf.1
- dev-wmf/1.42.0-wmf.26
- dev-wmf/1.42.0-wmf.25
- dev-wmf/1.42.0-wmf.24
- dev-wmf/1.42.0-wmf.23
- dev-wmf/1.42.0-wmf.22
- dev-wmf/1.42.0-wmf.21
- dev-wmf/1.42.0-wmf.19
- dev-wmf/1.42.0-wmf.20
- dev-wmf/1.42.0-wmf.18
- dev-wmf/1.42.0-wmf.17
- dev-wmf/1.42.0-wmf.16
- dev-wmf/1.42.0-wmf.14
- dev-wmf/1.42.0-wmf.15
- dev-wmf/1.42.0-wmf.13
- dev-REL1_35
- dev-wmf/1.42.0-wmf.12
- dev-wmf/1.42.0-wmf.10
- dev-wmf/1.42.0-wmf.9
- dev-wmf/1.42.0-wmf.7
- dev-dependabot/npm_and_yarn/sinon-17.0.1
- dev-wmf/1.42.0-wmf.2
- dev-wmf/1.42.0-wmf.3
- dev-wmf/1.42.0-wmf.4
- dev-wmf/1.42.0-wmf.5
- dev-wmf/1.42.0-wmf.1
- dev-wmf/1.41.0-wmf.30
- dev-wmf/1.41.0-wmf.29
- dev-wmf/1.41.0-wmf.26
- dev-wmf/1.41.0-wmf.27
- dev-wmf/1.41.0-wmf.28
- dev-wmf/1.41.0-wmf.25
- dev-dependabot/npm_and_yarn/jasmine-5.1.0
- dev-wmf/1.41.0-wmf.24
- dev-wmf/1.41.0-wmf.23
- dev-REL1_38
- dev-wmf/1.41.0-wmf.22
- dev-wmf/1.41.0-wmf.20
- dev-wmf/1.41.0-wmf.19
- dev-wmf/1.41.0-wmf.18
- dev-wmf/1.41.0-wmf.17
- dev-wmf/1.41.0-wmf.16
- dev-wmf/1.41.0-wmf.15
- dev-wmf/1.41.0-wmf.13
- dev-wmf/1.41.0-wmf.12
- dev-wmf/1.41.0-wmf.11
- dev-wmf/1.41.0-wmf.10
- dev-wmf/1.41.0-wmf.9
- dev-wmf/1.41.0-wmf.8
- dev-wmf/1.41.0-wmf.7
- dev-wmf/1.41.0-wmf.6
- dev-wmf/1.41.0-wmf.5
- dev-wmf/1.41.0-wmf.4
- dev-wmf/1.41.0-wmf.3
- dev-wmf/1.41.0-wmf.2
- dev-wmf/1.41.0-wmf.1
- dev-wmf/1.40.0-wmf.27
- dev-wmf/1.40.0-wmf.25
- dev-wmf/1.40.0-wmf.26
- dev-wmf/1.40.0-wmf.24
- dev-wmf/1.40.0-wmf.23
- dev-wmf/1.40.0-wmf.22
- dev-wmf/1.40.0-wmf.20
- dev-wmf/1.40.0-wmf.21
- dev-wmf/1.40.0-wmf.19
- dev-wmf/1.40.0-wmf.18
- dev-wmf/1.40.0-wmf.17
- dev-wmf/1.40.0-wmf.14
- dev-wmf/1.40.0-wmf.13
- dev-REL1_37
- dev-wmf/1.40.0-wmf.12
- dev-wmf/1.40.0-wmf.10
- dev-wmf/1.40.0-wmf.9
- dev-wmf/1.40.0-wmf.8
- dev-wmf/1.40.0-wmf.7
- dev-wmf/1.40.0-wmf.6
- dev-wmf/1.40.0-wmf.5
- dev-wmf/1.40.0-wmf.4
- dev-wmf/1.40.0-wmf.3
- dev-wmf/1.40.0-wmf.1
- dev-wmf/1.40.0-wmf.2
- dev-wmf/1.39.0-wmf.28
- dev-wmf/1.39.0-wmf.27
- dev-wmf/1.39.0-wmf.26
- dev-wmf/1.39.0-wmf.25
- dev-wmf/1.39.0-wmf.24
- dev-wmf/1.39.0-wmf.23
- dev-wmf/1.39.0-wmf.22
- dev-wmf/1.39.0-wmf.21
- dev-wmf/1.39.0-wmf.20
- dev-wmf/1.39.0-wmf.19
- dev-wmf/1.39.0-wmf.18
- dev-wmf/1.39.0-wmf.16
- dev-wmf/1.39.0-wmf.17
- dev-wmf/1.39.0-wmf.15
- dev-REL1_36
- dev-wmf/1.39.0-wmf.14
- dev-wmf/1.39.0-wmf.13
- dev-wmf/1.39.0-wmf.12
- dev-wmf/1.39.0-wmf.11
- dev-wmf/1.39.0-wmf.10
- dev-wmf/1.39.0-wmf.9
- dev-wmf/1.39.0-wmf.8
- dev-wmf/1.39.0-wmf.6
- dev-wmf/1.39.0-wmf.7
- dev-wmf/1.39.0-wmf.5
- dev-wmf/1.39.0-wmf.4
- dev-wmf/1.39.0-wmf.1
- dev-wmf/1.39.0-wmf.2
- dev-wmf/1.39.0-wmf.3
- dev-wmf/1.38.0-wmf.26
- dev-wmf/1.38.0-wmf.25
- dev-wmf/1.38.0-wmf.24
- dev-wmf/1.38.0-wmf.22
- dev-wmf/1.38.0-wmf.23
- dev-wmf/1.38.0-wmf.21
- dev-wmf/1.38.0-wmf.20
- dev-wmf/1.38.0-wmf.19
- dev-wmf/1.38.0-wmf.17
- dev-wmf/1.38.0-wmf.18
- dev-wmf/1.38.0-wmf.16
- dev-wmf/1.38.0-wmf.15
- dev-wmf/1.38.0-wmf.14
- dev-wmf/1.38.0-wmf.13
- dev-wmf/1.38.0-wmf.12
- dev-wmf/1.38.0-wmf.11
- dev-wmf/1.38.0-wmf.10
- dev-wmf/1.38.0-wmf.9
- dev-wmf/1.38.0-wmf.8
- dev-wmf/1.38.0-wmf.7
- dev-wmf/1.38.0-wmf.6
- dev-wmf/1.38.0-wmf.5
- dev-wmf/1.38.0-wmf.4
- dev-wmf/1.38.0-wmf.3
- dev-wmf/1.38.0-wmf.2
- dev-wmf/1.37.0-wmf.24
- dev-wmf/1.38.0-wmf.1
- dev-wmf/1.37.0-wmf.23
- dev-wmf/1.37.0-wmf.22
- dev-REL1_31
- dev-wmf/1.37.0-wmf.21
- dev-wmf/1.37.0-wmf.20
- dev-wmf/1.37.0-wmf.19
- dev-wmf/1.37.0-wmf.18
- dev-wmf/1.37.0-wmf.16
- dev-wmf/1.37.0-wmf.17
- dev-wmf/1.37.0-wmf.15
- dev-wmf/1.37.0-wmf.14
- dev-wmf/1.37.0-wmf.13
- dev-wmf/1.37.0-wmf.12
- dev-wmf/1.37.0-wmf.11
- dev-wmf/1.37.0-wmf.10
- dev-wmf/1.37.0-wmf.9
- dev-wmf/1.37.0-wmf.8
- dev-wmf/1.37.0-wmf.7
- dev-wmf/1.37.0-wmf.6
- dev-wmf/1.37.0-wmf.5
- dev-wmf/1.37.0-wmf.4
- dev-wmf/1.37.0-wmf.3
- dev-wmf/1.37.0-wmf.2
- dev-wmf/1.37.0-wmf.1
- dev-wmf/1.36.0-wmf.39
- dev-wmf/1.36.0-wmf.38
- dev-wmf/1.36.0-wmf.36
- dev-wmf/1.36.0-wmf.37
- dev-wmf/1.36.0-wmf.35
- dev-wmf/1.36.0-wmf.34
- dev-wmf/1.36.0-wmf.33
- dev-wmf/1.36.0-wmf.32
- dev-wmf/1.36.0-wmf.31
- dev-wmf/1.36.0-wmf.30
- dev-wmf/1.36.0-wmf.29
- dev-wmf/1.36.0-wmf.28
- dev-wmf/1.36.0-wmf.27
- dev-wmf/1.36.0-wmf.26
- dev-wmf/1.36.0-wmf.25
- dev-wmf/1.36.0-wmf.24
- dev-wmf/1.36.0-wmf.23
- dev-wmf/1.36.0-wmf.22
- dev-wmf/1.36.0-wmf.21
- dev-wmf/1.36.0-wmf.20
- dev-wmf/1.36.0-wmf.19
- dev-wmf/1.36.0-wmf.18
- dev-wmf/1.36.0-wmf.16
- dev-wmf/1.36.0-wmf.17
- dev-wmf/1.36.0-wmf.15
- dev-wmf/1.36.0-wmf.14
- dev-wmf/1.36.0-wmf.13
- dev-wmf/1.36.0-wmf.12
- dev-wmf/1.36.0-wmf.11
- dev-wmf/1.36.0-wmf.10
- dev-wmf/1.36.0-wmf.9
- dev-wmf/1.36.0-wmf.8
- dev-wmf/1.36.0-wmf.7
- dev-wmf/1.36.0-wmf.6
- dev-wmf/1.36.0-wmf.5
- dev-wmf/1.36.0-wmf.3
- dev-wmf/1.36.0-wmf.4
- dev-wmf/1.36.0-wmf.1
- dev-wmf/1.36.0-wmf.2
- dev-wmf/1.35.0-wmf.41
- dev-wmf/1.35.0-wmf.40
- dev-wmf/1.35.0-wmf.39
- dev-wmf/1.35.0-wmf.38
- dev-wmf/1.35.0-wmf.37
- dev-wmf/1.35.0-wmf.36
- dev-wmf/1.35.0-wmf.35
- dev-wmf/1.35.0-wmf.34
- dev-wmf/1.35.0-wmf.31
- dev-wmf/1.35.0-wmf.32
- dev-wmf/1.35.0-wmf.999
- dev-wmf/1.35.0-wmf.30
- dev-wmf/1.35.0-wmf.28
- dev-wmf/1.35.0-wmf.27
- dev-wmf/1.35.0-wmf.26
- dev-wmf/1.35.0-wmf.25
- dev-wmf/1.35.0-wmf.24
- dev-wmf/1.35.0-wmf.23
- dev-wmf/1.35.0-wmf.22
- dev-wmf/1.35.0-wmf.21
- dev-wmf/1.35.0-wmf.20
- dev-wmf/1.35.0-wmf.19
- dev-wmf/1.34.0-wmf.18
- dev-wmf/1.35.0-wmf.18
- dev-wmf/1.35.0-wmf.16
- dev-wmf/1.35.0-wmf.15
- dev-wmf/1.35.0-wmf.14
- dev-wmf/1.35.0-wmf.11
- dev-wmf/1.35.0-wmf.10
- dev-wmf/1.35.0-wmf.8
- dev-wmf/1.35.0-wmf.5
- dev-wmf/1.35.0-wmf.4
- dev-wmf/1.35.0-wmf.3
- dev-wmf/1.35.0-wmf.2
- dev-wmf/1.35.0-wmf.1
- dev-REL1_34
- dev-wmf/1.34.0-wmf.25
- dev-wmf/1.34.0-wmf.24
- dev-wmf/1.34.0-wmf.23
- dev-wmf/1.34.0-wmf.22
- dev-wmf/1.34.0-wmf.21
- dev-wmf/1.34.0-wmf.20
- dev-wmf/1.34.0-wmf.19
- dev-wmf/1.34.0-wmf.17
- dev-wmf/1.34.0-wmf.16
- dev-wmf/1.34.0-wmf.14
- dev-wmf/1.34.0-wmf.15
- dev-wmf/1.34.0-wmf.13
- dev-wmf/1.34.0-wmf.11
- dev-wmf/1.34.0-wmf.10
- dev-wmf/1.34.0-wmf.8
- dev-wmf/1.34.0-wmf.7
- dev-wmf/1.34.0-wmf.6
- dev-wmf/1.34.0-wmf.5
- dev-wmf/1.34.0-wmf.3
- dev-wmf/1.34.0-wmf.4
- dev-wmf/1.34.0-wmf.1
- dev-wmf/1.33.0-wmf.25
- dev-wmf/1.33.0-wmf.24
- dev-REL1_33
- dev-wmf/1.33.0-wmf.22
- dev-wmf/1.33.0-wmf.23
- dev-wmf/1.33.0-wmf.21
- dev-wmf/1.33.0-wmf.20
- dev-wmf/1.33.0-wmf.19
- dev-wmf/1.33.0-wmf.18
- dev-wmf/1.33.0-wmf.17
- dev-REL1_32
- dev-REL1_30
- dev-REL1_29
- dev-REL1_28
- dev-REL1_27
- dev-REL1_26
This package is not auto-updated.
Last update: 2024-10-30 10:34:57 UTC
README
Extension to Wikibase Repository that performs constraint checks.
Installation
-
Clone
WikibaseQualityConstraints
inside theextensions/
directory of your MediaWiki installations.cd .../extensions/ git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/WikibaseQualityConstraints
-
Install dependencies. The simplest way is to set up composer-merge-plugin and then run
composer install
in the MediaWiki base directory; alternatively, you can runcomposer install
inside theWikibaseQualityConstraints
directory. -
Load the extension.
wfLoadExtension( 'WikibaseQualityConstraints' );
-
Run
php maintenance/update.php --quick
. -
Configure the extension. You can find the configuration settings with documentation in
extension.json
. (Note that the variable name forLocalSettings.php
always begins withwg
, e. g.$wgWBQualityConstraintsClassId
for theWBQualityConstraintsClassId
setting.)-
Specify the entity IDs of entities that are used to define constraints. See the “Data import” section for an automatic way to do this.
-
If you have one or more SPARQL endpoints, configure the primary endpoint in
WBQualityConstraintsSparqlEndpoint
, and any additional endpoints inWBQualityConstraintsAdditionalSparqlEndpoints
. -
Alternatively, to check “format” constraints without running a full SPARQL server, you can use the minisparql server.
-
-
Run
php maintenance/run.php WikibaseQualityConstraints:ImportConstraintStatements.php
.
Client-side script
The extension includes a client-side script that checks constraints on entity pages and displays violations on statements. It is loaded by default for all logged-in users; anonymous users can load it on a page by entering the following code into the web console:
mw.loader.load( 'wikibase.quality.constraints.gadget' );
Data import
For local development, it’s easiest to import some data from Wikidata.
You can use the ImportConstraintEntities
maintenance script script to do this;
it will import all the required entities from Wikidata that don’t exist in your local wiki yet
and then print a config snippet which you can append to your LocalSettings.php
.
# working directory should be the MediaWiki installation folder, i.e. where LocalSettings.php is php maintenance/run.php WikibaseQualityConstraints:ImportConstraintEntities.php | tee -a LocalSettings.php
(The new entities will not show up in your wiki’s recent changes until they have been processed in the job queue;
try running the maintenance/runJobs.php
script if it doesn’t happen automatically.)
Running the tests
PHP
There are two ways to run the tests of this extension:
-
Using the included configuration file:
# from the MediaWiki installation folder composer phpunit -- -c extensions/WikibaseQualityConstraints/phpunit.xml.dist
This creates test coverage reports (in
tests/coverage/
andbuild/logs/clover.xml
) and is therefore fairly slow. -
Without the configuration file:
# from the MediaWiki installation folder composer phpunit:entrypoint extensions/WikibaseQualityConstraints/tests/phpunit/
This runs the tests without coverage report and is therefore much faster.
Javascript
You can run the tests, combined with linting and few other tools for asserting code quality by
# from this extension's folder npm install grunt test
Adding a new constraint type
To add a new constraint type, the following steps are necessary:
- Define the constraint checker class.
- It should be defined in a new file in
src/ConstraintCheck/Checker/
, named after the class name. It should be in theWikibaseQuality\ConstraintReport\ConstraintCheck\Checker
namespace. - The class name should follow the constraint type name (in English), ending in “Checker”.
- The class must implement the
ConstraintChecker
interface. - It should have at least the following class-level documentation comment:
/** * @author YOUR NAME HERE * @license GPL-2.0-or-later */
- Any services you need (
Config
,EntityLookup
, …) should be injected as constructor parameters. - If the constraint has parameters,
add support for parsing them to
ConstraintParameterParser
(add a config setting for the associated property inextension.json
and a method to parse the parameter inConstraintParameterParser
), and then add tests for them inConstraintParameterParserTest
. This should be done in a separate commit.
- It should be defined in a new file in
- Define new messages (at least a violation message for the constraint type).
- Define the message in
i18n/en.json
. A violation message should have a key likewbqc-violation-message-constraintType
. - Document the message in
i18n/qqq.json
. Use the same message key, and insert the documentation in the same location where you also added the message inen.json
(that is,en.json
andqqq.json
should contain message keys in the same order).
- Define the message in
- Add a configuration setting for the constraint type item ID.
- Configuration settings are defined in
extension.json
, as members of theconfig
object. - It should be added right after the current last
…ConstraintId
entry. - It should be named after the constraint type item’s English label,
following the pattern
WBQualityConstraints…ConstraintId
. - The default value should be the item ID on Wikidata, so that no extra configuration is required for Wikidata and importing the constraint type item (see “Data import” section) works.
- The first part of the description can be copied from similar settings, the rest should contain a short description of the constraint type.
- The ID can always be public (
"public": true
).
- Configuration settings are defined in
- Register the new constraint type checker.
- In
ConstraintCheckerServices.php
, add a constant likepublic const …_CHECKER = 'WBQC_…Checker';
at the end of the list of constants. The value should be'WBQC_'
followed by the class name, and the constant name should be the class name converted to all caps separated by underscores. - Also in
ConstraintCheckerServices.php
, add a method like/** * @param MediaWikiServices|null $services * @return ConstraintChecker */ public static function get…Checker( MediaWikiServices $services = null ) { return self::getService( $services, self::…_CHECKER ); }
at the end of the class. - In
ServiceWiring-ConstraintCheckers.php
, append a new function likeConstraintCheckerServices::…_CHECKER => function( MediaWikiServices $services ) { return new …Checker( // injected services ); },
to the array of services. - In
ServiceWiring.php
, append a new entry like$config->get( 'WBQualityConstraints…ConstraintId' ) => ConstraintCheckerServices::get…Checker( $services ),
to the$checkerMap
array in theDELEGATING_CONSTRAINT_CHECKER
function. - In
ServicesTest.php
, append a new entry like[ …Checker::class ],
to the array inprovideConstraintCheckerServiceClasses()
.
- In
- Add tests for the new constraint checker.
- The test class name should be the same as the checker class name,
with an additional suffix
Test
(i. e.,…CheckerTest
). - The test class should be placed somewhere in
tests/phpunit/Checker/
, either in the most suitable subdirectory or directly in that directory if none of the subdirectories are suitable. (The division into subdirectories there is dubious anyways, and we may get rid of it in the future.) - It should have at least the following class-level documentation comment:
/** * @covers WikibaseQuality\ConstraintReport\ConstraintCheck\Checker\…Checker * * @group WikibaseQualityConstraints * * @author YOUR NAME HERE * @license GPL-2.0-or-later */
- It should have at least one test for compliance with a constraint,
one test for a constraint violation,
one test for behavior on a deprecated statement,
and one test for the
checkConstraintParameters
method. - Use the
ResultAssertions
trait’s methods to check constraint check results. - Use the
NewItem
andNewStatement
builders to construct test data. - If the checker uses a
Config
, use theDefaultConfig
trait. - If the constraint has parameters,
add methods for them to the
ConstraintParameters
trait and use it in the tests. - You can copy+paste a
getConstraintMock
function from one of the existing tests, adjusting thegetConstraintTypeItemId
mocked return value. (Hopefully we’ll improve this in the future.)
- The test class name should be the same as the checker class name,
with an additional suffix
- Update the tests for
DelegatingConstraintChecker
.- In
DelegatingConstraintCheckerTest
, add an entry for your constraint type to the$constraints
array inaddDBData()
. - The
constraint_guid
should beP1$
, followed by a new UUID (e. g.cat /proc/sys/kernel/random/uuid
orjournalctl --new-id128
). - The
pid
should be1
. (Not'1'
!) - The
constraint_type_qid
should be$this->getConstraintTypeItemId( '…' )
, where…
is just the…
part of theWBQualityConstraints…ConstraintId
extension.json
config key. - The
constraint_parameters
should be a valid JSON serialization of constraint parameters. If the constraint type doesn’t have any parameters, you can pass{}
, otherwise there should ideally be methods to create the parameters in theConstraintParameters
trait so that you can usejson_encode( $this->…Parameter( … ) )
(perhaps witharray_merge
if there are multiple parameters).
- In
- Ask someone with grafana-admin access to update the “constraint types” panel in the wikidata-quality board to add the new constraint type.
Adding a new allowed entity type
- Start by adding an Item reference to
extension.json
. For example:"WBQualityConstraintsMediaInfoId": { "value": "Q3898244", "description": "The item ID of the 'MediaInfo' item, which represents the 'mediainfo' entity type for 'allowed entity types' constraints.", "public": true }
- The next step takes place inside
src/ConstraintCheck/Helper/ConstraintParameterParser.php
. The new allowed entity type should be added to the switch/case within the methodparseEntityTypeItem()
. Don't forget to add it to the default case as well! - To be able to test the newly added allowed entity type locally, please perform the steps described in section "Data import".
Chore: Dependency Updates
NodeJS
You can see which dependencies have new releases by first running npm ci
to ensure your local dependencies are up-to-date, and then running npm outdated
.
- grunt-eslint no longer supports "flat" eslint config files (i.e.
.eslintrc.json
) since version 25.0.0 because of changes since eslint 9 (see issue #176). See T364065 for progress with our eslint 9 migration. - grunt-stylelint switched to Stylelint 16+ in version 0.20.0, which no longer supports stylelint-stylistic, depended upon by stylelint-config-wikimedia. See issue #225
PHP
Running composer update
and composer outdated --direct
will give you a list of any outdated PHP dependencies. There are currently no notes or restrictions on package updates.