support_statement syntax

[wbamberg]

From looking at code that builds tables from the compat data, I had some questions about how we should use support_statement objects (https://github.com/mdn/browser-compat-data/blob/master/compat-data.schema.json#L47), especially in the case where it consists of an array of simple_support_statement objects.

To recap:

• support_statement can be either a single simple_support_statement, or an array of simple_support_statements.

• each simple_support_statement must contain version_added and may also contain version_removed.

• version_added and version_removed may be (1) a boolean, (2) null, or (3) a version string.

I think of each simple_support_statement as defining a range of versions during which some compat condition holds (like, it's supported, or behind a pref, or prefixed, or...). (I'm not sure that's a correct way to think of if, but if so...)

(1) Should it be OK for ranges to overlap:

35 — 49
47 - 53

(2) Should it be OK for ranges to include gaps:

 35 — 42
 47 - 53

If these are OK, what would constructs like that mean, and how can we present them in a comprehensible way?

(3) Do we assume that the ranges are ordered? If so, should we validate the data for it?

47 - 53  // should we be able to handle this?
35 — 47

(4) We allow version_added and version_removed to accept special imprecise values, true, false, and null. What does it mean when we use one of these imprecise values in combination with version-defined ranges?

35 — ?   // what does this mean?
47 - 53

35 — Yes   // or this?
47 - 53

35 — No   // or this?
47 - 53

The simplest, most restrictive, thing to say would be something like this:

• you can only use true, false, and null in the case that it is the only simple_support_statement. If you supply an array of simple_support_statement objects, you must supply actual versions in version_added and version_removed

• if you supply an an array of simple_support_statement objects, they must be ordered

• if you supply an an array of simple_support_statement objects, only the last one is allowed to include version_removed: the others are implicitly ended by the start of the next one.

I don't know if this would rule out too many useful expressions. But I do think that if we allow particular constructs we should be able to say what they mean.

[stephaniehobson]

I think this conversation is a bit bigger than adding and removing features. Here is some data to test our assumptions against:

16

• feature added behind a flag

21

• footnote: only allowed in sandboxed iframes

22

• feature is restricted to secure contexts
• feature no longer restricted to sandboxed iframes

23

• feature is no longer behind a flag

25

• feature removed

The easiest and most understandable approach I see is for each support statement to be a complete snapshot of the browser's support at that point in time. Which means the support statements for the above would require versions 21 and 22 to also identify that they are behind a flag and for 23 to identify that it must be in a secure context.

I agree simple_support_statements should be ordered (OMG yes)

I think we should allow true/false/null if it is the only or first in an array (so the above example could also have a false in the list prior to version 16)

[Elchi3]

There are a lot of things in this issue and we decided to resolve them once we have more experience and use cases. I want to bring a case to the table that illustrates that overlapping versions are OK.

(1) Should it be OK for ranges to overlap

Imo, yes, given e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/includes

I would translate it to this structure:

"firefox": [
  {
    "alternative_name": "contains",
    "version_added": "18",
    "version_removed": "48"
  },
  {
    "version_added": "40"
  }
],

This disagrees with

if you supply an an array of simple_support_statement objects, only the last one is allowed to include version_removed: the others are implicitly ended by the start of the next one.

For compatibility, both names were supported for a while, so the ranges overlap.

(2) Should it be OK for ranges to include gaps:

I haven't seen anything like this yet, if you encounter this, let us know here.

(3) Do we assume that the ranges are ordered?

I think ordering makes a lot of sense. My feeling is that the earliest version_added should be first.

[Elchi3]

I'm not sure there is anything actionable left here.
The redesigned tables, when encountering an array of support statements, will use the first statement to display in the cell and then have the historical or extra support statements in a collapsed section. I think that's quite nice as it shows you the most relevant support version first and if you need the details you can expand and see other support ranges with limitations like prefixes etc.