Can we remove syntaxes from mdn/data?

[wbamberg]

MDN doesn't use the formal syntax parts of mdn/data any more. Instead, we use data directly extracted from the specs via webref/css.

However, maintainers still have to add something there, and the linter checks for it: https://github.com/mdn/data/blob/6675982d35162544cc30a6c7a478944d529bd587/css/properties.schema.json#L302-L316.

Can we remove:

• the "syntax" property from properties.json, at-rules.json, selectors.json, etc
• the "syntaxes.json" file

?

As far as I know this would have no impact on MDN. It might have an impact on other users of mdn/data. For almost 2 years we have had a note at the top of the README, informing users of our plans to deprecate the repo and asking for feedback: mdn/data@23c544e.

The obvious alternative for dependents is to use webref/css as well, and it would be good to know what the obstacles to that would be.

[teoli2003]

I think that from mdn/content and MDN Web Docs perspective, we can remove it (and we should).

I think that we may have other consumers here. I guess the README would not be enough.

Maybe we should make a last "announcement", something like: "On July 1st, a new major version of mdn/data will be out, without the syntax…".

Also, we should likely announce the end of syntax in mdn/data to every contributor who updates them. Among them are likely the users of mdn/data (that likely upstream errors reported to them).

But, yes, we should remove syntax from mdn/data, it is painful to maintain and useless.

[chrisdavidmills]

This would be great. As someone who documents many new CSS features, I can say that figuring out adding the syntax properly, with all the levels of nested types, etc., takes way longer than the rest of the data put together.

[wbamberg]

csstree/csstree#244 indicates that https://github.com/stylelint/stylelint depends on mdn/data syntaxes, via css-tree.

[teoli2003]

Should we open an issue in csstree?

We can tell them we plan to remove syntaxes (because they are poorly maintainable and maintained) and that mdn/content has replaced mdn/data with w3c/webref instead with a link to the macro where we used it).

[estelle]

This discussion was discussed synchronously during the #writing-docs meeting held on April 16, 2024. Here are the (slightly edited for clarity) minutes from that portion of the meeting:

Question: Can we remove syntaxes from mdn/data?

• MDN still uses stuff in mdn/data. This is just about the syntax within that.
• No, not yet. CSS-tree uses it, and style-lint uses CSS-tree. We should talk to the maintainers (Roman) about it.
• Alternative: have a build step when mdn/data gets released that adds syntaxes from webref/css. But that is a project.
• It’s not the right the way of doing it, but it is a way to avoid future work. It prevents discrepancies and PRs that need to be reviewed.
  mdn/data’s linter requires properties to have a top-level syntax entry. A PR was merged to appease the linter, but it doesn’t include all the sub-syntax, so it’s not complete.
• Get people to stop using mdn/data and start using webref only. But webref does have issues, like non-standard properties are not included, so not valid for all pages, but in general it’s pretty reliable.

ANSWER: not yet.

SOLUTION: 2 options, either of which would be a project:

• Ask dependents to stop using mdn/data, and start using webref instead. Then release a breaking version of mdn/data which drops the syntaxes.
• Update mdn/data to use webref for syntaxes, so dependents can go on as before, and the change is invisible to them.

[teoli2003]

Hi all!

The conclusion of all these discussions is:

• as much as we want to eliminate this part of mdn/data, we can't just remove it from mdn/data.
• both potential solutions require a substantial amount of work, and we don't have the time to do any of them in the foreseeable future (Read: we have many more projects with higher impact lined up).

So we have to shelve the idea of removing syntaxes from mdn/data, as much as it breaks our hearts. We will be sure to revisit this periodically, and maybe there will be opportunities again to fix this problem in the future.

Thank you all for the insight.