Guidance about serialization

[LeaVerou]

This mostly applies to CSS, but perhaps to HTML too?

We often have long debates in CSS WG about how things should serialize, but there is no clear list of use cases and tradeoffs to consider when making these decisions, and I have recently realized that there is some confusion about serialized values vs computed values. Since there is a principle about how to choose computed values, I think one about serialization would be in scope too.

[annevk]

Everything with a parser and serializer could probably use some principles. One desirable property is that if you serialize X, then parse the result, it better be identical to X (minus object identity). (This isn't true for HTML unfortunately as it's rather broken in various ways, but should be true for URLs and MIME types.)

And I guess with CSS a question is how much of the expressiveness of the syntax needs to be preserved in the model (and the eventual serialization). My personal preference is that everything that is not important for the model is not preserved, which means that whitespace and such end up disappearing. This is not necessarily great for editors, but they're not the target of the system either (and can have their own implementation that does preserve these things).

[dbaron]

For what it's worth, the guidance about computed value is about the value's underlying representation or what it is conceptually, not about how it serializes. So there's a little bit of difference.

At one point I did write down some principles for CSS serialization, such as (perhaps stated a bit differently):

• serialize to the older (or most-accepted) syntax when the syntax has evolved over time
• serialize to the shorter form when there's a choice and the form originally written isn't being preserved

A bunch of the debates are about which aspects of what is written to preserve, though, and I don't have a good principle for that...

[atanassov]

Reasoning over the different users of serialization results, it seems difficult to add guidance that is general enough so it applies to all of them. However, there are certainly patterns we should try.

Some obvious constituencies or serialization results we should consider are:

• Users - often reading result of serialization to validate expectations or learn
• Tools - use these results to enrich dev experience, provide auditing, automation, testing etc.
• Web platform API - serialized results passed as input to other (or the same) API of the platform

There are also specific expectations that can be language specific - does empty space matter, numeric precision, structure format (ex. CSS grid structure) etc. In most of these cases it makes sense that we should expect that serialization results:

• should be intuitive (this is rather weakly defined expectation but often cited in discussions)
• should not add to error accumulation - taking the serialized output of an API and feeding it back to the same API in a loop should be predictable and ideally error free (at least for simple API)

So perhaps we can start with this higher level guidance and then become more specific to the user/use case or language.

[LeaVerou]

There's a label for issues relating to serialization in the CSSWG repo, so that could help whoever is tasked with drafting this guidance: https://github.com/w3c/csswg-drafts/issues?q=is%3Aissue+sort%3Aupdated-desc+label%3A%22topic%3A+serialization%22+