[Schema] ID proposal

[teoli2003]

Hi all!

Our schema must be able to identify different features. We need to agree on the way to identify these.

We have a few constraints: we would like not to rely on the file structure we choose, as it is unclear how it will be in the future (1 large file, numerous small files, or even in a DB).

For the moment, the experiments showed 2 kind of file structures that we are using:

• 1 file for a large set of features (like WebExtensions). We privileges here the simplicity to do batch changes.
• 1 file for each interface for APIs, or for each property for CSS. We privileges here the simplicity to do individual changes.

We don't know which of these file structures will be the best in the long term, so we need to have a identifier that works in both cases (without to much added complexity).

The proposal is the following: we put the id inside the json:

E.g. css.properties.line-height would be the id for the line-height properties and written:

{"css": {
"properties": {
"line-height" : {...}
}

E.g
{"WebGL2RenderingContext": {
"api": {
"WebGL2RenderingContext": {...},
"WebGL2RenderingContext.beginQuery": {...},
...
}
}

To indicate the bottom of the id, the idea would be to use a special keyword ("__compat" or similar) to indicates that what follows is the compat information.

What do you think of this idea?

[SebastianZ]

You say that the ID will be stored within the JSON, though in the examples they are missing. Also, it's unclear to me, what you mean with "bottom of the ID".

Sebastian

[wbamberg]

1 file for a large set of features (like WebExtensions). We privileges here the simplicity to do batch changes.

This isn't the main reason WE has one massive file. The main reason is that I want to be able to generate pages like this: https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Browser_support_for_JavaScript_APIs. It's not clear to me how I could do this if the compat data was split up into lots of individual files.

I don't think I really understand this proposal either. At the moment WE JSON looks something like this:

{
  "i18n": {
    "getUILanguage": {
        ...[compat data]
    },
    "LanguageCode": {
       ...[compat data]
    },
   ...[more i18n APIs]
  },
  "cookies": {
    "getAllCookieStores": { 
       ...[compat data]
    },
...[etc]

So I guess the "ID" would be i18n/getUILanguage etc., and all i18n APIs are properties of i18n: this makes it easy for code to do "get compat data for i18n", to build tables like https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/i18n#Browser_compatibility.

How would this differ under the current proposal, and how would I build these aggregate tables?

[teoli2003]

@SebastianZ: sorry I've not been clear enough. The id of line-height would be css.properties.line-height.

@wbamberg: the proposal is not fundamentally different than the one of WE. The main difference is that the ID will be unique through all the files, being one, or being multiple. This means that the id must be unique not only inside a file, but throughout all the files. This is enforces at review time, helped by a simple id scheme.

The possibility to use one large file, or several small files, is left to the curator of each area. Ideally, in the future macros will use a DB and the notion of file will disappear.

In the case of WebExtensions, there will still be one large file, with similar ids. The ids will be a bit longer.

Instead of: i18.cookies, it will be webextensions.i18.cookies (or similar):
{
"webextensions": {
"i18n": {
"getUILanguage": {
...[compat data]
},
"LanguageCode": {
...[compat data]
},
...[more i18n APIs]
},
"cookies": {
"getAllCookieStores": {
...[compat data]
},
...[etc]
}
}

That way we can easily merge different files, or separate them as the id scheme is universal throughout all browser compat data.

[wbamberg]

Thanks for the clarification @teoli2003 ! I'm +1 on this proposal now.

[SebastianZ]

@SebastianZ: sorry I've not been clear enough. The id of line-height would be css.properties.line-height.

Ah, I see. You call the JSON path down to an entry the "ID". 😄 With your description I would have expected a key "id" containing "css.properties.line-height".

So, yes, your proposal is fine for me.

Sebastian

[jwhitlock]

I like the proposal.

The _compat element is vital for code to be able to walk the tree of data, so that the data walker knows it should expect compatibility data, rather than look for new child elements. I think you'll need to describe in more detail how that is used.

If it is just "_compat": true, you can't mix ID and compatibility data. For example, you can't add support information to "webextensions.i18n", only to "webexetensions.i18n.getUILanguage". You'll have to use a trick like "webextensions.i18n.basic_support" if you want to talk about support in a more general way:

{
  "webextensions": {
    "i18n": {
      "basicSupport": {
        "_compat": true,
        [generic, caniuse-style compat data]
      },
      "getUILanguage" {
        "_compat": true,
        [specific, MDN-style compat data]
      }
    }
  }
}

Alternatively, you compatibility data could appear under the _compat element, so you know there is compat data attached to that node.

{
  "webextensions": {
    "i18n": {
      "_compat": [generic, caniuse-style compat data],
      "getUILanguage" {
        "_compat": [specific, MDN-style compat data],
      }
    }
  }
}

Update: Issue #114 specifies the second form, that data appears under the __compat element.

[Elchi3]

I think we've come to an agreement here and the new schema reflects that. Please open new issues if you have new feedback on identifiers.