Spartacus is a checker used at W3C to validate the compliance of Technical Reports with publication rules.
Spartacus is a Node.js application, distributed through npm. Alternatively, you can clone the repository and run:
$ npm install -d
In order to get all the dependencies installed. Naturally, this requires that you have a reasonably recent version of Node.js installed.
Currently there is no shell to run Spartacus. Later we will add both Web and CLI interfaces based on the same core library.
$ W3C_API_KEY="<YOUR W3C API KEY>" npm start [PORT]
Spartacus relies on the W3C API to run a few checks. You will need to provide your key in an environment variable W3C_API_KEY
Meaning of positional parameters:
PORT
: where Spartacus will be listening for HTTP connections. (Default80
.)
Examples:
$ W3C_API_KEY="<YOUR W3C API KEY>" npm start
$ W3C_API_KEY="<YOUR W3C API KEY>" npm start 3001
Set the environment variable DEBUG
to run in debug mode instead:
$ DEBUG=true W3C_API_KEY="<YOUR W3C API KEY>" npm start
This modifies the behaviour of certain parts of the application to facilitate debugging.
eg, CSS and JS resources will not be loaded in their minified/uglified forms
(the web UI will load bootstrap.css
, bootstrap.js
and jquery.js
instead of bootstrap.min.css
, bootstrap.min.js
and jquery.min.js
).
If Spartacus is not going to be served from the root directory of a domain, or if it will be served through a proxy,
set also BASE_URI
pointing to the public root URI of Spartacus; eg
$ BASE_URI=https://spec-store.com/check/ W3C_API_KEY=deadbeef npm start
$ BASE_URI=/hostname/can/be/omitted/ W3C_API_KEY=deadbeef npm start 88
Testing is done using mocha. Simply run:
$ W3C_API_KEY="<YOUR W3C API KEY>" mocha
from the root and you will be running the test suite. Mocha can be installed with:
$ npm install -g mocha
Some of the tests can on occasion take a long time, or fail outright because a remote service is unavailable. To work around this, you can set SKIP_NETWORK:
$ SKIP_NETWORK=1 W3C_API_KEY="<YOUR W3C API KEY>" mocha
The interface you get when you require("spartacus")
is that from lib/validator
. It returns a
Spartacus
instance that is properly configured for operation in the Node.js environment
(there is nominal support for running Spartacus under other environments, but it isn't usable at this time).
(See also the REST API.)
This method takes an object with the following fields:
url
: URL of the content to check. One ofurl
,source
,file
, ordocument
must be specified and if several are they will be used in this order.source
: AString
with the content to check.file
: A file system path to the content to check.document
: A DOMDocument
object to be checked.profile
: A profile object which defines the validation. Required. See below.events
: An event sink which supports the same interface as Node.js'sEventEmitter
. Required. See below for the events that get generated.
This method eventually extends this
with metadata inferred from the document.
Once the event end-all
is emitted, the metadata should be available in a new property called meta
.
The options
accepted are equal to those in validate()
, except that a profile
is not necessary and will be ignored (finding out the profile is one of the
goals of this method).
this.meta
will be an Object
and may include up to 15 properties described below:
profile
title
: The (possible) title of the document.docDate
: The date associated to the document.thisVersion
: URL of this version of the document.latestVersion
: URL of the latest version of the document.previousVersion
: URL of the previous version of the document (the last one, if multiple are shown).editorsDraft
: URL of the latest editor's draft.delivererIDs
: ID(s) of the deliverer(s); anArray
ofNumber
s.editorIDs
: ID(s) of the editor(s) responsible for the document; anArray
ofNumber
s.informative
: Whether the document in informative or notrectrack
: Whether the document in on REC track or notprocess
: The process rules link.sameWorkAs
: The previous shortlink if any.implementationFeedbackDue
: The implementation review date for CRsprReviewsDue
: The review date for PRsimplementationReport
: Implementation report link for CRs, PRs and RECs
If some of these pieces of metadata cannot be deduced, that key will not exist, or its value will not be defined.
This is an example of the value of Spartacus.meta
after the execution of Spartacus.extractMetadata()
:
{
"profile": "WD",
"title": "Title of the spec",
"docDate": "2016-2-3",
"thisVersion": "http://www.w3.org/TR/2016/WD-foobar-20160203/",
"latestVersion": "http://www.w3.org/TR/foobar/",
"previousVersion": "http://www.w3.org/TR/2015/WD-foobar-20150101/",
"editorsDraft": "http://w3c.github.io/foobar/",
"delivererIDs": [123, 456],
"editorIDs": [ 12345 ],
"informative": false,
"rectrack": true,
"process": "http://www.w3.org/2015/Process-20150901/" }
}
Similar to the JS API, Spartacus exposes a REST API via HTTP too.
The endpoint is <host>/api/
.
Use either url
or file
to pass along the document (neither source
nor document
are allowed).
Note: If you want to use the public W3C instance of Spartacus, you can replace <host>
with https://www.w3.org/pubrules
.
There are three GET
methods available.
Returns the version string, eg 1.5.3
.
Extract all known metadata from a document; see below for information about the return value.
Check the document (syntax).
Many of the options understood by the JS method validate
are accepted.
The special profile auto
is also available.
<host>/api/version
<host>/api/metadata?url=http://example.com/doc.html
<host>/api/validate?file=/home/me/docs/spec.html
<host>/api/validate?file=draft2.html&profile=WD&validation=simple-validation&processDocument=2015
Methods metadata
and validate
return a JSON object with these properties:
success
(boolean
): whether the operation succeeded, or not.errors
(array
): all errors found.warnings
(array
): all warnings.info
(array
): additional, informative messages.metadata
(object
): extracted metadata; see structure here.
If there is an internal error, the document cannot be retrieved or is not recognised, or validation fails, both methods would return HTTP status code 400
.
Also, in the case of validate
, success
would be false
and errors.length > 0
.
This is an example of a successful validation of a document, with profile auto
:
{ "success": true,
"errors": [],
"warnings":
[ "headers.ol-toc",
"links.linkchecker",
"links.compound",
"headers.dl" ],
"info":
[ "sotd.diff",
"structure.display-only",
"structure.display-only",
"structure.display-only",
"validation.wcag" ],
"metadata":
{ "profile": "WD",
"title": "Character Model for the World Wide Web: String Matching and Searching",
"docDate": "2016-4-7",
"thisVersion": "http://www.w3.org/TR/2016/WD-charmod-norm-20160407/",
"latestVersion": "http://www.w3.org/TR/charmod-norm/",
"previousVersion": "http://www.w3.org/TR/2015/WD-charmod-norm-20151119/",
"editorsDraft": "http://w3c.github.io/charmod-norm/",
"delivererIDs": [ 32113 ],
"editorIDs": [ 33573 ],
"rectrack": false,
"informative": false,
"process": "http://www.w3.org/2015/Process-20150901/",
"url": "https://www.w3.org/TR/2016/WD-charmod-norm-20160407/"
}
}
When the profile is given by the user (instead of being set to auto
), fewer items of metadata are returned.
metadata
returns a similar structure, where all values are empty arrays, except for the key metadata
which contains the metadata object.
Profiles are simple objects that support the following API:
- name: A
String
being the name of this profile. - rules: An
Array
of rule objects which are checked in this profile.
A profile is basically a configuration of what to check. You can load a specific profile from under
lib/profiles
or create your own.
Here follows the current hierarchy of profiles. Each profile inherits all rules from its parent profile. Profiles that are identical to its parent profile, ie that do not add any new rules, are marked too.
dummy
base
TR
WG-NOTE
FPWG-NOTE
(identical)
WG-NOTE-Echidna
IG-NOTE
FPIG-NOTE
(identical)
WD
WD-Echidna
FPWD
(identical)PR
PR-AMENDED
(identical)
CR
CR-AMENDED
(identical)CR-Echidna
FPCR
REC
REC-AMENDED
(identical)
REC-OBSOLETE
REC-RSCND
REC-SUPERSEDED
Submission
SUBM
MEM-SUBM
For a given checking run, the event sink you specify will be receiving a bunch of events as indicated below. Events are shown as having parameters since those are passed to the event handler.
start-all(profile-name)
: Fired first to indicate that the profile's checking has started.end-all(profile-name)
: Fired last to indicate that the profile's checking has completed. When you receive this you are promised that all testing operations, including asynchronous ones, have terminated.done(rule-name)
: Fired when a specific rule has finished processing, including its asynchronous tasks.ok(rule-name)
: Fired to indicate that a rule has succeeded. There is only oneok
per rule. There cannot also beerr
events but there can bewarning
events.err(error-name, data)
: Fired when an error is detected. Thedata
contains further details, that depend on the error but should feature amessage
field. There can be multiple errors for a given rule. There cannot also beok
events but there can bewarning
s.warning(warnings-name, data)
: Fired for non-fatal problems with the document that may nevertheless require investigation. There may be several for a rule.info(info-name, data)
: Fired for additional information items detected by the validator.metadata(key, value)
: Fired for every piece of document metadata found by the validator.exception(message)
: Fired when there is a system error, such as a File not found error.message
contains details about this error. All exceptions are displayed on the error console in addition to this event being fired.
Rules are simple modules that just expose a check(sr, cb)
method. They receive a Spartacus object
and a callback, use the Spartacus object to fire validation events and call the callback when
they're done.
The Spartacus object exposes the following API that's useful for validation:
$
. A jQuery-like interface to the document being checked.loader
. The loader object that loaded the content, which exposes the content'surl
andsource
if they are known.sink
. The event target on which to fire validation events.version
. The Spartacus version.checkSelector(selector, rule-name, cb)
. Some rules need to do nothing other than to check that a selector returns some content. For this case, the rule can just call this method with the selector and its callback, and Spartacus will conveniently take care of all the rest.norm(text)
. Returns a whitespace-normalised version of the text.getDocumentDate()
. Returns a Date object that matches the document's date as specified in the headers' h2.getDocumentDateElement()
. Returns the element that contains the document's date.