PerformanceObserver.observe(): compatibility table is misleading — does not distinguish Level 1 (entryTypes) vs Level 2 (type+buffered) syntax, caused production breakage

[827652549]

MDN URL

https://developer.mozilla.org/en-US/docs/Web/API/PerformanceObserver/observe

What specific section or headline is this issue about?

Code example and Browser compatibility table

What information was incorrect, unhelpful, or incomplete?

The code example uses the Level 2 syntax ({ type, buffered }) without any warning:

observer.observe({ type: "resource", buffered: true });

This throws a runtime TypeError on older browsers (e.g. Android 9 WebView, iOS 12 Safari) that only support the Level 1 syntax ({ entryTypes: [...] }).

Additionally, the Browser Compatibility table shows observe() is supported from Safari 11 / iOS 11, but this only reflects support for the Level 1 signature. The Level 2 signature ({ type, buffered }) has a narrower support range that is not separately represented in the table.

The combination of a Level 2 example and a table that appears to show broad support is misleading.

What did you expect to see?

Either:

1. The example uses the safer Level 1 syntax (entryTypes), or shows both syntaxes with a feature-detect fallback
2. A compatibility warning noting that { type, buffered } requires Level 2 support (not available in Safari < 14, Chrome WebView < ~73)
3. Separate BCD entries for the type and buffered options so developers can see the real support range

Do you have any supporting links, references, or citations?

• Performance Timeline Level 2 spec: https://w3c.github.io/performance-timeline/#dom-performanceobserver-observe
• Live reproduction: https://7fznjs.csb.app/

Do you have anything more you want to share?

Reproduction steps (verified on Android 9):

1. Start an Android 9 emulator (API 28) via Android Studio AVD Manager
2. Open https://7fznjs.csb.app/ in the browser
3. Inspect via chrome://inspect on desktop Chrome
4. Error in Console: "Uncaught TypeError: Failed to execute 'observe' on 'PerformanceObserver': required member entryTypes is undefined."

Environment: Android 9 (PSR1.210301.009.B1), WebView Chrome 66.0.3359.158

iOS 12 was also affected — confirmed at the time via a real enterprise device — but cannot be re-verified now as iOS 12 simulators require Xcode 13 (incompatible with newer macOS), and cloud platforms like BrowserStack no longer support iOS 12.

This issue caused a production white screen in an enterprise app. The misleading compatibility table was the primary reason the bug went unnoticed during development.

[Josh-Cena]

Please see our guideline for browser support: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Code_style_guide/JavaScript#use_modern_javascript_features_when_supported

We don't complicate our code examples for feature detection once a feature is baseline. Legacy browsers are not part of our concern, and are not the concern of the majority of web apps. If you develop enterprise apps, it's your responsibility to make the code adapt to your browser compat requirements, such as via polyfills, transpilers, or type checking.

The browser compat table may be missing this nuance; that should go into BCD.

[wbamberg]

I wondered about this, and agree that most of the fix is in BCD, but I also wondered if the page ought to describe the legacy syntax. Because BCD can't itself describe the legacy syntax, so how could BCD express this situation in a helpful way?

[Josh-Cena]

BCD would definitely need a subfeature for any new options introduced in v2. The page itself already describes entryTypes

[827652549]

Thanks for taking the time to respond and for pointing me to the guidelines — that genuinely helps me understand how MDN approaches these decisions.

I want to make sure I'm being clear about what I was trying to raise, because I don't think I communicated it well in the original issue. My concern isn't about adding feature detection to the example — I completely agree that's not MDN's responsibility. What I was trying to point to is a question of whether the compatibility data accurately reflects reality: the { type, buffered } syntax (Level 2) and the entryTypes syntax (Level 1) have meaningfully different browser support ranges, but the current table only shows the support status of observe() as a whole, with no indication of that distinction.

For some context on why this matters in practice: according to StatCounter data from early 2026, Android 9 (which ships with Chrome 66 WebView and doesn't support Level 2 syntax) still accounts for around 4.5% of the Android market — roughly 3% of global mobile users. Add iOS 12 Safari on top of that, and the affected audience is not negligible. It's also worth noting that caniuse has integrated MDN BCD data since 2019, which means any gap in the BCD data propagates to caniuse as well, reaching an even wider developer audience.

Anyway, I appreciate you engaging with this — happy to defer to your judgment on whether and how it's worth addressing.

[827652549]

Thank you for raising that question — it actually gets at exactly what I was trying to suggest.

To be clear, I'm not asking MDN to document the legacy entryTypes-only syntax as a separate section. What I had in mind was something narrower: adding a BCD subfeature entry for the type option specifically, so the compatibility table could reflect the actual support range for that particular calling signature, rather than just the method as a whole. Josh-Cena also mentioned that "BCD would definitely need a subfeature for any new options," so I assumed this direction might be feasible — though I'll leave it to you all to decide whether it's worth pursuing.