browser-compat-data What should the BCD path of the static Response.json() be?

There's a new static Response.json() method which will be in browsers sooner or later, and need to be added to BCD. Unfortunately, there's already a Response.prototype.json, and BCD doesn't have a way of distinguishing between these, both would have the path "api.Response.json".

What should we do? Options:

Hack around it with "api.Response.static_json" and hope this doesn't happen much.
Move the existing "api.Response.json" to "api.Response.prototype.json"
The above, but additionally do this rename for all instance methods/members, which is thousands.

@queengooborg thoughts, and how do we make a decision like this?

Jun 09 '22 06:06 foolip

Chrome Canary has Response.json now: https://crbug.com/1305358

Sep 18 '22 18:09 saschanaz

It would be a lot of work, but I think I now favor the option of adding "prototype" to the BCD path everywhere.

Sep 18 '22 20:09 foolip

But is json_static too ugly? We already have _event etc, so I think it's acceptable.

Sep 18 '22 22:09 saschanaz

I'm in favor of json_static or static_json -- I don't expect this to happen too often and I feel that reworking the entire structure for it is not worthwhile.

Sep 19 '22 00:09 queengooborg

I'd say if json_static would be the thing then all other static functions should be named same way. Not too many static functions are there, fortunately.

Sep 19 '22 02:09 saschanaz

There are 70 static functions in @webref/idl:

AbortSignal.abort
AbortSignal.timeout
AudioDecoder.isConfigSupported
AudioEncoder.isConfigSupported
BarcodeDetector.getSupportedFormats
BluetoothUUID.canonicalUUID
BluetoothUUID.getCharacteristic
BluetoothUUID.getDescriptor
BluetoothUUID.getService
Credential.isConditionalMediationAvailable
CropTarget.fromElement
CSSColorValue.parse
CSSNumericValue.parse
CSSStyleValue.parse
CSSStyleValue.parseAll
DeviceMotionEvent.requestPermission
DeviceOrientationEvent.requestPermission
DOMMatrix.fromFloat32Array
DOMMatrix.fromFloat64Array
DOMMatrix.fromMatrix
DOMMatrixReadOnly.fromFloat32Array
DOMMatrixReadOnly.fromFloat64Array
DOMMatrixReadOnly.fromMatrix
DOMPoint.fromPoint
DOMPointReadOnly.fromPoint
DOMQuad.fromQuad
DOMQuad.fromRect
DOMRect.fromRect
DOMRectReadOnly.fromRect
GeolocationSensor.read
HTMLScriptElement.supports
IDBKeyRange.bound
IDBKeyRange.lowerBound
IDBKeyRange.only
IDBKeyRange.upperBound
IdentityCredential.logoutRPs
IdleDetector.requestPermission
ImageDecoder.isTypeSupported
MediaRecorder.isTypeSupported
MediaSource.canConstructInDedicatedWorker
MediaSource.isTypeSupported
Notification.maxActions
Notification.permission
Notification.requestPermission
PerformanceObserver.supportedEntryTypes
PressureObserver.requestPermission
PressureObserver.supportedSources
PublicKeyCredential.isConditionalMediationAvailable
PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable
PublicKeyCredential.parseCreationOptionsFromJSON
PublicKeyCredential.parseRequestOptionsFromJSON
PushManager.supportedContentEncodings
Response.error
Response.redirect
RTCPeerConnection.generateCertificate
RTCRtpReceiver.getCapabilities
RTCRtpSender.getCapabilities
Sanitizer.getDefaultConfiguration
TrustedHTML.fromLiteral
TrustedScript.fromLiteral
TrustedScriptURL.fromLiteral
URL.createObjectURL
URL.revokeObjectURL
VideoDecoder.isConfigSupported
VideoEncoder.isConfigSupported
XRWebGLLayer.getNativeFramebufferScaleFactor

A bunch of these probably aren't in BCD, but most of them probably will be eventually.

I think that renaming all static methods would be a bit excessive, especially when these paths actually make more sense that the paths of methods, which should have ".prototype." to match how they're accessed in JS code.

I think json_static would be OK, with the description "json() static method". Such descriptions are already used at least here, when it's not needed to disambiguate: https://developer.mozilla.org/en-US/docs/Web/API/DOMMatrix#browser_compatibility

Sep 21 '22 14:09 foolip

I just cross-checked, and these are the 52 static methods already in BCD:

api.AbortSignal.abort
api.AbortSignal.timeout
api.AudioDecoder.isConfigSupported
api.AudioEncoder.isConfigSupported
api.BarcodeDetector.getSupportedFormats
api.BluetoothUUID.canonicalUUID
api.BluetoothUUID.getCharacteristic
api.BluetoothUUID.getDescriptor
api.BluetoothUUID.getService
api.CSSNumericValue.parse
api.CSSStyleValue.parse
api.CSSStyleValue.parseAll
api.CropTarget.fromElement
api.DOMMatrix.fromFloat32Array
api.DOMMatrix.fromFloat64Array
api.DOMMatrix.fromMatrix
api.DOMMatrixReadOnly.fromFloat32Array
api.DOMMatrixReadOnly.fromFloat64Array
api.DOMMatrixReadOnly.fromMatrix
api.DOMPoint.fromPoint
api.DOMPointReadOnly.fromPoint
api.DOMQuad.fromQuad
api.DOMQuad.fromRect
api.DOMRect.fromRect
api.DOMRectReadOnly.fromRect
api.DeviceMotionEvent.requestPermission
api.DeviceOrientationEvent.requestPermission
api.HTMLScriptElement.supports
api.IDBKeyRange.bound
api.IDBKeyRange.lowerBound
api.IDBKeyRange.only
api.IDBKeyRange.upperBound
api.IdleDetector.requestPermission
api.ImageDecoder.isTypeSupported
api.MediaRecorder.isTypeSupported
api.MediaSource.isTypeSupported
api.Notification.maxActions
api.Notification.permission
api.Notification.requestPermission
api.PerformanceObserver.supportedEntryTypes
api.PublicKeyCredential.isUserVerifyingPlatformAuthenticatorAvailable
api.PushManager.supportedContentEncodings
api.RTCPeerConnection.generateCertificate
api.RTCRtpReceiver.getCapabilities
api.RTCRtpSender.getCapabilities
api.Response.error
api.Response.redirect
api.URL.createObjectURL
api.URL.revokeObjectURL
api.VideoDecoder.isConfigSupported
api.VideoEncoder.isConfigSupported
api.XRWebGLLayer.getNativeFramebufferScaleFactor

Sep 21 '22 14:09 foolip

One point for _static-everywhere would be that it can consistently tell whether an item is for static or for prototype. Currently we are getting static functions after having prototype ones, but what if we ever get the static one first and then the prototype one? It would be confusing without knowing the history beforehand, and machines never attend history classes.

.prototype. also works, yes, but much much more excessive. 🤔

Sep 21 '22 18:09 saschanaz

Indeed, always appending _static would make it trivial to map IDL to a BCD entry. But the rule if we only do it in case of a conflict is still fairly simple: if the _static entry exists, that's the one, otherwise the path is the one without _static.

Sep 22 '22 11:09 foolip

Indeed, always appending _static would make it trivial to map IDL to a BCD entry. But the rule if we only do it in case of a conflict is still fairly simple: if the _static entry exists, that's the one, otherwise the path is the one without _static.

For the sake of authors, I would much prefer to always append _static.

When someone writes an MDN page, they have to add a front matter item pointing to the BCD query. They will know whether the method/property is static or not, because they are writing the page. But if _static is only applied in cases of conflict, then MDN authors won't know whether to add _static to the query without knowing something about other parts of the API: the answer to the question is no longer self-contained. People will get this wrong, all the time.

Contributing to MDN is complicated enough already.

Then of course even if they get it right (naming, say, the entry for the static method https://developer.mozilla.org/en-US/docs/web/api/idbkeyrange/bound bound because it does not have a non-static counterpart), this can be broken under their feet, if we ever add a non-static bound.

Oct 14 '22 17:10 wbamberg

See the related issue at https://github.com/orgs/mdn/discussions/264 (about what the MDN URLs should look like)

Oct 18 '22 08:10 sideshowbarker

I brought this up in the BCD call today and I think there was consensus to go ahead and append _static to all statics. It should be documented as a new BCD data guideline here: https://github.com/mdn/browser-compat-data/blob/main/docs/data-guidelines/api.md

May 02 '23 14:05 Elchi3