Reconsider the way we represent globals in Web/API

[wbamberg]

I think the way we represent globals in Web/API is not ideal.

We have various interfaces that are for global objects in various scopes, like Window or ServiceWorkerGlobalScope.

But then we also have items just at the top level, like btoa() or fetch(), which were members of the old WindowOrWorkerGlobalScope mixin, and which are just called "globals".

This makes it hard for someone to know what's available in a given scope. If I'm working with service workers, I can see ServiceWorkerGlobalScope and its parent WorkerGlobalScope, and know exactly what's available there. But this is incomplete: it's hard for me to get an easy view of what's missing here, like btoa() and fetch().

I think we should duplicate these "globals" in the top-level scopes in which they appear, namely Window and WorkerGlobalScope.

[Edited to add: it's not that bad, since these globals are listed in the body of https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope#instance_properties . But they're not in the nav for that page or for https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope, which I would 100% expect.

It's also conceptually confusing to call them "globals" when they're not available in all contexts (for example in audio worklets, unless I am mistaken).]

[teoli2003]

I always wanted to duplicate these "globals", but I was in the minority back then.

In addition to the argument of duplication and related to it, there was the argument of maintenance: if we update a page, we likely need to update 2 (and, in rare cases, more). We should also double check what consequences there are in relation to BCD (we don't need to do the same as them, but both mdn/content and mdn/browser-compat-data should be interoperable).

So we would have:

• Window (That I call in my mind WindowGlobalScope)
• WorkerGlobalScope
  • DedicatedWorkerGlobalScope
  • ServiceWorkerGlobalScope
  • SharedWorkerGlobalScope
• WorkletGlobalScope
  • AudioWorkletGlobalScope
  • PaintWorkletGlobalScope
  • LayoutWorkletGlobalScope (not implemented yet)
  • AnimationWorkletGlobalScope (not implemented yet)
• JsonLd(not implemented yet)
• RTCIdentityProvider

Also, global scopes are prefixed with the [Global=x,y,z] in WebIDL, indicating they are a global scope for realms x, y, z. A global scope interface can be visible as a global of several realms, and a realm can have several global scopes.

A small extract from w3c/webref:

[OnkarRuikar]

I think we should duplicate these "globals" in the top-level scopes in which they appear, namely Window and WorkerGlobalScope.

We can duplicate global scope interface pages without duplicating content itself if we implement symlink kinda stuff in yari:

# Some Global interface(SGInterface)
/files/en-us/web/api/SGInterface/index.md

# To add it to WindowGlobalScope
/files/en-us/web/api/Window/WindowGlobalScope/SGInterface/link.md

# To add it to WorkerGlobalScope
/files/en-us/web/api/WorkerGlobalScope/SGInterface/link.md

Content of link.md under worker scope could be like:

---
slug: /Web/API/WorkerGlobalScope/SGInterface
status: 
	- experimental
content-location: /files/en-us/web/api/SGInterface/index.md
---

<!-- Do not add content to this file! -->

When yari sees a link.md file it will have to get the content from content-location path. We'll have to decide which front-matter attributes can be reused and which can't be, e.g. addition of SGInterface to Workers scope can be experimental while API itself can be pretty old one.

---

Note: We could've directly used soft link feature of operating systems as git handles them perfectly without hiccups. But there are platform specific variations.
Like on Windows, depending on version and edition, developer mode has to be activated or user has to be given linking permissions.

[wbamberg]

Pinging this issue again.

I'm looking at mdn/content#29975, which adds links to various globals under the *WorkerGlobalScope interface pages. It think it is wrong to add them to all the *WorkerGlobalScope pages, we should just have them in the base class WorkerGlobalScope.

But also, I agree with teoli that we should duplicate these globals under all the base class global-scope objects, like Window, WorkerGlobalScope, and WorkletGlobalScope, and remove the top level globals like crypto.

We can duplicate global scope interface pages without duplicating content itself if we implement symlink kinda stuff in yari:

I think it would be better not to make this dependent on Yari features.

[teoli2003]

We could keep the globals at the top level but list them in all base classes of the global-scope objects (if relevant). We avoid duplication, and we have a complete list in the global object interface for people looking for them.

[wbamberg]

Yes, this does avoid duplication, but has at least two problems:

• they would not appear in the sidebars of global scope objects
• when you navigate from, say, Window to fetch() you'd lose your context - it doesn't look like a property of Window any more.

Also calling these things "global" is misleading because AFAIK there's really no such thing as just a "global" - there are different global scopes and they don't all have the same properties (e.g. WorkletGlobalScope). What we call "global" is really just WindowOrWorkerGlobalScope, isn't it?

How much duplication are we talking about? Are we just talking about duplicating between Window and WorkerGlobalScope? I count 11 web-api-global-function pages and 7 web-api-global-property pages.

[teoli2003]

I was (and still am) all for the duplication of these pages. I'm trying to find alternatives as some people weren't happy about that.

I count 13 pages (+ a few others in partial interface extensions, like crypto) to be duplicated on the mixin:

[wbamberg]

From webref/idl, I count 20 members, including partials:

indexedDB
crypto
fetch
performance
origin
isSecureContext
crossOriginIsolated
reportError
btoa
atob
setTimeout
clearTimeout
setInterval
clearInterval
queueMicrotask
createImageBitmap
structuredClone
scheduler
caches
trustedTypes

[skyclouds2001]

For those global properties and methods, maybe a solution is to keep two pages under Window interface and WorkerGlobalScope interface.

If the documentation itself is huge, we place the documentation under Window interface as the major documentation where place the major part of the content, and the documentation under WorkerGlobalScope interface where place the least part of the content:

like:

• content meta data
• a simple description to the property or method
• a link to indicate reader to go to the property/method documentation under Window interface
• a Specifications section
• a Browser compatibility section
• a See also section, including the link to the property/method documentation under Window interface
• also some other part if necessary)

---

for example, for fetch() method, we could do as follows:

Window.fetch():

// we place the previous content of the global fetch() method here

WorkerGlobalScope.fetch():

---

// some content meta data

The fetch() method of the WorkerGlobalScope interface // a simple description

For the detail of fetch() method, please go to {{domxref("Window.fetch()")}}.

Specifications

{{Specifications}}

Browser compatibility

{{Compat}}

See also

• {{domxref("Window.fetch()")}}

note if the page is simple, we could simply place as two documentaion (but I think add a link to each other is still necessary)

---

this can not only used in global properties/methods, but also some other situations that causes dumplite documentations

---

and it is doing similar things in examples, see api landing template

[wbamberg]

For those global properties and methods, maybe a solution is to keep two pages under Window interface and WorkerGlobalScope interface.

That's what my proposal is.

If the documentation itself is huge, we place the documentation under Window interface as the major documentation where place the major part of the content, and the documentation under WorkerGlobalScope interface where place the least part of the content:

Yes, I think this would be OK if it seems necessary.

[Rumyra]

OK sorry for the delay in reading through - yes let's duplicate - more thoughts:

I'm not really for this, it does add complexity for authors which I'm generally on the team of 'reduce complexity' and I do think we can come up a better solution, but I think that better solution will be platform dependent.

I've reasoned with both of the above with:

• the proposal here is closer to being accurate than the current approach
• the fact it's only ~13 instances
• albeit a small change, that it would be more understandable than it currently is for our users (and actually for our information architecture)
• and that if the platform allowed us to have a better solution, it is something folks in this thread would be keen to modify the approach again (you are very allowed to correct this if it is a wrong assumption :) )

[wbamberg]

We just merged mdn/content#32040, which as a test case fixes one of the 20 members that need fixing (indexedDB).

Once it's percolated, if it seems to work I'll continue with the others.

The procedure for each page is:

• yarn content move the global page to be under Window.
• update the page under Window to be an instance property page, and update the content accordingly
• create a new version of the page under WorkerGlobalScope, that's worker-specific
• manually delete the redirect from Web/API/WorkerGlobalScope/indexedDB to Web/API/indexedDB
• fix any domxref links
• update GroupData

[teoli2003]

One question that came to me this morning.

Should we use:

• self.xyz
• window.xyz (resp. self.xyz) [What has been done in the example]
• xyz
  in the examples?

I have no strong feelings here.

[wbamberg]

In mdn/content#32040 I used window for Window and self for WorkerGlobalScope, which I suppose felt most natural:

• https://developer.mozilla.org/en-US/docs/Web/API/Window/indexedDB#examples
• https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/indexedDB#examples

[teoli2003]

This is fine for me (and we shouldn't block on this). I wonder, though, what is done in the industry. I found no study about it with a basic web search.

[wbamberg]

So another set of questions is: what do we do for the other Window/WorkerGlobalScope members, and why should we do anything different for these? (i.e. given that we don't think mixins should be visible to readers, why would we have a difference here?) And have we ever worried about consistency there?

[wbamberg]

mdn/content#32040 has percolated now so we can look at it.

We have two pages:

• https://developer.mozilla.org/en-US/docs/Web/API/Window/indexedDB
• https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/indexedDB

Both pages have a web-api-instance-property page type and a normal title like "WorkerGlobalScope: indexedDB property".

In both pages, the sidebar gets a link to the IndexedDB API at the top, e.g.

In all pages for each property's interface or its members (i.e. the Window or WorkerGlobalScope interface or any of their members), the sidebar has an entry for the property, under "Instance properties", e.g.

In the IndexedDB API sidebar, both property pages are listed:

The old page at https://developer.mozilla.org/en-US/docs/Web/API/indexedDB redirects to https://developer.mozilla.org/en-US/docs/Web/API/Window/indexedDB.

[OnkarRuikar]

A tiny bug got introduced on https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/indexedDB :

[wbamberg]

Interesting. See also for example:
https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/sinkId
https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/backgroundFetch
https://developer.mozilla.org/en-US/docs/Web/API/Navigator/bluetooth
https://developer.mozilla.org/en-US/docs/Web/API/Navigator/clipboard
etc

As far as I can see these pages (and https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/indexedDB ) are set up properly. I think this is probably a bug in the sidebar macro.

[OnkarRuikar]

I think this is probably a bug in the sidebar macro.

• Yes. This can't be fixed on the content side. I've created an issue in yari: APIRef macro adds duplicate related entries in sidebar yari#10864

[wbamberg]

I'm closing this, since it seems we are into execution now. I've created mdn/content#33019 to track execution.

[wbamberg]

This is done: mdn/content#33019 . Massive thanks @skyclouds2001 for all your work on it.