Proposal: General `notes` section for BCD

MDN
#1

I’d like to propose that we support the use of a "notes" section at the topmost level of a BCD file. This would let us provide general notes about the support level or compatibility of an API, which would be especially useful for newer APIs or those where browsers have substantial implementation differences that need to be considered.

For instance, at this time, the WebRTC statistics APIs are implemented wildly differently across the browsers. By the spec, the RTCRtpSender.setParameters() method’s input object is of type RTCRtpSendParameters, but Firefox instead uses the RTCRtpParameters type (which by the spec is the parent class of RTCRtpSendParameters.

One of the members of the RTCRtpSendParameters class is, in Firefox, instead found in RTCRtpParameters. Chrome, on the other hand, implements RTCRtpSendParameters and RTCRtpEncodingParameters, but the properties are strewn around among them so that many are not in the right place. And of course, all the browsers have properties they don’t support at all.

As a result, this dictionary deserves to have a note on it along the lines of "Due to the ongoing development of browser support for WebRTC, browser handling of WebRTC parameter objects varies widely, with properties sometimes defined in different dictionaries than described. These are noted here, but be sure to watch out for them."

Not only could this note then be used on MDN, but it would be helpful for others using our data, because they could get this helpful information for free along with the rest of the data.

All it would take is allowing something like this:

{
  "api": {
    "RTCRtpEncodingParameters": {
      "__compat": {
        "mdn_url": "https://developer.mozilla.org/docs/Web/API/RTCRtpEncodingParameters",
        "notes": "Due to the ongoing development... etc."
...

Thoughts?

1 Like
#2

This was an interesting write-up, @sheppy. Thanks for bringing this up!

My initial impression is that if this sort of thing were to exist, it ought to be a "notes" section of "status" (i.e., alongside "experimental", "standard_track", and "deprecated"). But I’m conflicted about whether it ought to be part of the schema. I’ve got questions. :slight_smile:

Specifically, I’m wondering whether the schema can already handle a case like the one you’ve described:

One of the members of the RTCRtpSendParameters class is, in Firefox, instead found in RTCRtpParameters . Chrome, on the other hand, implements RTCRtpSendParameters and RTCRtpEncodingParameters , but the properties are strewn around among them so that many are not in the right place. And of course, all the browsers have properties they don’t support at all.

If I understand correctly, there’s some BCD feature like api.RTCRtpSendParameters.some_member. But in Firefox, the equivalent feature is implemented as the non-standard api.RTCRtpParameters.non_standard_member feature. Now, if I were trying to add this to BCD, I’d add the feature api.RTCRtpParameters.non_standard_member with:

  • only Firefox as having any non-false "version_added" value
  • a note on Firefox’s support saying that it’s an implementation of api.RTCRtpSendParameters.some_member
  • The "standard_track" value set to false

Right now (as in, before any schema change), I’d probably consider adding a note to Firefox’s ("version_added": false) support of api.RTCRtpSendParameters.some_member saying, more or less, "See api.RTCRtpParameters.non_standard_member".

Would this capture the relationship between api.RTCRtpSendParameters.some_member, api.RTCRtpParameters.non_standard_member, and the specification? Or would you want the notes field in addition to this?

More broadly, do you imagine that a notes field would be routinely used? Or only when an API got sufficiently fragmented? If it’s not for routine use, what sort of criteria would you use to distinguish noteworthy APIs from ordinary APIs?

1 Like
#3

Another way to do that would be to do what’s already done for some APIs (where it’s marked as supported on the child interface with a note stating that it’s implemented on the parent interface).

#4

Yes, those things cover the individual items. But I’m talking about an overall note that says “This API is undergoing a substantial round of changes right now, blah blah” or “The implementation in browser X is substantially different and special attention is needed when doing X”. That kind of thing. General notes about the overall state of the API that can be helpful when deciding whether or not to use an API, or how much someone wants to rely on it.