Exploring CSS property definitions

Reffy and CSS specifications

Reffy is a specification exploration tool that Dominique Hazaël-Massieux and I developed as a side project during W3C Geek Week a couple of years ago to explore cross-dependencies of JavaScript APIs specifications. Reffy crawls, parses, analyzes, and reports on potential anomalies that specifications may have. Reffy reports are published on a daily basis and help detect issues such as invalid WebIDL content or missing normative references. The dump of the WebIDL content defined in each specification is now also used to create WebIDL tests in the Web Platform Tests effort.

Reffy was essentially restricted to specifications that define some WebIDL content. For Geek Week this year, Dominique and I wondered whether we could extend Reffy to support CSS specifications:

1. Could we extract all CSS property/descriptor definitions from specifications automatically?
2. Could we create a useful syntax tree out of the CSS property/descriptor value definitions automatically?
3. Would it reveal potential issues in CSS specs? Would it be useful to improve the quality of the specifications, to automate the creation of tests, or to create/maintain documentation?

Outcomes

We identified and added about 100 CSS specifications to the list of specifications crawled by Reffy, looking at specifications published as W3C Technical reports, as well as Editor's Drafts from the CSS Working Group, the FX Task Force and the Houdini Task Force.

Reffy can now successfully extract all CSS property/descriptor definitions from these specifications (544 CSS properties as of today), and parse all value definitions that follow the Value Definition Syntax.

A number of issues have been raised against CSS specifications along the way (see CSS Value Definition Syntax issues for details), notably to report invalid value definitions per the syntax and editorial updates that would help automate the extraction and parsing of definitions. The Value Definition Syntax was most likely not created with automated parsing in mind. We could not spot places where definitions were really ambiguous for human beings, but the syntax could perhaps be improved to ease automated processing and prevent any misunderstanding.

Comparing the information we extracted with MDN data, we detected and reported some outdated info on MDN related to scroll-snap properties and offset-* properties.

Possible next steps

We will continue to investigate the integration with MDN data. That data is currently maintained manually by the community. The possibility to automate part of this process would improve accuracy.

We did not have enough time to run a deep analysis of the resulting syntax tree. Such an analysis might reveal further specification issues. On top of improving the quality of CSS specifications, it should be easy to create a CSS property explorer similar to WebIDLPedia (this one being restricted, as its name suggests, to the exploration of WebIDL used across specifications) out of the list of properties extracted.

In specifications that define JavaScript APIs, WebIDL definitions can be used to create interface tests automatically, using idlharness.js. Similar tests can probably be created for CSS. We confess being more familiar with JavaScript APIs though. It may be that parsing CSS is not a major source of interoperability issues. Would such tests be as useful as WebIDL ones?

The extraction and parsing currently only works for CSS properties and descriptors. It could be interesting to cover at-rules and selectors as well. This may be more challenging though, as actual prose seems to prevail in that area, with fewer parseable code definitions.