Skip to content

Add naming conventions for APIs, constants, enum values and the manifest. - #1186

Open
xeenon wants to merge 1 commit into
w3c:mainfrom
xeenon:api-conventions-naming
Open

xeenon wants to merge 1 commit into
w3c:mainfrom
xeenon:api-conventions-naming

Conversation

@xeenon

@xeenon xeenon commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Fills in docs/api-conventions.md with the naming conventions agreed in #563 and extends them to methods, properties and manifest keys. The method and property rules come from the casing that existing APIs already use.

It covers:

  • A table of the style for namespaces, methods, events, properties, types, constants, enum values, manifest keys and manifest enum values.
  • Acronyms are written in capitals, except as the first word of a camelCase name. ID stays Id to match tabId, windowId and frameId.
  • A property name leaves out a word that the method name already says, as in action.setIcon({ variants }).
  • Constants are SCREAMING_SNAKE_CASE. Enum values are kebab-case, and manifest enum values stay snake_case.
  • A property that is in both the manifest and an API takes the style of where it is written (css_origin and cssOrigin, color_schemes and colorSchemes).

The conventions apply to future additions. Existing names are not changed.

Closes #563

@xeenon
xeenon force-pushed the api-conventions-naming branch 2 times, most recently from 03a510f to 8221150 Compare November 9, 2026 22:57
@xeenon
xeenon force-pushed the api-conventions-naming branch from 8221150 to 712274a Compare November 10, 2026 01:32
@carlosjeurissen

Copy link
Copy Markdown
Member

Thanks for putting this together @xeenon !!

In general there seem to be two major potentially unavoidable concerns with the conventions.

  1. The snake_case vs camelCase for properties in declarative manifest values vs javaScript API calls. If the specific objects like ContentScripts and IconVariants are taken from the manifest file, the extension has to manually convert them between cases to be able to use them in the JavaScript APIs. This is also additional friction in potential abstraction layers in build / compilation scripts in extensions.

  2. Conflict in enum value casing between JS APIs using kebab-case and manifest enum values using snake_case. Same concern as mentioned above. And it contradicts current casing behavior in JS APIs today; for example (extensionTypes.RunAt). Is there any reason we can not use the same casing for both moving forward?

@xeenon

xeenon commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator Author

Thanks, @carlosjeurissen.

On the second point: a value shared by the manifest and an API is the awkward case, and RunAt is the clearest. The guide only applies to future additions, so RunAt and the other existing enums stay as they are.

The reason for kebab-case is the W3C style for web APIs, which asks for lowercase, dash-delimited enum values. That was the main driver in #563.

I also counted enum values in the JS APIs and manifest.json of Safari, Chromium and Firefox. Most sets have no multi-word value, and a single word reads the same in kebab-case, snake_case and lowercase. Where a set does, snake_case is the most common style today and kebab-case the least, but camelCase and SCREAMING_SNAKE_CASE also appear, so matching existing values would not give one rule either.

Aligning manifest keys and values with the API style is something I would like to see, but that is a larger change for a future manifest version.

@carlosjeurissen

Copy link
Copy Markdown
Member

@xeenon thanks for the added context! In that case I would be in favor of also using kebab-case for future web extension enums in manifest files even if this is different than what we do with RunAt.

@tophf

tophf commented Nov 14, 2026

Copy link
Copy Markdown

ID stays Id

FWIW id in programming is arguably perceived de facto as a single term, not an acronym, so Id feels natural and not an exception.

The snake_case vs camelCase for properties in declarative manifest values vs javaScript API calls

What about chrome.runtime.getManifest({ convertValues: true })?

Comment thread docs/api-conventions.md Outdated
|---|---|---|
| Namespace | camelCase | `declarativeNetRequest` |
| Method | camelCase, verb first | `getRecentlyClosed()` |
| Event | `on` followed by camelCase | `onVisitRemoved` |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nitpicky nitpick:

Strictly speaking it is "camelCase" starting with "on".

(Or "on" followed by PascalCase)

Comment thread docs/api-conventions.md
| Constant | SCREAMING_SNAKE_CASE | `TAB_ID_NONE` |
| Enum value | kebab-case | `"per-origin"` |
| Manifest key | snake_case | `"default_title"` |
| Manifest enum value | snake_case | `"document_idle"` |

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
| Manifest enum value | snake_case | `"document_idle"` |
| Manifest enum value | kebab-case | `"no-repeat"` |

The web app manifests also use kebab-case for enums in the manifest. Aligning with them seems to make sense.

@carlosjeurissen carlosjeurissen left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Very much in favor of using kebab-case for manifest enum values. This will align us with the web app manifest spec and would align with the JS APIs.

@tophf

tophf commented Nov 16, 2026

Copy link
Copy Markdown

kebab-case in manifest sounds like a breaking change for MV4+.

@carlosjeurissen

Copy link
Copy Markdown
Member

@tophf the point of writing these conventions is to be applied for new enums. We still have to discuss how to migrate existing enums to properly formatted/cased enums. Supporting both could be something browsers could offer on a very short notice. While actually removing support for non kebab-case values should indeed only happen in mv4+ in my opinion.

@tophf

tophf commented Nov 16, 2026

Copy link
Copy Markdown

Mixing of different conventions in one scope is not a consistent API design. We already suffered Chromium-imposed SCREAMING_CASE inside values under a specious argument that it helps unification while actually it only added more fragmentation, but that's what MV3 ended up doing globally anyway, so ironically there is internal consistency. Thing is, if your extension wants to run in older versions of Chromium you are stuck with those SUDDENLY_SCREAMING values in manifest.json.

…est.

Cover the casing of namespaces, methods, events, properties, types, constants, enum values, manifest keys and
manifest enum values, how acronyms are written, and how a property that is in both the manifest and an API is
named.
@xeenon

xeenon commented Nov 16, 2026

Copy link
Copy Markdown
Collaborator Author

@carlosjeurissen @tophf thanks, both of you.

The goal of this document is to write down what we largely agree on for new APIs, without a drastic departure from what is implemented today. The main thing I want to avoid is new SCREAMING_CASE values being introduced, as tophf describes, and the document does that either way. For manifest enum values I would keep snake_case for now, because it matches the values already in the manifest (document_idle, service_worker). Adding kebab-case next to them would mix two styles in one place.

I agree this should be revisited for a v4 with a holistic view of backwards compatibility. Browsers could normalize automatically so that old and new spellings both load, while enforcing one consistent style going forward. Safari already does a little of this. It accepts world case-insensitively in the manifest and in scripting, so the lowercase "isolated" and "main" work. The inconsistency of uppercase values bothered me enough to do that.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

wewg Topics under the umbrella of the WEWG (WebExtensions Working Group)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

New API enum values should use lowercase-dash-delimited style

4 participants