WinterTC Registered Symbol Naming Convention

Introduction

The ECMAScript global symbol registry — Symbol.for(key) — provides a process-global, cross-realm mechanism for sharing symbols by string key. WinterTC specifications use registered symbols for protocol markers, sentinel values, and extension hooks. Because the registry is shared with all application code and third-party libraries running in the same agent, naming discipline is essential to avoid collisions.

This specification defines a mandatory naming convention for all registered symbols introduced by WinterTC specifications. Individual specifications define specific symbols and their semantics; this specification governs only how their registry keys are formed.

Goals

1. Collision avoidance: A distinctive common prefix ensures WinterTC-defined keys cannot collide with application or library code.

2. Discoverability: A predictable naming structure makes symbols easier to identify, document, and debug.

3. Consistency across specifications: A shared convention prevents divergent naming styles as the number of WinterTC specifications grows.

1. Terminology

A registered symbol is a symbol obtained from the ECMAScript global symbol registry via Symbol.for(key), where key is a string. The same key always produces the same symbol, across all realms in the same agent.

A WinterTC-defined registered symbol is a registered symbol whose key is specified normatively by a WinterTC specification.

2. Naming Convention

2.1. Key Format

Every WinterTC-defined registered symbol MUST have a key that begins with the prefix wintertc., followed by one or more dot-separated segments:

wintertc.<domain>.<name>

where:

• **wintertc.** is a fixed, required prefix common to all WinterTC-defined registered symbols.

• **<domain>** is a lowercase identifier scoped to the defining specification or specification family.

• **<name>** is a camelCase identifier describing the symbol’s purpose.

The complete key — including the prefix — is the string passed to Symbol.for().

// A protocol marker defined by a server API specification
const marker = Symbol.for('wintertc.server.protocol');

// A sentinel value defined by the same specification
const fallthrough = Symbol.for('wintertc.server.fallthrough');

2.2. Domain Requirements

The <domain> component MUST match the production [a-z][a-z0-9]* — a non-empty, lowercase ASCII segment beginning with a letter.

Each WinterTC specification that defines registered symbols chooses its own domain. Domain names SHOULD be short, descriptive, and clearly related to the specification’s subject area. Different specifications MUST NOT use the same domain unless they are part of the same specification family (e.g., a base specification and its extensions).

2.3. Name Requirements

The <name> component MUST be:

• A valid ECMAScript IdentifierName [ECMA-262].

• Written in camelCase when it consists of multiple words.

• Concise and descriptive of the symbol’s role.

Single-word names (e.g., protocol, fallthrough) naturally satisfy both lowercase and camelCase conventions.

2.4. Permanence

Once a WinterTC-defined registered symbol key appears in a published WinterTC specification, that key MUST NOT be reassigned to a different purpose, even if the original symbol is deprecated or the defining specification is superseded. The key may be marked as deprecated, but its string remains permanently reserved.

This ensures that code written against an earlier version of a specification cannot silently observe a symbol with different semantics.

3. Conformance Requirements for WinterTC Specifications

A WinterTC specification that defines one or more registered symbols MUST:

1. Reference this specification.

2. Follow the key format defined in § 2.1 Key Format.

3. For each symbol, provide:

   • The full key string (e.g., 'wintertc.server.protocol').

   • A prose definition of the symbol’s purpose.

   • The contexts in which the symbol is used (property key, function argument, return value, etc.).

   • Any constraints on associated values.

Design Notes (Non-normative)

Why a common prefix

The wintertc. prefix follows the precedent set by Node.js, which prefixes its registered symbols with nodejs. (e.g., Symbol.for('nodejs.util.inspect.custom')). The prefix creates a distinctive namespace that is extremely unlikely to collide with application or library code.

Without a prefix, generic names like server.protocol or streams.drainable could plausibly be chosen independently by third-party code. The prefix eliminates this risk at a modest verbosity cost.

Implementation-specific symbols

This convention governs only WinterTC-defined registered symbols. Runtime implementations are encouraged to follow a similar prefixed pattern for their own registered symbols, but this specification imposes no requirements on non-WinterTC symbols.

The WinterTC Runtime Keys registry (ECMA TR/114) assigns a unique identifier to each runtime (e.g., node, deno, workerd). Implementations may wish to use their runtime key as a natural prefix for implementation-specific registered symbols — e.g., node.util.inspect.custom for Node.js. (Node.js predates the registry and uses nodejs. instead; newer runtimes have the opportunity to align.)

Copyright

© 2026 Ecma International

This document is available under the BSD License.