1.Introduction

This section is informative.

This standard defines an interface definition language, Web IDL, that can be used to describeinterfaces that are intended to be implemented in web browsers. Web IDL is an IDL variant with anumber of features that allow the behavior of common script objects in the web platform to bespecified more readily. How interfaces described with Web IDL correspond to constructs withinJavaScript execution environments is also detailed here.

Concretely, Web IDL provides a syntax for specifying the surface APIs of web platform objects, aswell as JavaScript bindings that detail how those APIs manifest as JavaScript constructs. Thisensures common tasks, such as installing global properties, processing numeric inputs, or exposingiteration behavior, remain uniform across web platform specifications: such specifications describetheir interfaces using Web IDL, and then use prose to specify API-specific details.

The term "JavaScript" is used to refer to ECMA-262, rather than the official term ECMAScript, since the term JavaScript is more widely known.

2.Interface definition language

This section describes a language,Web IDL, which can be used to defineinterfaces for APIs in the Web platform. A specification that defines Web APIscan include one or moreIDL fragments thatdescribe the interfaces (the state and behavior that objects can exhibit)for the APIs defined by that specification.AnIDL fragment isa sequence of definitions that matches theDefinitions grammar symbol.The set ofIDL fragments thatan implementation supports is not ordered.SeeIDL grammar for the complete grammar and an explanation of the notation used.

The different kinds ofdefinitions that can appear in anIDL fragment are:interfaces,partial interface definitions,interface mixins,partial mixin definitions,callback functions,callback interfaces,namespaces,partial namespace definitions,dictionaries,partial dictionary definitions,typedefs andincludes statements.These are all defined in the following sections.

Eachdefinition (matchingDefinition)can be preceded by a list ofextended attributes (matchingExtendedAttributeList),which can control how the definition will be handled in language bindings.The extended attributes defined by this specification that are language bindingagnostic are discussed in§ 2.14 Extended attributes,while those specific to the JavaScript language binding are discussedin§ 3.3 Extended attributes.

[extended_attributes]interfaceidentifier {  /* interface_members... */};

Definitions ::ExtendedAttributeListDefinitionDefinitions    ε

Definition ::CallbackOrInterfaceOrMixinNamespacePartialDictionaryEnumTypedefIncludesStatement

[Exposed=Window]interfacePaint { };[Exposed=Window]interfaceSolidColor :Paint {attributedoublered;attributedoublegreen;attributedoubleblue;};[Exposed=Window]interfacePattern :Paint {attributeDOMStringimageURL;};[Exposed=Window]interfaceGraphicalWindow {constructor();readonlyattributeunsignedlongwidth;readonlyattributeunsignedlongheight;attributePaintcurrentPaint;undefineddrawRectangle(doublex,doubley,doublewidth,doubleheight);undefineddrawText(doublex,doubley,DOMStringtext);};

2.1.Names

Everyinterface,partial interface definition,namespace,partial namespace definition,dictionary,partial dictionary definition,enumeration,callback function,callback interface andtypedef (together callednamed definitions)and everyconstant,attribute,anddictionary member has anidentifier, as do someoperations.The identifier is determined by anidentifier token somewherein the declaration:

• Fornamed definitions,theidentifier token that appearsdirectly after theinterface,namespace,dictionary,enum orcallback keyworddetermines the identifier of that definition.

  interfaceinterface_identifier { /* interface_members... */ };partialinterfaceinterface_identifier { /* interface_members... */ };namespacenamespace_identifier { /* namespace_members... */ };partialnamespacenamespace_identifier { /* namespace_members... */ };dictionarydictionary_identifier { /* dictionary_members... */ };partialdictionarydictionary_identifier { /* dictionary_members... */ };enumenumeration_identifier {"enum","values" /* , ... */ };callbackcallback_identifier =return_type (/* arguments... */);callbackinterfacecallback_interface_identifier { /* interface_members... */ };

• Forattributes,typedefs anddictionary members,the finalidentifier token before thesemicolon at the end of the declaration determines the identifier.

  [extended_attributes]interfaceidentifier {attributetypeattribute_identifier;};typedeftypetypedef_identifier;dictionaryidentifier {typedictionary_member_identifier;};

• Forconstants,theidentifier token before theequals sign determines the identifier.

  consttypeconstant_identifier = 42;

• Foroperations, theidentifier token that appearsafter the return type but before the opening parenthesis (that is,one that is matched as part of theOptionalOperationName grammar symbol in anOperationRest) determines the identifier of the operation. Ifthere is no suchidentifier token,then the operation does not have an identifier.

  interfaceinterface_identifier {return_typeoperation_identifier(/* arguments... */);};

Note: Operations can have no identifier when they are being used to declare aspecial kind of operation, such as a getter or setter.

For all of these constructs, theidentifier is the value of theidentifier token with any leadingU+005F (_) removed.

Note: A leading U+005F (_) is used to escape an identifier from lookinglike a reserved word so that, for example, an interface named "interface" can bedefined. The leading U+005F (_) is dropped to unescape theidentifier.

Operation arguments can take a slightly wider set of identifiers. In an operationdeclaration, the identifier of an argument is specified immediately after itstype and is given by either anidentifier token or by one of the keywords that match theArgumentNameKeyword symbol. If one of these keywords is used, it need not be escaped with a leadingunderscore.

interfaceinterface_identifier {return_typeoperation_identifier(argument_typeargument_identifier /* , ... */);};

ArgumentNameKeyword ::asyncattributecallbackconstconstructordeleterdictionaryenumgetterincludesinheritinterfaceiterablemaplikemixinnamespacepartialreadonlyrequiredsetlikesetterstaticstringifiertypedefunrestricted

If anidentifier token is used, then theidentifier of the operation argumentis the value of that token with any leadingU+005F (_) removed.If instead one of theArgumentNameKeyword keyword token is used, then theidentifier of the operation argumentis simply that token.

Theidentifier of any of the abovementionedIDL constructs (except operation arguments) must not be "constructor","toString",or begin with a U+005F (_). Theseare known asreserved identifiers.

Although the "toJSON"identifier is not areserved identifier,it must only be used forregular operations that convert objects toJSON types,as described in§ 2.5.3.1 toJSON.

Note: Further restrictions on identifier names for particular constructs can be madein later sections.

Within the set ofIDL fragments that a given implementation supports,theidentifier of everyinterface,namespace,dictionary,enumeration,callback function,callback interface andtypedef must notbe the same as the identifier of any otherinterface,namespace,dictionary,enumeration,callback function,callback interface ortypedef.

Within anIDL fragment, a referenceto adefinition need not appear afterthe declaration of the referenced definition. References can also be madeacrossIDL fragments.

[Exposed=Window]interfaceB :A {undefinedf(SequenceOfLongsx);};[Exposed=Window]interfaceA {};typedefsequence<long>SequenceOfLongs;

// Typedef identifier: "number"typedefdoublenumber;// Interface identifier: "System"[Exposed=Window]interfaceSystem {  // Operation identifier:          "createObject"  // Operation argument identifier: "interface"objectcreateObject(DOMString_interface);  // Operation argument identifier: "interface"sequence<object>getObjects(DOMStringinterface);  // Operation has no identifier; it declares a getter.getterDOMString (DOMStringkeyName);};// Interface identifier: "TextField"[Exposed=Window]interfaceTextField {  // Attribute identifier: "const"attributeboolean_const;  // Attribute identifier: "value"attributeDOMString?_value;};

2.2.Interfaces

IDL fragments are used todescribe object oriented systems. In such systems, objects are entitiesthat have identity and which are encapsulations of state and behavior.Aninterface is a definition (matchinginterfaceInterfaceRest) that declares somestate and behavior that an object implementing that interface will expose.

[extended_attributes]interfaceidentifier {  /* interface_members... */};

An interface is a specification of a set ofinterface members (matchingInterfaceMembers).These are themembers that appear between the braces in the interface declaration.

Interfaces in Web IDL describe how objects that implement theinterface behave. In bindings for object oriented languages, it isexpected that an object that implements a particular IDL interfaceprovides ways to inspect and modify the object’s state and toinvoke the behavior described by the interface.

An interface can be defined toinherit from another interface.If the identifier of the interface is followed by aU+003A (:)and anidentifier,then that identifier identifies the inherited interface.An object that implements an interface that inherits from anotheralso implements that inherited interface. The object therefore will alsohave members that correspond to the interface members from the inherited interface.

interfaceidentifier :identifier_of_inherited_interface {  /* interface_members... */};

The order that members appear in has significance for property enumeration in theJavaScript binding.

Interfaces may specify an interface member that has the same name asone from an inherited interface. Objects that implement the derivedinterface will expose the member on the derived interface. It islanguage binding specific whether the overridden member can beaccessed on the object.

[Exposed=Window]interfaceA {undefinedf();undefinedg();};[Exposed=Window]interfaceB :A {undefinedf();undefinedg(DOMStringx);};

[Object.prototype: the Object prototype object]     ↑[A.prototype: interface prototype object for A]     ↑[B.prototype: interface prototype object for B]     ↑[instanceOfB]

Theinherited interfaces ofa given interfaceA is the set of all interfaces thatA inherits from, directly or indirectly. IfA does notinherit from another interface, then the set is empty. Otherwise, the setincludes the interfaceB thatAinherits from and all ofB’sinherited interfaces.

An interface must not be declared such thatits inheritance hierarchy has a cycle. That is, an interfaceA cannot inherit from itself, nor can it inherit from anotherinterfaceB that inherits fromA, and so on.

Note that general multiple inheritance of interfaces is not supported, andobjects also cannot implement arbitrary sets of interfaces.Objects can be defined to implement a single given interfaceA,which means that it also implements all ofA’sinherited interfaces.In addition, anincludes statement can be usedto define that objects implementing aninterfaceA will always also include themembers of theinterface mixinsAincludes.

Each interface member can be preceded by a list ofextended attributes (matchingExtendedAttributeList),which can control how the interface member will be handled in language bindings.

[extended_attributes]interfaceidentifier {  [extended_attributes]consttypeconstant_identifier = 42;  [extended_attributes]attributetypeidentifier;  [extended_attributes]return_typeidentifier(/* arguments... */);};

The IDL for interfaces can be split into multiple parts by usingpartial interface definitions(matchingpartialinterfacePartialInterfaceRest).Theidentifier of a partialinterface definition must be the sameas the identifier of an interface definition. All ofthe members that appear on each of the partial interfaces are considered to bemembers of the interface itself.

interfaceSomeInterface {  /* interface_members... */};partialinterfaceSomeInterface {  /* interface_members... */};

Note: Partial interface definitions are intended for use as a specificationeditorial aide, allowing the definition of an interface to be separatedover more than one section of the document, and sometimes multiple documents.

The order of appearance of aninterface definition and any of itspartial interface definitions does not matter.

Note: A partial interface definition cannot specify that the interfaceinherits from another interface.Inheritance is to be specified on the originalinterface definition.

The relevant language binding determines how interfaces correspond to constructsin the language.

The following extended attributes are applicable to interfaces:[CrossOriginIsolated],[Exposed],[Global],[LegacyFactoryFunction],[LegacyNoInterfaceObject],[LegacyOverrideBuiltIns],[LegacyWindowAlias], and[SecureContext].

The following extended attributes are applicable topartial interfaces:[CrossOriginIsolated],[Exposed],[LegacyOverrideBuiltIns], and[SecureContext].

Interfaces must be annotated with an [Exposed]extended attribute.

CallbackOrInterfaceOrMixin ::callbackCallbackRestOrInterfaceinterfaceInterfaceOrMixin

InterfaceOrMixin ::InterfaceRestMixinRest

InterfaceRest ::identifierInheritance{InterfaceMembers};

Partial ::partialPartialDefinition

PartialDefinition ::interfacePartialInterfaceOrPartialMixinPartialDictionaryNamespace

PartialInterfaceOrPartialMixin ::PartialInterfaceRestMixinRest

PartialInterfaceRest ::identifier{PartialInterfaceMembers};

InterfaceMembers ::ExtendedAttributeListInterfaceMemberInterfaceMembers    ε

InterfaceMember ::PartialInterfaceMemberConstructor

PartialInterfaceMembers ::ExtendedAttributeListPartialInterfaceMemberPartialInterfaceMembers    ε

PartialInterfaceMember ::ConstOperationStringifierStaticMemberIterableAsyncIterableReadOnlyMemberReadWriteAttributeReadWriteMaplikeReadWriteSetlikeInheritAttribute

Inheritance :::identifier    ε

[Exposed=Window]interfaceAnimal {attributeDOMStringname;};[Exposed=Window]interfaceHuman :Animal {attributeDog?pet;};[Exposed=Window]interfaceDog :Animal {attributeHuman?owner;};

[Exposed=Window]interfaceNode {readonlyattributeDOMStringnodeName;readonlyattributeNode?parentNode;NodeappendChild(NodenewChild);undefinedaddEventListener(DOMStringtype,EventListenerlistener);};callbackinterfaceEventListener {undefinedhandleEvent(Eventevent);};

var node= getNode();// Obtain an instance of Node.var listener={  handleEvent:function(event){// ...}};node.addEventListener("click", listener);// This works.node.addEventListener("click",function(){...});// As does this.

var node= getNode();// Obtain an instance of Node.var newNode={  nodeName:"span",  parentNode:null,  appendChild:function(newchild){// ...},  addEventListener:function(type, listener){// ...}};node.appendChild(newNode);// This will throw a TypeError exception.

2.3.Interface mixins

Aninterface mixin is a definition (matchinginterfaceMixinRest)that declares state and behavior that can beincluded by one or moreinterfaces,and that are exposed by objects that implement aninterface thatincludes theinterface mixin.

interfacemixinidentifier {  /* mixin_members... */};

Note:Interface mixins, much likepartial interfaces,are intended for use as a specification editorial aide,allowing a coherent set of functionalities to be grouped together,and included in multiple interfaces, possibly across documents.They are not meant to be exposed through language bindings.Guidance on when to choosepartial interfaces,interface mixins,orpartial interface mixins can be found in§ 2.3.1 Using mixins and partials.

Aninterface mixin is a specification of a set ofinterface mixin members (matchingMixinMembers),which are theconstants,regular operations,regular attributes, andstringifiers that appear between the braces in theinterface mixin declaration.

Theseconstants,regular operations,regular attributes, andstringifiers describe the behaviors that can be implemented by an object,as if they were specified on theinterface thatincludes them.

Static attributes,static operations,special operations, anditerable,asynchronously iterable,maplike, andsetlike declarations cannot appear ininterface mixin declarations.

As with interfaces, the IDL forinterface mixins can be split into multiple parts by usingpartial interface mixin definitions(matchingpartialinterfaceMixinRest).Theidentifier of apartial interface mixindefinition mustbe the same as theidentifier of aninterface mixindefinition.All of themembers that appear on each of thepartial interface mixindefinitions are considered to bemembers of theinterface mixin itself,and—by extension—of theinterfaces thatinclude theinterface mixin.

interfacemixinSomeMixin {  /* mixin_members... */};partialinterfacemixinSomeMixin {  /* mixin_members... */};

The order that members appear in has significance for property enumerationin theJavaScript binding.

Note that unlikeinterfaces ordictionaries,interface mixins do not create types.

Of the extended attributes defined in this specification,only the [CrossOriginIsolated], [Exposed], and [SecureContext] extended attributesare applicable tointerface mixins.

Anincludes statement is a definition(matchingIncludesStatement)used to declare that all objects implementing aninterfaceI (identified by the firstidentifier)must additionally include themembers ofinterface mixinM (identified by the second identifier).InterfaceI is said toincludeinterface mixinM.

interface_identifierincludesmixin_identifier;

The firstidentifier must reference ainterfaceI.The second identifier must reference aninterface mixinM.

Eachmember ofM is considered to beamember of eachinterfaceI,J,K, … thatincludesM,as if a copy of eachmember had been made.So for a given memberm ofM,interfaceI is considered to have amemberm_I,interfaceJ is considered to have amemberm_J,interfaceK is considered to have amemberm_K, and so on.Thehost interfaces ofm_I,m_J,andm_K, areI,J, andK respectively.

Note: In JavaScript, this implies that eachregular operation declared as amember ofinterface mixinM,and exposed as a data property with abuilt-in function object value,is a distinctbuilt-in function object in eachinterface prototype object whose associatedinterfaceincludesM.Similarly, forattributes, each copy of the accessor property hasdistinctbuilt-in function objects for its getters and setters.

The order of appearance ofincludes statements affects the order in whichinterface mixin areincluded by theirhost interface.

Member order isn’t clearly specified,in particular wheninterface mixins are defined in separate documents.It is discussed inissue #432.

Noextended attributes defined in this specification are applicable toincludes statements.

interfaceEntry {readonlyattributeunsignedshortentryType;  // ...};interfacemixinObservable {undefinedaddEventListener(DOMStringtype,EventListenerlistener,booleanuseCapture);  // ...};EntryincludesObservable;

var e= getEntry();// Obtain an instance of Entry.typeof e.addEventListener;// Evaluates to "function".

CallbackOrInterfaceOrMixin ::callbackCallbackRestOrInterfaceinterfaceInterfaceOrMixin

InterfaceOrMixin ::InterfaceRestMixinRest

Partial ::partialPartialDefinition

PartialDefinition ::interfacePartialInterfaceOrPartialMixinPartialDictionaryNamespace

MixinRest ::mixinidentifier{MixinMembers};

MixinMembers ::ExtendedAttributeListMixinMemberMixinMembers    ε

MixinMember ::ConstRegularOperationStringifierOptionalReadOnlyAttributeRest

IncludesStatement ::identifierincludesidentifier;

2.3.1.Using mixins and partials

This section is informative.

Interface mixins allow the sharing ofattributes,constants, andoperations acrossmultipleinterfaces.If you’re only planning to extend a single interface,you might consider using apartial interface instead.

For example, instead of:

interfacemixinWindowSessionStorage {readonlyattributeStoragesessionStorage;};WindowincludesWindowSessionStorage;

do:

partialinterfaceWindow {readonlyattributeStoragesessionStorage;};

Additionally, you can rely on extendinginterface mixins exposed by other specificationsto target common use cases, such asexposing a set ofattributes,constants, oroperations across both window and worker contexts.

For example, instead of the common but verbose:

interfacemixinGlobalCrypto {readonlyattributeCryptocrypto;};WindowincludesGlobalCrypto;WorkerGlobalScopeincludesGlobalCrypto;

you can extend theWindowOrWorkerGlobalScopeinterface mixin using apartial interface mixin:

partialinterfacemixinWindowOrWorkerGlobalScope {readonlyattributeCryptocrypto;};

2.4.Callback interfaces

Acallback interface is adefinition matchingcallbackinterfaceidentifier{CallbackInterfaceMembers};.It can be implemented by any object, as described in§ 2.12 Objects implementing interfaces.

Note: Acallback interface is not aninterface. The name and syntax are left over fromearlier versions of this standard, where these concepts had more in common.

Acallback interface is a specification of a set ofcallback interface members (matchingCallbackInterfaceMembers).These are themembers that appear between the braces in the interface declaration.

callbackinterfaceidentifier {  /* interface_members... */};

Note: See also the similarly namedcallback function definition.

Callback interfaces must define exactly oneregular operation.

Callback interfaces which declareconstants must be annotated with an [Exposed]extended attribute.

CallbackRestOrInterface ::CallbackRestinterfaceidentifier{CallbackInterfaceMembers};

CallbackInterfaceMembers ::ExtendedAttributeListCallbackInterfaceMemberCallbackInterfaceMembers    ε

CallbackInterfaceMember ::ConstRegularOperation

2.5.Members

Interfaces,interface mixins, andnamespaces are specifications of a set ofmembers (respectively matchingInterfaceMembers,MixinMembers, andNamespaceMembers),which are theconstants,attributes,operations, andother declarations that appear between the braces of their declarations.Attributes describe the state that an objectimplementing theinterface,interface mixin, ornamespace will expose,andoperations describe the behaviors that can be invoked on the object.Constants declare named constant valuesthat are exposed as a convenience to users of objects in the system.

Theconstructor steps,getter steps,setter steps, andmethod steps for the variousmembers defined on aninterface orinterface mixin have access to athis value, which is an IDL value of theinterface type that the member isdeclared on or thatincludes theinterface mixin the member is declared on.

Setter steps also have access tothe given value,which is an IDL value of the type theattribute is declared as.

Interfaces,interface mixins,callback interfaces andnamespaces each support adifferent set ofmembers,which are specified in§ 2.2 Interfaces,§ 2.3 Interface mixins,§ 2.4 Callback interfaces, and§ 2.6 Namespaces,and summarized in the following informative table:

2.5.1.Constants

Aconstant is a declaration (matchingConst) used to bind a constant value to a name.Constants can appear oninterfaces andcallback interfaces.

Constants have in the past primarily been used to define named integer codes in the style of an enumeration. The Web platform is moving away from this design pattern in favor of the use of strings. Editors who wish to use this feature are strongly advised to discuss this byfiling an issue before proceeding.

consttypeconstant_identifier = 42;

Theidentifier of aconstant must not be the same as the identifierof anotherinterface member orcallback interface member defined on the sameinterface orcallback interface.The identifier also must notbe "length", "name" or "prototype".

Note: These three names are the names of properties that are defined on theinterface object in the JavaScript language binding.

The type of a constant (matchingConstType)must not be any type other thanaprimitive type.If anidentifier is used,it must reference atypedef whose type is a primitive type.

TheConstValue part of aconstant declaration gives the value of the constant, which can beone of the two boolean literal tokens (true andfalse), aninteger token,adecimal token,or one of the three special floating point constant values(-Infinity,Infinity andNaN).

Note: These values – in addition to strings and the empty sequence – can also be used to specify thedefault value of a dictionary member orof an optional argument.Note that strings, theempty sequence[], and the default dictionary{} cannot be used as the value of aconstant.

The value of the boolean literal tokenstrue andfalse are the IDLboolean valuestrue andfalse.

The type of aninteger token is the sameas the type of the constant, dictionary member or optional argument it is being used as the value of.The value of theinteger token must notlie outside the valid range of values for its type, as given in§ 2.13 Types.

The value of a constant value specified asInfinity,-Infinity, orNaN is eitheran IEEE 754 single-precision floating point number or an IEEE 754double-precision floating point number, depending on the type of theconstant, dictionary member, or optional argument it is being used as thevalue for:

Typeunrestricted float, constant valueInfinity

The value is the IEEE 754 single-precision positive infinity value.

Typeunrestricted double, constant valueInfinity

The value is the IEEE 754 double-precision positive infinity value.

Typeunrestricted float, constant value-Infinity

The value is the IEEE 754 single-precision negative infinity value.

Typeunrestricted double, constant value-Infinity

The value is the IEEE 754 double-precision negative infinity value.

Typeunrestricted float, constant valueNaN

The value is the IEEE 754 single-precision NaN value with the bit pattern 0x7fc00000.

Typeunrestricted double, constant valueNaN

The value is the IEEE 754 double-precision NaN value with the bit pattern 0x7ff8000000000000.

The type of adecimal token is the sameas the type of the constant, dictionary member or optional argument it is being used as the value of.The value of thedecimal token must notlie outside the valid range of values for its type, as given in§ 2.13 Types.Also,Infinity,-Infinity andNaN must notbe used as the value of afloat ordouble.

The value of thenull token is the specialnull value that is a member of thenullable types. The type ofthenull token is the same as thetype of the constant, dictionary member or optional argument it is being used as the value of.

IfVT is the type of the value assigned to a constant, andDT is the type of the constant, dictionary member or optional argument itself, then these types mustbe compatible, which is the case ifDT andVT are identical,orDT is anullable type whoseinner type isVT.

Constants are not associated withparticular instances of theinterface orcallback interface on which they appear. It is language binding specific whetherconstants are exposed on instances.

[Exposed=Window]interfaceA {constshortrambaldi = 47;};

The following extended attributes are applicable to constants:[CrossOriginIsolated],[Exposed], and[SecureContext].

Const ::constConstTypeidentifier=ConstValue;

ConstValue ::BooleanLiteralFloatLiteralinteger

BooleanLiteral ::truefalse

FloatLiteral ::decimal-InfinityInfinityNaN

ConstType ::PrimitiveTypeidentifier

[Exposed=Window]interfaceUtil {constbooleanDEBUG =false;constoctetLF = 10;constunsignedlongBIT_MASK = 0x0000fc00;constdoubleAVOGADRO = 6.022e23;};

2.5.2.Attributes

Anattribute is aninterface member ornamespace member (matchinginheritAttributeRest,staticOptionalReadOnlyAttributeRest,stringifierOptionalReadOnlyAttributeRest,OptionalReadOnlyAttributeRest,orAttributeRest)that is used to declare data fields with a given type andidentifier whose value canbe retrieved and (in some cases) changed. There are two kinds of attributes:

1. regular attributes, which are thoseused to declare that objects implementing theinterface will have a data field member with the givenidentifier

   interfaceinterface_identifier {attributetypeidentifier;};

2. static attributes, which are usedto declare attributes that are not associated with a particular object implementing the interface

   interfaceinterface_identifier {staticattributetypeidentifier;};

If an attribute has nostatic keyword, then it declares aregular attribute. Otherwise,it declares astatic attribute. Note that in addition to beinginterface members,read onlyregular attributes can benamespace members as well.

Thegetter steps of an attributeattr should be introduced using text of the form “Theattr getter steps are:” followed by a list, or “Theattr getter stepsare to” followed by an inline description.

Thesetter steps of an attributeattr should be introduced using text of the form “Theattr setter steps are:” followed by a list, or “Theattr setter stepsare to” followed by an inline description.

Note: When defininggetter steps, you implicitly have access tothis.When definingsetter steps, you implicitly have access tothis andthe given value.

Theidentifier of anattribute must not be the same as the identifierof anotherinterface member defined on the sameinterface.The identifier of a static attribute must notbe "prototype".

The type of the attribute is given by the type (matchingType)that appears after theattribute keyword.If theType is anidentifier or an identifier followed by?,then the identifier mustidentify aninterface,enumeration,callback function,callback interface ortypedef.

The type of the attribute, after resolving typedefs, must not be anullable or non-nullable version of any of the following types:

• asequence type

• anasync iterable type

• adictionary type

• arecord type

• aunion type that has a nullable or non-nullable sequence type, dictionary,or recordas one of itsflattened member types

The attribute isread only if thereadonly keyword is used before theattribute keyword.An object that implements the interface on which a read only attributeis defined will not allow assignment to that attribute. It is languagebinding specific whether assignment is simply disallowed by the language,ignored or an exception is thrown.

interfaceinterface_identifier {readonlyattributetypeidentifier;};

Attributes whose type is apromise type must beread only. Additionally, they cannot haveany of theextended attributes [LegacyLenientSetter], [PutForwards], [Replaceable], or[SameObject].

Aregular attribute that is notread only can be declared toinherit its getter from an ancestor interface. This can be used to make a read only attributein an ancestor interface be writable on a derived interface. An attributeinherits its getter ifits declaration includesinherit in the declaration.The read only attribute from which the attribute inherits its getteris the attribute with the same identifier on the closest ancestor interfaceof the one on which the inheriting attribute is defined. The attributewhose getter is being inherited must beof the same type as the inheriting attribute.

Note: The grammar ensures thatinherit does not appear on aread only attributeor astatic attribute.

[Exposed=Window]interfaceAncestor {readonlyattributeTheTypetheIdentifier;};[Exposed=Window]interfaceDerived :Ancestor {inheritattributeTheTypetheIdentifier;};

When thestringifier keyword is usedin aregular attribute declaration, it indicates that objects implementing theinterface will be stringified to the value of the attribute. See§ 2.5.5 Stringifiers for details.

interfaceinterface_identifier {stringifierattributeDOMStringidentifier;};

The followingextended attributes are applicable to regular and static attributes:[CrossOriginIsolated],[Exposed],[SameObject], and[SecureContext].

The followingextended attributes are applicable only to regular attributes:[LegacyLenientSetter],[LegacyLenientThis],[PutForwards],[Replaceable],[LegacyUnforgeable].

ReadOnlyMember ::readonlyReadOnlyMemberRest

ReadOnlyMemberRest ::AttributeRestMaplikeRestSetlikeRest

ReadWriteAttribute ::AttributeRest

InheritAttribute ::inheritAttributeRest

AttributeRest ::attributeTypeWithExtendedAttributesAttributeName;

AttributeName ::AttributeNameKeywordidentifier

AttributeNameKeyword ::asyncrequired

OptionalReadOnly ::readonly    ε

[Exposed=Window]interfaceAnimal {  // A simple attribute that can be set to any string value.readonlyattributeDOMStringname;  // An attribute whose value can be assigned to.attributeunsignedshortage;};[Exposed=Window]interfacePerson :Animal {  // An attribute whose getter behavior is inherited from Animal, and need not be  // specified in the description of Person.inheritattributeDOMStringname;};

2.5.3.Operations

Anoperation is aninterface member,callback interface member ornamespace member (matchingstaticRegularOperation,stringifier,RegularOperation orSpecialOperation)that defines a behavior that can be invoked on objects implementing the interface.There are three kinds of operation:

1. regular operations, whichare those used to declare that objects implementing theinterface will have a method withthe givenidentifier

   interfaceinterface_identifier {return_typeidentifier(/* arguments... */);};

2. special operations,which are used to declare special behavior on objectsimplementing the interface, such as object indexing and stringification

   interfaceinterface_identifier {  /* special_keyword */return_typeidentifier(/* arguments... */);  /* special_keyword */return_type (/* arguments... */);};

3. static operations,which are used to declare operations that are not associated witha particular object implementing the interface

   interfaceinterface_identifier {staticreturn_typeidentifier(/* arguments... */);};

If an operation has an identifier but nostatic keyword, then it declares aregular operation.If the operation has aspecial keyword used in its declaration (that is, any keyword matchingSpecial, orthestringifier keyword),then it declares a special operation. A single operation can declareboth a regular operation and a special operation;see§ 2.5.6 Special operations for details on special operations.Note that in addition to beinginterface members,regular operations can also becallback interface members andnamespace members.

If an operation has no identifier,then it must be declared to be a special operationusing one of the special keywords.

The identifier of aregular operation orstatic operation must not be the same as the identifierof aconstant orattribute defined on the sameinterface,callback interface ornamespace.The identifier of a static operation must not be "prototype".

Note: The identifier can be the sameas that of another operation on the interface, however.This is how operation overloading is specified.

Note: Theidentifier of astatic operation can be the same as the identifierof aregular operation defined on the sameinterface.

Thereturn type of the operation is givenby the type (matchingType)that appears before the operation’s optionalidentifier.If the return type is anidentifier followed by?,then the identifier mustidentify aninterface,dictionary,enumeration,callback function,callback interface ortypedef.

An operation’s arguments (matchingArgumentList)are given between the parentheses in the declaration. Each individual argument is specifiedas a type (matchingType) followed by anidentifier (matchingArgumentName).

Note: For expressiveness, the identifier of an operation argument can also be specifiedas one of the keywords matching theArgumentNameKeyword symbol without needing to escape it.

If theType of an operation argument is an identifierfollowed by?,then the identifier must identify aninterface,enumeration,callback function,callback interface,ortypedef.If the operation argument type is anidentifier not followed by?, then the identifier mustidentify any one of those definitions or adictionary.

If the operation argument type, after resolving typedefs,is anullable type,itsinner type must not be adictionary type.

interfaceinterface_identifier {return_typeidentifier(typeidentifier,typeidentifier /* , ... */);};

The identifier of each argument must not be the sameas the identifier of another argument in the same operation declaration.

Each argument can be preceded by a list ofextended attributes (matchingExtendedAttributeList),which can control how a value passed as the argument will be handled inlanguage bindings.

interfaceinterface_identifier {return_typeidentifier([extended_attributes]typeidentifier, [extended_attributes]typeidentifier /* , ... */);};

[Exposed=Window]interfaceDimensions {attributeunsignedlongwidth;attributeunsignedlongheight;};[Exposed=Window]interfaceButton {  // An operation that takes no arguments and returns a boolean.booleanisMouseOver();  // Overloaded operations.undefinedsetDimensions(Dimensionssize);undefinedsetDimensions(unsignedlongwidth,unsignedlongheight);};

An operation orconstructor operation is considered to bevariadic if the final argument uses the... token justafter the argument type. Declaring an operation to be variadic indicates thatthe operation can be invoked with any number of arguments after that final argument.Those extra implied formal arguments are of the same type as the final explicitargument in the operation declaration. The final argument can also be omittedwhen invoking the operation. An argument must notbe declared with the... token unless itis the final argument in the operation’s argument list.

interfaceinterface_identifier {return_typeidentifier(type...identifier);return_typeidentifier(typeidentifier,type...identifier);};

Extended attributes thattake an argument list ([LegacyFactoryFunction], of thosedefined in this specification) andcallback functions are also considered to bevariadic when the... token is used in their argument lists.

[Exposed=Window]interfaceIntegerSet {readonlyattributeunsignedlongcardinality;undefinedunion(long...ints);undefinedintersection(long...ints);};

var s= getIntegerSet();// Obtain an instance of IntegerSet.s.union();// Passing no arguments corresponding to 'ints'.s.union(1,4,7);// Passing three arguments corresponding to 'ints'.

An argument is considered to be anoptional argument if it is declared with theoptional keyword.The final argument of avariadic operationis also considered to be an optional argument. Declaring an argumentto be optional indicates that the argument value can be omittedwhen the operation is invoked. The final argument in anoperation must not explicitly be declared to beoptional if the operation isvariadic.

interfaceinterface_identifier {return_typeidentifier(typeidentifier,optionaltypeidentifier);};

Optional arguments can also have adefault value specified. If the argument’s identifier is followed by a U+003D (=)and a value (matchingDefaultValue),then that gives the optional argument itsdefault value.The implicitly optional final argument of avariadic operation must not have a default value specified.The default value is the value to be assumed when the operation is called with thecorresponding argument omitted.

interfaceinterface_identifier {return_typeidentifier(typeidentifier,optionaltypeidentifier = "value");};

It is strongly suggested not to use adefault value oftrue forboolean-typed arguments, as this can be confusing for authors who might otherwise expect the default conversion ofundefined to be used (i.e.,false).[API-DESIGN-PRINCIPLES]

If the type of an argument is adictionary type or aunion type that hasadictionary type as oneof itsflattened member types, and that dictionary type and its ancestors have norequiredmembers, and the argument is either the final argument or isfollowed only byoptional arguments, then the argument must be specified asoptional and have a default value provided.

When a boolean literal token (true orfalse),thenull token,aninteger token, adecimal token or one ofthe three special floating point literal values (Infinity,-Infinity orNaN) is used as thedefault value,it is interpreted in the same way as for aconstant.

When theundefined token is used as thedefault value,the value is the IDLundefined value.

If the type of theoptional argument is anenumeration, then itsdefault value if specified mustbe one of theenumeration’s values.

Optional argument default values can also be specified using thetwo token value[], which represents an empty sequencevalue. The type of this value is the same as the type of the optionalargument it is being used as the default value of. That typemust be asequence type, anullable type whoseinner type is asequence type or aunion type ornullable union typethat has asequence type in itsflattened member types.

Optional argument default values can also be specified using the two token value{}, which represents a default-initialized (as if from ESnull or an object with no properties) dictionary value. The typeof this value is the same as the type of the optional argument it is being usedas the default value of. That type must be adictionary type, or aunion type that has adictionary type in itsflattened member types.

[Exposed=Window]interfaceColorCreator {objectcreateColor(doublev1,doublev2,doublev3,optionaldoublealpha);};

[Exposed=Window]interfaceColorCreator {objectcreateColor(doublev1,doublev2,doublev3);objectcreateColor(doublev1,doublev2,doublev3,doublealpha);};

dictionaryLookupOptions {booleancaseSensitive =false;};[Exposed=Window]interfaceAddressBook {booleanhasAddressForName(USVStringname,optionalLookupOptionsoptions = {});};

The following extended attributes are applicable to operations:[CrossOriginIsolated],[Default],[Exposed],[LegacyUnforgeable],[NewObject], and[SecureContext].

Themethod steps of an operationoperation should be introduced using text of the form“Theoperation(arg1,arg2, ...) methodsteps are:” followed by a list, or “Theoperation(arg1,arg2, ...) method steps are to” followed by an inline description.

Note: When definingmethod steps, you implicitly have access tothis.

DefaultValue ::ConstValuestring[]{}nullundefined

Operation ::RegularOperationSpecialOperation

RegularOperation ::TypeOperationRest

SpecialOperation ::SpecialRegularOperation

Special ::gettersetterdeleter

OperationRest ::OptionalOperationName(ArgumentList);

OptionalOperationName ::OperationName    ε

OperationName ::OperationNameKeywordidentifier

OperationNameKeyword ::includes

ArgumentList ::ArgumentArguments    ε

Arguments ::,ArgumentArguments    ε

Argument ::ExtendedAttributeListArgumentRest

ArgumentRest ::optionalTypeWithExtendedAttributesArgumentNameDefaultTypeEllipsisArgumentName

ArgumentName ::ArgumentNameKeywordidentifier

Ellipsis ::...    ε

ArgumentNameKeyword ::asyncattributecallbackconstconstructordeleterdictionaryenumgetterincludesinheritinterfaceiterablemaplikemixinnamespacepartialreadonlyrequiredsetlikesetterstaticstringifiertypedefunrestricted

2.5.3.1.toJSON

By declaring atoJSONregular operation,aninterface specifies how to convert the objects that implement it toJSON types.

ThetoJSONregular operation is reserved for this usage.It must take zero arguments and return aJSON type.

TheJSON types are:

• numeric types,

• boolean,

• string types,

• nullable types whoseinner type is aJSON type,

• annotated types whoseinner type is aJSON type,

• union types whosemember types areJSON types,

• typedefs whosetype being given a new name is aJSON type,

• sequence types whose parameterized type is aJSON type,

• frozen array types whose parameterized type is aJSON type,

• dictionary types where the types of allmembers declared on the dictionary and all itsinherited dictionaries areJSON types,

• records where all of theirvalues areJSON types,

• object,

• interface types that have atoJSON operation declared on themselves orone of theirinherited interfaces.

How thetoJSONregular operation is made available on an object in a language binding,and how exactly theJSON types are converted into a JSON string,is language binding specific.

Note: In the JavaScript language binding,this is done by exposing atoJSON methodwhich returns theJSON type converted into a JavaScript valuethat can be turned into a JSON stringby theJSON.stringify() function.Additionally, in the JavaScript language binding,thetoJSON operation can take a [Default]extended attribute,in which case thedefault toJSON steps are exposed instead.

[Exposed=Window]interfaceTransaction {readonlyattributeDOMStringfrom;readonlyattributeDOMStringto;readonlyattributedoubleamount;readonlyattributeDOMStringdescription;readonlyattributeunsignedlongnumber;TransactionJSONtoJSON();};dictionaryTransactionJSON {Accountfrom;Accountto;doubleamount;DOMStringdescription;};

// Get an instance of Transaction.var txn= getTransaction();// Evaluates to an object like this:// {//   from: "Bob",//   to: "Alice",//   amount: 50,//   description: "books"// }txn.toJSON();// Evaluates to a string like this:// '{"from":"Bob","to":"Alice","amount":50,"description":"books"}'JSON.stringify(txn);

2.5.4.Constructor operations

If aninterface has aconstructor operation member (matchingConstructor), it indicates that it is possible tocreate objects thatimplement theinterface using aconstructor.

Multipleconstructor operations may appear on a giveninterface.For eachconstructor operation on theinterface, there will be a way to attempt toconstruct an instance by passing the specified arguments.

Theconstructor steps of aconstructor operation that is a member of an interfacenamedinterface should be introduced using text of the form “Thenewinterface(arg1,arg2, ...) constructor stepsare:” followed by a list, or “Thenewinterface(arg1,arg2, ...) constructor stepsare to” followed by an inline description.

Theconstructor steps must do nothing, initialize the value passed asthis, or throw anexception.

If the constructor does not initializethis, one can write “Thenew Example(init) constructorsteps are to do nothing.”

See§ 3.7.1 Interface object for details on how aconstructor operation is to be implemented.

[Exposed=Window]interfaceNodeList {Nodeitem(unsignedlongindex);readonlyattributeunsignedlonglength;};[Exposed=Window]interfaceCircle {constructor();constructor(doubleradius);attributedoubler;attributedoublecx;attributedoublecy;readonlyattributedoublecircumference;};

var x=new Circle();// This uses the zero-argument constructor to create a// reference to a platform object that implements the// Circle interface.var y=new Circle(1.25);// This also creates a Circle object, this time using// the one-argument constructor.var z=new NodeList();// This would throw a TypeError, since no// constructor is declared.

Constructor ::constructor(ArgumentList);

ArgumentList ::ArgumentArguments    ε

Arguments ::,ArgumentArguments    ε

Argument ::ExtendedAttributeListArgumentRest

ArgumentRest ::optionalTypeWithExtendedAttributesArgumentNameDefaultTypeEllipsisArgumentName

ArgumentName ::ArgumentNameKeywordidentifier

Ellipsis ::...    ε

ArgumentNameKeyword ::asyncattributecallbackconstconstructordeleterdictionaryenumgetterincludesinheritinterfaceiterablemaplikemixinnamespacepartialreadonlyrequiredsetlikesetterstaticstringifiertypedefunrestricted

2.5.5.Stringifiers

When aninterface has astringifier, it indicates that objectsthat implement the interface have a non-default conversion to a string. Stringifiers can bespecified using astringifier keyword, which creates a stringifier operation whenused alone.

interfaceinterface_identifier {stringifier;};

Prose accompanying the interface must definethestringification behavior of the interface.

Thestringifier keywordcan also be placed on anattribute.In this case, the string to convert the object to is thevalue of the attribute. Thestringifier keywordmust not be placed on an attribute unlessit is declared to be of typeDOMString orUSVString.It also must not be placed onastatic attribute.

interfaceinterface_identifier {stringifierattributeDOMStringidentifier;};

On a giveninterface, there must exist at most one stringifier.

Stringifier ::stringifierStringifierRest

StringifierRest ::OptionalReadOnlyAttributeRest;

[Exposed=Window]interfaceStudent {constructor();attributeunsignedlongid;stringifierattributeDOMStringname;};

var s=new Student();s.id=12345678;s.name='周杰倫';var greeting='Hello, '+ s+'!';// Now greeting == 'Hello, 周杰倫!'.

[Exposed=Window]interfaceStudent {constructor();attributeunsignedlongid;attributeDOMString?familyName;attributeDOMStringgivenName;stringifier;};

var s=new Student();s.id=12345679;s.familyName='Smithee';s.givenName='Alan';var greeting='Hi '+ s;// Now greeting == 'Hi Alan Smithee'.

2.5.6.Special operations

Aspecial operation is adeclaration of a certain kind of special behavior on objects implementingthe interface on which the special operation declarations appear.Special operations are declared by using aspecial keyword in an operation declaration.

There are three kinds of special operations. The table below indicatesfor a given kind of special operation what special keywordis used to declare it and what the purpose of the special operation is:

Not all language bindings support all of the four kinds of specialobject behavior. When special operations are declared usingoperations with no identifier, then in language bindings that donot support the particular kind of special operations there simplywill not be such functionality.

[Exposed=Window]interfaceDictionary {readonlyattributeunsignedlongpropertyCount;getterdouble (DOMStringpropertyName);setterundefined (DOMStringpropertyName,doublepropertyValue);};

Defining a special operation with anidentifier is equivalent to separating the special operation out into its owndeclaration without an identifier. This approach is allowed tosimplifymethod steps of an interface’s operations.

[Exposed=Window]interfaceDictionary {readonlyattributeunsignedlongpropertyCount;getterdoublegetProperty(DOMStringpropertyName);setterundefinedsetProperty(DOMStringpropertyName,doublepropertyValue);};

[Exposed=Window]interfaceDictionary {readonlyattributeunsignedlongpropertyCount;doublegetProperty(DOMStringpropertyName);undefinedsetProperty(DOMStringpropertyName,doublepropertyValue);getterdouble (DOMStringpropertyName);setterundefined (DOMStringpropertyName,doublepropertyValue);};

A givenspecial keyword must notappear twice on an operation.

Getters and setters come in two varieties: ones thattake aDOMString as a property name,known asnamed property getters andnamed property setters,and ones that take anunsigned long as a property index, known asindexed property getters andindexed property setters.There is only one variety of deleter:named property deleters.See§ 2.5.6.1 Indexed properties and§ 2.5.6.2 Named properties for details.

On a giveninterface,there must exist at most onenamed property deleter,and at most one of each variety of getter and setter.

If an interface has a setter of a given variety,then it must also have a getter of thatvariety. If it has anamed property deleter,then it must also have anamed property getter.

Special operations declared using operations must notbevariadic nor have anyoptional arguments.

If an object implements more than oneinterface that defines a given special operation, then it is undefined which (if any)special operation is invoked for that operation.

2.5.6.1.Indexed properties

Aninterface that defines anindexed property getter is said tosupport indexed properties.By extension, aplatform object is said tosupport indexed properties ifit implements aninterface that itself does.

If an interfacesupports indexed properties,then the interface definition must be accompanied bya description of what indices the object can be indexed with atany given time. These indices are called thesupported property indices.

Interfaces thatsupport indexed properties must defineaninteger-typedattribute named "length".

Indexed property getters mustbe declared to take a singleunsigned long argument.Indexed property setters mustbe declared to take two arguments, where the first is anunsigned long.

interfaceinterface_identifier {gettertypeidentifier(unsignedlongidentifier);settertypeidentifier(unsignedlongidentifier,typeidentifier);gettertype (unsignedlongidentifier);settertype (unsignedlongidentifier,typeidentifier);};

The following requirements apply to the definitions of indexed property getters and setters:

• If anindexed property getter was specified using anoperation with anidentifier,then the value returned when indexing the object with a givensupported property index is the value that would be returned by invoking the operation, passingthe index as its only argument. If the operation used to declare the indexed property getterdid not have an identifier, then the interface definition must be accompaniedby a description of how todetermine the value of an indexed property for a given index.

• If anindexed property setter was specified using an operationwith an identifier,then the behavior that occurs when indexing the object for property assignment with a given supported property index and valueis the same as if the operation is invoked, passingthe index as the first argument and the value as the second argument. If the operation used to declare the indexed property setterdid not have an identifier, then the interface definition must be accompaniedby a description of how toset the value of an existing indexed property and how toset the value of a new indexed property for a given property index and value.

[Exposed=Window]interfaceA {getterDOMStringtoWord(unsignedlongindex);};

var a= getA();a.toWord(0);// Evalautes to "zero".a[0];// Also evaluates to "zero".a.toWord(5);// Evaluates to "five".a[5];// Evaluates to undefined, since there is no property "5".

[Exposed=Window]interfaceOrderedMap {readonlyattributeunsignedlongsize;getteranygetByIndex(unsignedlongindex);setterundefinedsetByIndex(unsignedlongindex,anyvalue);getteranyget(DOMStringname);setterundefinedset(DOMStringname,anyvalue);};

// Assume map is a legacy platform object implementing the OrderedMap interface.var map= getOrderedMap();var x, y;x= map[0];// If map.length > 0, then this is equivalent to:////   x = map.getByIndex(0)//// since a property named "0" will have been placed on map.// Otherwise, x will be set to undefined, since there will be// no property named "0" on map.map[1]=false;// This will do the equivalent of:////   map.setByIndex(1, false)y= map.apple;// If there exists a named property named "apple", then this// will be equivalent to:////   y = map.get('apple')//// since a property named "apple" will have been placed on// map.  Otherwise, y will be set to undefined, since there// will be no property named "apple" on map.map.berry=123;// This will do the equivalent of:////   map.set('berry', 123)delete map.cake;// If a named property named "cake" exists, then the "cake"// property will be deleted, and then the equivalent to the// following will be performed:////   map.remove("cake")

2.5.6.2.Named properties

Aninterface that defines anamed property getter is said tosupport named properties.By extension, aplatform object is said tosupport named properties ifit implements aninterface that itself does.

If an interfacesupports named properties,then the interface definition must be accompanied bya description of the ordered set of names that can be used to index the objectat any given time. These names are called thesupported property names.

Named property getters and deleters mustbe declared to take a singleDOMString argument.Named property setters mustbe declared to take two arguments, where the first is aDOMString.

interfaceinterface_identifier {gettertypeidentifier(DOMStringidentifier);settertypeidentifier(DOMStringidentifier,typeidentifier);deletertypeidentifier(DOMStringidentifier);gettertype (DOMStringidentifier);settertype (DOMStringidentifier,typeidentifier);deletertype (DOMStringidentifier);};

The following requirements apply to the definitions of named property getters, setters and deleters:

• If anamed property getter was specified using anoperation with anidentifier,then the value returned when indexing the object with a givensupported property name is the value that would be returned by invoking the operation, passingthe name as its only argument. If the operation used to declare the named property getterdid not have an identifier, then the interface definition must be accompaniedby a description of how todetermine the value of a named property for a given property name.

• If anamed property setter was specified using an operationwith an identifier,then the behavior that occurs when indexing the object for property assignment with a given supported property name and valueis the same as if the operation is invoked, passingthe name as the first argument and the value as the second argument. If the operation used to declare the named property setterdid not have an identifier, then the interface definition must be accompaniedby a description of how toset the value of an existing named property and how toset the value of a new named property for a given property name and value.

• If anamed property deleter was specified using an operationwith an identifier,then the behavior that occurs when indexing the object for property deletion with a given supported property nameis the same as if the operation is invoked, passingthe name as the only argument. If the operation used to declare the named property deleterdid not have an identifier, then the interface definition must be accompaniedby a description of how todelete an existing named property for a given property name.

Note: As withindexed properties,if annamed property getter,setter ordeleter is specified using anoperation with anidentifier,then indexing an object with a name that is not asupported property name does not necessarily elicit the same behavior as invoking the operation with that name; the behavioris language binding specific.

2.5.7.Static attributes and operations

Static attributes andstatic operations are ones thatare not associated with a particular instance of theinterface on which it is declared, and is instead associated with the interfaceitself. Static attributes and operations are declared by using thestatic keyword in their declarations.

It is language binding specific whether it is possible to invokea static operation or get or set a static attribute through a referenceto an instance of the interface.

StaticMember ::staticStaticMemberRest

StaticMemberRest ::OptionalReadOnlyAttributeRestRegularOperation

[Exposed=Window]interfacePoint { /* ... */ };[Exposed=Window]interfaceCircle {attributedoublecx;attributedoublecy;attributedoubleradius;staticreadonlyattributelongtriangulationCount;staticPointtriangulate(Circlec1,Circlec2,Circlec3);};

var circles= getCircles();// an Array of Circle objectstypeof Circle.triangulate;// Evaluates to "function"typeof Circle.triangulationCount;// Evaluates to "number"Circle.prototype.triangulate;// Evaluates to undefinedCircle.prototype.triangulationCount;// Also evaluates to undefinedcircles[0].triangulate;// As does thiscircles[0].triangulationCount;// And this// Call the static operationvar triangulationPoint= Circle.triangulate(circles[0], circles[1], circles[2]);// Find out how many triangulations we have donewindow.alert(Circle.triangulationCount);

2.5.8.Overloading

If aregular operation orstatic operation defined on aninterface has anidentifier that is the same as the identifier of another operation on thatinterface of the same kind (regular or static), then the operation is said to beoverloaded. When the identifierof an overloaded operation is used to invoke one of theoperations on an object that implements the interface, thenumber and types of the arguments passed to the operationdetermine which of the overloaded operations is actuallyinvoked.Constructor operations can be overloaded too.There are some restrictions on the argumentsthat overloaded operations and constructors can bespecified to take, and in order to describe these restrictions,the notion of aneffective overload set is used.

A set of overloadedoperations must either:

• contain nooperations whosereturn type is apromise type;

• only containoperations whosereturn type is apromise type.

Operations must not be overloaded acrossinterface,partial interface,interface mixin, andpartial interface mixin definitions.

[Exposed=Window]interfaceA {undefinedf();};partialinterfaceA {undefinedf(doublex);undefinedg();};partialinterfaceA {undefinedg(DOMStringx);};

Aneffective overload set represents the allowable invocations for a particularoperation,constructor (specified with aconstructor operation or [LegacyFactoryFunction]), orcallback function.The algorithm tocompute the effective overload set operates on one of the following four types of IDL constructs, and listed with them below arethe inputs to the algorithm needed to compute the set.

For regular operations

For static operations

• theinterface on which theoperations are to be found

• theidentifier of the operations

• the number of arguments to be passed

For constructors

• theinterface on which theconstructor operations are to be found

• the number of arguments to be passed

For legacy factory functions

• theinterface on which the [LegacyFactoryFunction]extended attributes are to be found

• theidentifier of the legacy factory function

• the number of arguments to be passed

Aneffective overload set is used, among other things, to determine whether there areambiguities in the overloaded operations and constructors specified on an interface.

Theitems of aneffective overload set aretuples of the form(callable,type list,optionality list)whoseitems are described below:

• Acallable is anoperation if theeffective overload set is forregular operations,static operations, orconstructor operations; and it is anextended attribute if theeffective overload set is forlegacy factory functions.

• Atype list is alist of IDL types.

• Anoptionality list is alist ofthree possibleoptionality values – "required", "optional" or "variadic" –indicating whether the argument at a given index wasdeclared as beingoptional or corresponds to avariadic argument.

Eachtuple represents an allowable invocation of the operation,constructor, or callback function with an argument value list of the given types.Due to the use ofoptional arguments andvariadic operationsand constructors, there may be multiple items in aneffective overload set identifyingthe same operation or constructor.

[Exposed=Window]interfaceA {  /* f1 */undefinedf(DOMStringa);  /* f2 */undefinedf(Nodea,DOMStringb,double...c);  /* f3 */undefinedf();  /* f4 */undefinedf(Eventa,DOMStringb,optionalDOMStringc,double...d);};

«  (f1, « DOMString »,                           « required »),  (f2, « Node, DOMString »,                     « required, required »),  (f2, « Node, DOMString, double »,             « required, required, variadic »),  (f2, « Node, DOMString, double, double »,     « required, required, variadic, variadic »),  (f3, « »,                                     « »),  (f4, « Event, DOMString »,                    « required, required »),  (f4, « Event, DOMString, DOMString »,         « required, required, optional »),  (f4, « Event, DOMString, DOMString, double », « required, required, optional, variadic »)»

Two types aredistinguishable ifthe following algorithm returnstrue.

1. If one typeincludes a nullable type and the other type eitherincludes a nullable type,is aunion type withflattened member types including adictionary type, oris adictionary type,returnfalse.

   None of the following pairs are distinguishable:

   • double? andDictionary1
   • (Interface1 orlong)? and(Interface2 orDOMString)?
   • (Interface1 orlong?) and(Interface2 orDOMString)?
   • (Interface1 orlong?) and(Interface2 orDOMString?)
   • (Dictionary1 orlong) and(Interface2 orDOMString)?
   • (Dictionary1 orlong) and(Interface2 orDOMString?)

2. If both types are either aunion type ornullableunion type,returntrue if each member type of the oneis distinguishable with each member type of the other,orfalse otherwise.

3. If one type is aunion type or nullable union type,returntrue if eachmember type of the union type is distinguishablewith the non-union type,orfalse otherwise.

4. Consider the two "innermost" types derived by taking each type’sinner type if it is anannotated type, and then taking itsinner type inner typeif the result is anullable type. If these two innermost types appear or are in categoriesappearing in the following table and there is a “●” mark in the corresponding entryor there is a letter in the corresponding entry and the designated additionalrequirement below the table is satisfied, then returntrue.Otherwise returnfalse.

   Categories:

   interface-like

   • interface types

   • buffer source types

   dictionary-like

   • dictionary types

   • record types

   • callback interface types

   sequence-like

   • sequence types

   • frozen array types

   	undefined	boolean	numeric types	bigint	string types	object	symbol	interface-like	callback function	dictionary-like	async iterable	sequence-like
   undefined		●	●	●	●	●	●	●	●		●	●
   boolean			●	●	●	●	●	●	●	●	●	●
   numeric types				(b)	●	●	●	●	●	●	●	●
   bigint					●	●	●	●	●	●	●	●
   string types						●	●	●	●	●	(d)	●
   object							●
   symbol								●	●	●	●	●
   interface-like								(a)	●	●	●	●
   callback function										(c)	●	●
   dictionary-like											●	●
   async iterable
   sequence-like

   1. The two identified interface-like types arenot the same, and no singleplatform object implements bothinterface-like types.

   2. The types are distinguishable, but there isa separate restriction on their use inoverloading below. Please also notetheadvice about using unions of these types.

   3. Acallback function that does not have[LegacyTreatNonObjectAsNull] extended attribute isdistinguishable from a type in the dictionary-like category.

      For example, when converting an ECMAScript value tounion type which includes acallback function and a dictionary-like type, if the value iscallable, then it is converted to acallback function. Otherwise, it is converted to a dictionary-like type.

   4. The types are distinguishable, but when converting from an ECMAScript value,astring object is never converted to anasync iterable type (even if it has a%Symbol.iterator% method), if astring type is also in the overload set or union.

   double andDOMString are distinguishable because there is a ● at the intersection ofnumeric types withstring types.
   double andlong are not distinguishable because they are bothnumeric types, and there is no ● or letter at the intersection ofnumeric types withnumeric types.
   Given:

   callbackinterfaceCBIface {undefinedhandle();};[Exposed=Window]interfaceIface {attributeDOMStringattr2;};dictionaryDict {DOMStringfield1;};

   CBIface is distinguishable fromIface because there’s a ● at the intersection of dictionary-like and interface-like, but it is not distinguishable fromDict because there’s no ● at the intersection of dictionary-like and itself.

   Promise types do not appear in the above table, and as a consequence are not distinguishable with any other type.

If there is more than oneitem in aneffective overload set that has a giventype listsize,then for those items there must be an indexi such thatfor each pair of items the types at indexi aredistinguishable.The lowest such index is termed thedistinguishing argument index for the items of theeffective overload set with the given type list size.

Aneffective overload set must not contain more thanoneitem with the sametype listsize, where oneitem has abigint argument at thedistinguishing argument index and another has anumeric type argument at thedistinguishing argument index.

[Exposed=Window]interfaceB {undefinedf(DOMStringx);undefinedf(USVStringx);};

In addition, for each indexj, wherej is less than thedistinguishing argument index for a given type list size, the types at indexj inall of the items' type lists must be the same,and theoptionality values at indexj in all of the items' optionality lists mustbe the same.

[Exposed=Window]interfaceB {  /* f1 */undefinedf(DOMStringw);  /* f2 */undefinedf(longw,doublex,Nodey,Nodez);  /* f3 */undefinedf(doublew,doublex,DOMStringy,Nodez);};

«  (f1, « DOMString »,                       « required »),  (f2, « long, double, Node, Node »,        « required, required, required, required »),  (f3, « double, double, DOMString, Node », « required, required, required, required »)»

2.5.8.1.Overloading vs. union types

This section is informative.

interfaceCanvasDrawPathExcerpt {undefinedstroke();undefinedstroke(Path2Dpath);};

interfaceCanvasDrawPathExcerptOptional {undefinedstroke(optionalPath2Dpath);};

2.5.9.Iterable declarations

Aninterface can be declared to beiterable by using aniterable declaration (matchingIterable) in the body of the interface.

interfaceinterface_identifier {iterable<value_type>;iterable<key_type,value_type>;};

Objects implementing an interface that is declared to be iterablesupport being iterated over to obtain a sequence of values.

Note: In the JavaScript language binding, an interface that is iterablewill haveentries,forEach,keys,values, and%Symbol.iterator% properties on itsinterface prototype object.

If a single type parameter is given, then the interface has avalue iterator and providesvalues of the specified type.If two type parameters are given, then the interface has apair iterator and providesvalue pairs with the given types.

Avalue pair, given a key type and a value type, is astruct with twoitems:

1. anitem whosename is "key", which is referred to as thevalue pair’skey, and whose value is an IDL value of the key type;

2. anitem whosename is "value", which is referred to as thevalue pair’svalue, and whose value is an IDL value of thevalue type.

Avalue iterator must only be declared on an interfacethatsupports indexed properties.The value-type of thevalue iterator must be the same as the type returned bytheindexed property getter.Avalue iterator is implicitlydefined to iterate over the object’s indexed properties.

Apair iterator must not be declared on an interfacethatsupports indexed properties.

Prose accompanying aninterface with apair iterator must define alist ofvalue pairs for each instance of theinterface, which is the list ofvalue pairs to iterate over.

Note: This is howarray iterator objects work.For interfaces thatsupport indexed properties,the iterator objects returned byentries,keys,values, and%Symbol.iterator% areactualarray iterator objects.

Interfaces with aniterable declaration must not have anyattributes,constants, orregular operations named "entries", "forEach", "keys", or"values", or have anyinherited interfaces that haveattributes,constants,orregular operations with these names.

[Exposed=Window]interfaceSessionManager {SessiongetSessionForUser(DOMStringusername);iterable<DOMString,Session>;};[Exposed=Window]interfaceSession {readonlyattributeDOMStringusername;  // ...};

// Get an instance of SessionManager.// Assume that it has sessions for two users, "anna" and "brian".var sm= getSessionManager();typeof SessionManager.prototype.values;// Evaluates to "function"var it= sm.values();// values() returns an iterator objectString(it);// Evaluates to "[object SessionManager Iterator]"typeof it.next;// Evaluates to "function"// This loop will log "anna" and then "brian".for(;;){let result= it.next();if(result.done){break;}let session= result.value;  console.log(session.username);}// This loop will also log "anna" and then "brian".for(let usernameof sm.keys()){  console.log(username);}// Yet another way of accomplishing the same.for(let[username, session]of sm){  console.log(username);}

An interface must not have more than oneiterable declaration.Theinherited interfaces of an interface with aniterable declaration must not also have aniterable declaration.An interface with aniterable declaration and itsinherited interfaces must not have amaplike declaration,setlike declaration, orasynchronously iterable declaration.

The following extended attributes are applicable toiterable declarations:[CrossOriginIsolated],[Exposed], and[SecureContext].

Iterable ::iterable<TypeWithExtendedAttributesOptionalType>;

OptionalType ::,TypeWithExtendedAttributes    ε

2.5.10.Asynchronously iterable declarations

Aninterface can be declared to be asynchronously iterable by using anasynchronously iterable declaration (matchingAsyncIterable) in the body of theinterface.

interfaceinterface_identifier {asynciterable<value_type>;asynciterable<value_type>(/* arguments... */);asynciterable<key_type,value_type>;asynciterable<key_type,value_type>(/* arguments... */);};

Objects thatimplement aninterface that is declared to be asynchronously iterable supportbeing iterated over asynchronously to obtain a sequence of values.

If a single type parameter is given, then the interface has avalue asynchronously iterable declaration and asynchronously provides values of thespecified type. If two type parameters are given, then the interface has apair asynchronously iterable declaration and asynchronously providesvalue pairs with the given types.

If given, anasynchronously iterable declaration’s arguments (matchingArgumentList) must all beoptional arguments.

Prose accompanying aninterface with anasynchronously iterable declaration must define aget the next iteration result algorithm.This algorithm receives the instance of theinterface that is being iterated, as well as theasync iterator itself (which can be useful for storing state).It must return aPromise that either rejects, resolves with a specialend ofiteration value to signal the end of the iteration, or resolves with one of the following:

forvalue asynchronously iterable declarations:

a value of the type given in the declaration;

forpair asynchronously iterable declarations:

atuple containing a value of the first type given in the declaration, and a value of the second type given in the declaration.

The prose may also define anasynchronous iterator return algorithm. Thisalgorithm receives the instance of theinterface that is being iterated, the async iteratoritself, and a single argument value of typeany. This algorithm is invoked in the case ofpremature termination of the async iterator. It must return aPromise; if that promisefulfills, its fulfillment value will be ignored, but if it rejects, that failure will be passed onto users of the async iterator API.

In the JavaScript binding, this algorithm allows customizing the behavior when theasync iterator’sreturn() method is invoked. This most commonly occurs when abreak orreturn statement causes an exit from afor-await-of loop.

We could add a similar hook forthrow(). So far there has been no need,but if you are creating an API that needs such capabilities, pleasefile an issue.

The prose may also defineasynchronous iterator initialization steps. Thesereceive the instance of theinterface being iterated, the newly-created iterator object, and alist of IDL values representing the arguments passed, if any.

Interfaces with anasynchronously iterable declaration must not have anyattributes,constants, orregular operations named "entries", "keys", or"values", or have anyinherited interfaces that haveattributes,constants,orregular operations with these names.

[Exposed=Window]interfaceSessionManager {SessiongetSessionForUser(DOMStringusername);asynciterable<DOMString,Session>;};[Exposed=Window]interfaceSession {readonlyattributeDOMStringusername;  // ...};

// Get an instance of SessionManager.// Assume that it has sessions for two users, "anna" and "brian".var sm= getSessionManager();typeof SessionManager.prototype.values;// Evaluates to "function"var it= sm.values();// values() returns an iterator objecttypeof it.next;// Evaluates to "function"// This loop will log "anna" and then "brian".forawait(let usernameof sm.keys()){  console.log(username);}// Yet another way of accomplishing the same.forawait(let[username, session]of sm){  console.log(username);}

Aninterface must not have more than oneasynchronously iterable declaration.Theinherited interfaces of aninterface with anasynchronously iterable declaration must not also have anasynchronously iterable declaration.Aninterface with anasynchronously iterable declaration and itsinherited interfaces must not have amaplike declaration,setlike declaration, oriterable declaration.

The following extended attributes are applicable toasynchronously iterable declarations:[CrossOriginIsolated],[Exposed], and[SecureContext].

theseextended attributes are not currently taken into account.When they are, the effect will be as you would expect.

AsyncIterable ::asynciterable<TypeWithExtendedAttributesOptionalType>OptionalArgumentList;

OptionalArgumentList ::(ArgumentList)    ε

2.5.11.Maplike declarations

Aninterface can be declared to bemaplike by using amaplike declaration (matchingReadWriteMaplike orreadonlyMaplikeRest) in the body of the interface.

interfaceinterface_identifier {readonlymaplike<key_type,value_type>;maplike<key_type,value_type>;};

Objects implementing an interface that is declared to be maplikerepresent anordered map of key–value pairs, initially empty,known as that object’smap entries.The types used for the keys and values are given in the anglebrackets of the maplike declaration. Keys are required to be unique.

Specification authors can modify the contents of themap entries,which will automatically be reflected in the contents of the objectas observed by JavaScript code.

Maplike interfaces support an API for querying the map entriesappropriate for the language binding. If thereadonly keyword is not used, then it also supports an API for modifyingthe map entries.

Note: In the JavaScript language binding, the API for interactingwith the map entries is similar to that available on JavaScriptMap objects. If thereadonly keyword is used, this includesentries,forEach,get,has,keys,values,%Symbol.iterator% methods, and asize getter.For read–write maplikes, it also includesclear,delete, andset methods.

Maplike interfaces must not have anyattributes,constants, orregular operations named"entries", "forEach", "get", "has","keys", "size", or "values", or have anyinherited interfaces that haveattributes,constants, orregular operations withthese names.

Read–write maplike interfaces must nothave anyattributes orconstants named"clear", "delete",or "set", or have anyinherited interfaces that haveattributes orconstants with these names.

Note: Read-write maplike interfacescan haveregular operations named"clear", "delete", or "set", which will override the defaultimplementation of those methods (defined in§ 3.7.11 Maplike declarations). If such regular operations aredefined, they must match the input and output expectations of each method, defined in their defaultimplementation sections.

An interface must not have more than onemaplike declaration.Theinherited interfaces of a maplike interface must notalso have amaplike declaration.A maplike interface and itsinherited interfaces must not have aniterable declaration,anasynchronously iterable declaration,asetlike declaration, oranindexed property getter.

ReadOnlyMember ::readonlyReadOnlyMemberRest

ReadOnlyMemberRest ::AttributeRestMaplikeRestSetlikeRest

ReadWriteMaplike ::MaplikeRest

MaplikeRest ::maplike<TypeWithExtendedAttributes,TypeWithExtendedAttributes>;

Noextended attributes defined in this specification are applicable tomaplike declarations.

Add example.

2.5.12.Setlike declarations

Aninterface can be declared to besetlike by using asetlike declaration (matchingReadWriteSetlike orreadonlySetlikeRest) in the body of the interface.

interfaceinterface_identifier {readonlysetlike<type>;setlike<type>;};

Objects implementing an interface that is declared to be setlikerepresent anordered set of values, initially empty,known as that object’sset entries.The type of the values is given in the anglebrackets of the setlike declaration. Values are required to be unique.

Specification authors can modify the contents of theset entries,which will automatically be reflected in the contents of the objectas observed by JavaScript code.

Setlike interfaces support an API for querying the set entriesappropriate for the language binding. If thereadonly keyword is not used, then it also supports an API for modifyingthe set entries.

Note: In the JavaScript language binding, the API for interactingwith the set entries is similar to that available on JavaScriptSet objects. If thereadonly keyword is used, this includesentries,forEach,has,keys,values,%Symbol.iterator% methods, and asize getter.For read–write setlikes, it also includesadd,clear, anddelete methods.

Setlike interfaces must not have anyattributes,constants, orregular operations named"entries", "forEach", "has", "keys","size", or "values", or have anyinherited interfaces that haveattributes,constants, orregular operations with these names.

Read–write setlike interfaces must nothave anyattributes orconstants named"add", "clear",or "delete", or have anyinherited interfaces that haveattributes orconstants with these names.

Note: Read-write setlike interfacescan haveregular operations named"add", "clear", or "delete", which will override the defaultimplementation of those methods (defined in§ 3.7.12 Setlike declarations). If such regular operations aredefined, they must match the input and output expectations of each method, defined in their defaultimplementation sections.

An interface must not have more than onesetlike declaration.Theinherited interfaces of a setlike interface must notalso have asetlike declaration.A setlike interface and itsinherited interfaces must not have aniterable declaration,anasynchronously iterable declaration,amaplike declaration, oranindexed property getter.

ReadOnlyMember ::readonlyReadOnlyMemberRest

ReadOnlyMemberRest ::AttributeRestMaplikeRestSetlikeRest

ReadWriteSetlike ::SetlikeRest

SetlikeRest ::setlike<TypeWithExtendedAttributes>;

Noextended attributes defined in this specification are applicable tosetlike declarations.

Add example.

2.6.Namespaces

Anamespace is a definition (matchingNamespace) that declares a global singleton withassociated behaviors.

namespaceidentifier {  /* namespace_members... */};

A namespace is a specification of a set ofnamespace members (matchingNamespaceMembers), which are theregular operations,read onlyregular attributes, andconstants that appear betweenthe braces in the namespace declaration. These operations and attributes describe the behaviorspackaged into the namespace.

As with interfaces, the IDL for namespaces can be split into multiple parts by usingpartial namespace definitions(matchingpartialNamespace). Theidentifier of a partial namespace definition must be the same as the identifier of a namespace definition.All of the members that appear on each of the partial namespace definitions areconsidered to be members of the namespace itself.

namespaceSomeNamespace {  /* namespace_members... */};partialnamespaceSomeNamespace {  /* namespace_members... */};

Note: As with partial interface definitions, partial namespace definitions are intended foruse as a specification editorial aide, allowing the definition of a namespace to beseparated over more than one section of the document, and sometimes multipledocuments.

The order that members appear in has significance for property enumeration in theJavaScript binding.

Note that unlike interfaces or dictionaries, namespaces do not create types.

Of the extended attributes defined in this specification, only the [CrossOriginIsolated], [Exposed], and [SecureContext] extended attributes are applicable to namespaces.

Namespaces must be annotated with the [Exposed]extended attribute.

Partial ::partialPartialDefinition

PartialDefinition ::interfacePartialInterfaceOrPartialMixinPartialDictionaryNamespace

Namespace ::namespaceidentifier{NamespaceMembers};

NamespaceMembers ::ExtendedAttributeListNamespaceMemberNamespaceMembers    ε

NamespaceMember ::RegularOperationreadonlyAttributeRestConst

namespaceVectorUtils {readonlyattributeVectorunit;doubledotProduct(Vectorx,Vectory);VectorcrossProduct(Vectorx,Vectory);};

Object.getPrototypeOf(VectorUtils);// Evaluates to Object.prototype.Object.keys(VectorUtils);// Evaluates to ["dotProduct", "crossProduct"].Object.getOwnPropertyDescriptor(VectorUtils,"dotProduct");// Evaluates to { value: <a function>, enumerable: true, configurable: true, writable: true }.Object.getOwnPropertyDescriptor(VectorUtils,"unit");// Evaluates to { get: <a function>, enumerable: true, configurable: true }.

2.7.Dictionaries

Adictionary is a definition (matchingDictionary)used to define anordered map data type with a fixed, ordered set ofentries,termeddictionary members,wherekeys are strings andvalues are of a particular type specified in the definition.

dictionaryidentifier {  /* dictionary_members... */};

Dictionary instances do not retain a reference to their language-specific representations (e.g.,the corresponding JavaScript object). So for example, returning a dictionary from anoperation will result in a new JavaScript object being created from the current values of the dictionary. And,an operation that accepts a dictionary as an argument will perform a one-time conversion from thegiven JavaScript value into the dictionary, based on the current properties of the JavaScriptobject. Modifications to the dictionary will not be reflected in the corresponding JavaScriptobject, and vice-versa.

Dictionaries must not be used as the type of anattribute orconstant.

A dictionary can be defined toinherit from another dictionary.If the identifier of the dictionary is followed by a colon and aidentifier,then that identifier identifies the inherited dictionary. The identifiermust identify a dictionary.

A dictionary must not be declared such thatits inheritance hierarchy has a cycle. That is, a dictionaryA cannot inherit from itself, nor can it inherit from anotherdictionaryB that inherits fromA, and so on.

dictionaryBase {  /* dictionary_members... */};dictionaryDerived :Base {  /* dictionary_members... */};

Theinherited dictionaries ofa given dictionaryD is the set of all dictionaries thatD inherits from, directly or indirectly. IfD does notinherit from another dictionary, then the set is empty. Otherwise, the setincludes the dictionaryE thatDinherits from and all ofE’sinherited dictionaries.

Dictionary members can be specified asrequired, meaning thatconverting a language-specific value to a dictionary requires providing a value for that member. Anydictionary member that is notrequired isoptional.

Note that specifyingdictionary members asrequired only hasan observable effect when converting other representations of dictionaries (like a JavaScript valuesupplied as an argument to anoperation) to an IDL dictionary. Specification authors shouldleave the membersoptional in all other cases, including when a dictionarytype is used solely as thereturn type ofoperations.

A given dictionary value of typeD can haveentries for each of the dictionary membersdefined onD and on any ofD’sinherited dictionaries. Dictionary members that are specifiedasrequired, or that are specified as having adefault value, will always have such correspondingentries. Othermembers' entries might or might notexist in the dictionary value.

In the JavaScript binding, a value ofundefined for the property corresponding to adictionary member is treated the same as omitting that property. Thus, it will cause an error if the member isrequired, or will trigger thedefault value if one is present, or will result in noentry existing in the dictionary value otherwise.

As withoperation argument default values, it is strongly encouraged not to usetrue as thedefault value forboolean-typeddictionary members, as this can be confusing for authors who might otherwise expect the default conversion ofundefined to be used (i.e.,false).[API-DESIGN-PRINCIPLES]

Anordered map with stringkeys can be implicitly treated as a dictionary value of aspecific dictionaryD if all of itsentries correspond todictionary members, as longas those entries have the correct types, and there areentries present for anyrequired ordefaulted dictionary members.

dictionaryDescriptor {DOMStringname;sequence<unsignedlong>serviceIdentifiers;};

Eachdictionary member (matchingDictionaryMember) is specifiedas a type (matchingType) followed by anidentifier (given by anidentifier token followingthe type). The identifier is the key name of the key–value pair.If theType is anidentifier followed by?, then the identifiermust identify aninterface,enumeration,callback function,callback interface ortypedef.If the dictionary member type is an identifiernot followed by?, then the identifier mustidentify any one of those definitions or adictionary.

If the type of thedictionary member, after resolving typedefs,is anullable type,itsinner type must not be adictionary type.

dictionaryidentifier {typeidentifier;};

If the identifier for anoptionaldictionary member is followed by aU+003D (=) and a value (matchingDefaultValue), then that gives the dictionary member itsdefault value, whichis the value used by default when author code or specification text does not provide a value forthat member.

dictionaryidentifier {typeidentifier = "value";};

When a boolean literal token (true orfalse),thenull token,aninteger token, adecimal token,one of the three special floating point literal values (Infinity,-Infinity orNaN),astring token, the twotoken sequence[], or the two token sequence{} isused as thedefault value,it is interpreted in the same way as for anoperation’soptional argument default value.

If the type of thedictionary member is anenumeration, then itsdefault value if specified mustbe one of theenumeration’s values.

If the type of the dictionary member is preceded by therequired keyword, the member is considered arequireddictionary member.

dictionaryidentifier {requiredtypeidentifier;};

The type of a dictionary member must not includethe dictionary it appears on. A type includes a dictionaryD if at least one of the following is true:

• the type isD

• the type is a dictionary thatinherits fromD

• the type is anullable type whoseinner type includesD

• the type is asequence type orfrozen array whose element type includesD

• the type is aunion type,one of whosemember types includesD

• the type is a dictionary, one of whose members or inherited members hasa type that includesD

• the type isrecord<K,V> whereV includesD

As with interfaces, the IDL for dictionaries can be split into multiple partsby usingpartial dictionary definitions(matchingpartialDictionary).Theidentifier of a partialdictionary definition must be the same as theidentifier of a dictionary definition. All of the members that appear on eachof the partial dictionary definitions are considered to be members ofthe dictionary itself.

dictionarySomeDictionary {  /* dictionary_members... */};partialdictionarySomeDictionary {  /* dictionary_members... */};

Note: As with partial interface definitions, partial dictionary definitions are intended for use as a specificationeditorial aide, allowing the definition of an interface to be separatedover more than one section of the document, and sometimes multiple documents.

The order of thedictionary members on a given dictionary is such that inherited dictionary members are orderedbefore non-inherited members, and the dictionary members on the onedictionary definition (including any partial dictionary definitions) areordered lexicographically by the Unicode codepoints that comprise theiridentifiers.

dictionaryB :A {longb;longa;};dictionaryA {longc;longg;};dictionaryC :B {longe;longf;};partialdictionaryA {longh;longd;};

[Exposed=Window]interfaceSomething {undefinedf(Aa);};

var something= getSomething();// Get an instance of Something.var x=0;var dict={};Object.defineProperty(dict,"d",{ get:function(){return++x;}});Object.defineProperty(dict,"c",{ get:function(){return++x;}});something.f(dict);

The identifier of a dictionary member must not bethe same as that of another dictionary member defined on the dictionary oron that dictionary’sinherited dictionaries.

Noextended attributes are applicable to dictionaries.

Partial ::partialPartialDefinition

PartialDefinition ::interfacePartialInterfaceOrPartialMixinPartialDictionaryNamespace

Dictionary ::dictionaryidentifierInheritance{DictionaryMembers};

DictionaryMembers ::DictionaryMemberDictionaryMembers    ε

DictionaryMember ::ExtendedAttributeListDictionaryMemberRest

DictionaryMemberRest ::requiredTypeWithExtendedAttributesidentifier;TypeidentifierDefault;

PartialDictionary ::dictionaryidentifier{DictionaryMembers};

Default ::=DefaultValue    ε

DefaultValue ::ConstValuestring[]{}nullundefined

Inheritance :::identifier    ε

[Exposed=Window]interfacePoint {constructor();attributedoublex;attributedoubley;};dictionaryPaintOptions {DOMStringfillPattern = "black";DOMStringstrokePattern;Pointposition;};[Exposed=Window]interfaceGraphicsContext {undefineddrawRectangle(doublewidth,doubleheight,optionalPaintOptionsoptions);};

// Get an instance of GraphicsContext.var ctx= getGraphicsContext();// Draw a rectangle.ctx.drawRectangle(300,200,{ fillPattern:"red", position:new Point(10,10)});

2.8.Exceptions

Anexception is a type of object that represents an error andwhich can be thrown or treated as a first class value by implementations. Web IDL has a number ofpre-defined exceptions that specifications can reference and throw in their definition ofoperations, attributes, and so on. Custom exception types can also be defined, asinterfaces thatinherit fromDOMException.

Asimple exception is identified by one of thefollowing types:

• EvalError

• RangeError

• ReferenceError

• TypeError

• URIError

These correspond to all of the JavaScripterror objects (apart fromSyntaxError andError, which are deliberatelyomitted as they are reserved for use by the JavaScript parser and by authors, respectively). Themeaning of eachsimple exception matches its corresponding error object in the JavaScriptspecification.

The second kind of exception is aDOMException, which provides furtherprogrammatically-introspectable detail on the error that occurred by giving aname.Suchnames are drawn from theDOMException names table below.

AsDOMException is aninterface type, it can be used as a type in IDL. Thisallows for example anoperation to be declared to have aDOMExceptionreturn type. Thisis generally a bad pattern, however, as exceptions are meant to be thrown and not returned.

The final kind of exception is a derived interface ofDOMException. These are more complicated,and thus described in the dedicated section§ 2.8.2 DOMException derived interfaces.

Simple exceptions can becreated by providing theirtype name. ADOMException can becreated by providing itsname followed byDOMException. Exceptions can also bethrown, by providing the same detailsrequired tocreate one. In both cases, the caller may provide additional informationabout what the exception indicates, which is useful when constructing the exception’s message.

The resulting behavior from creating and throwing an exception is language binding specific.

See§ 3.14.3 Creating and throwing exceptions for details on what creating and throwing anexception entails in the JavaScript language binding.

2.8.1.BaseDOMException error names

TheDOMException names table below lists all theallowednames for instances of the baseDOMException interface, along with adescription of what such names mean, and legacy numeric error code values.

Interfacesinheriting fromDOMException, in the manner describedin§ 2.8.2 DOMException derived interfaces, will have their own names, not listed in this table.

Whencreating orthrowing aDOMException, specifications must useone of these names. If a specification author believes none of these names are a good fit for theircase, they mustfile an issue to discuss adding a new name to the shared namespace, so that the community can coordinate suchefforts. Note that adding new use-case-specific names is only important if you believe webdevelopers will discriminate multiple error conditions arising from a single API.

TheDOMException names marked as deprecated are kept for legacy purposes, buttheir usage is discouraged.

Note: Don’t confuse the "SyntaxError"DOMException defined herewith JavaScript’sSyntaxError."SyntaxError"DOMException is used to report parsing errors in web APIs,for example when parsing selectors,while the JavaScriptSyntaxError is reserved for the JavaScript parser.To help disambiguate this further,always favor the "SyntaxError"DOMException notationover just usingSyntaxError to refer to theDOMException.[DOM]

2.8.2.DOMException derived interfaces

When an exception needs to carry additional programmatically-introspectable information, beyond whatcan be provided with aDOMException’sname, specification authors can create aninterface whichinherits fromDOMException. Such interfaces need to followcertain rules, in order to have a predictable shape for developers. Specifically:

• Theidentifier of theinterface must end withError, and must not be anyof the names in theDOMException names table.

• Theinterface must have aconstructor operation which sets the instance’sname to the interface’sidentifier.

• Theirconstructor operation must take as its first parameter anoptionalDOMString namedmessage defaulting to the empty string, and must set the instance’smessage tomessage.

• Theirconstructor operation should take as its second parameter adictionary containingthe additional information that needs to be exposed.

• They should haveread onlyattributes, whose names are the same as the members of theconstructor dictionary, which return the values accepted by the constructor operation.

• They should beserializable objects, whoseserialization steps anddeserialization steps preserve the additional information.

These requirements mean that the inheritedcode property of theseinterfaces will always return 0.

[Exposed=Window,Serializable]interfaceProtocolXError :DOMException {constructor(optionalDOMStringmessage = "",ProtocolXErrorOptionsoptions);readonlyattributeunsignedlonglongerrorCode;};dictionaryProtocolXErrorOptions {required [EnforceRange]unsignedlonglongerrorCode;};

Tocreate orthrow aDOMException derived interface, supply itsinterfaceidentifier as well as the additional information needed to construct it.

2.9.Enumerations

Anenumeration is a definition (matchingEnum) used to declare a typewhose valid values are a set of predefined strings. Enumerationscan be used to restrict the possibleDOMString values that can be assigned to anattribute or passed to anoperation.

enumidentifier {"enum","values" /* , ... */ };

Theenumeration values are specifiedas a comma-separated list ofstring literals.The list ofenumeration values must not include duplicates.

It is strongly suggested that enumeration values be all lowercase, and that multiple words be separated using dashes or not be separated at all, unless there is a specific reason to use another value naming scheme. For example, an enumeration value that indicates an object should be created could be named "createobject" or "create-object". Consider related uses of enumeration values when deciding whether to dash-separate or not separate enumeration value words so that similar APIs are consistent.

The behavior when a string value that is not a valid enumeration valueis used when assigning to anattribute,or passed as anoperation argument,whose type is the enumeration, is language binding specific.

Note: In the JavaScript binding, assignment of an invalid string value to anattribute is ignored, whilepassing such a value in other contexts (for example as anoperation argument)results in an exception being thrown.

Noextended attributes defined in this specification are applicable toenumerations.

Enum ::enumidentifier{EnumValueList};

EnumValueList ::stringEnumValueListComma

EnumValueListComma ::,EnumValueListString    ε

EnumValueListString ::stringEnumValueListComma    ε

enumMealType {"rice","noodles","other" };[Exposed=Window]interfaceMeal {attributeMealTypetype;attributedoublesize;     // in gramsundefinedinitialize(MealTypetype,doublesize);};

var meal= getMeal();// Get an instance of Meal.meal.initialize("rice",200);// Operation invoked as normal.try{  meal.initialize("sandwich",100);// Throws a TypeError.}catch(e){}meal.type="noodles";// Attribute assigned as normal.meal.type="dumplings";// Attribute assignment ignored.meal.type=="noodles";// Evaluates to true.

2.10.Callback functions

The “Custom DOM Elements” spec wants to use callback function types for platform object provided functions. Should we rename “callback functions” to just “functions” to make it clear that they can be used for both purposes?

Acallback function is a definition (matchingcallbackCallbackRest) used to declare a function type.

callbackidentifier =return_type (/* arguments... */);

Note: See also the similarly namedcallback interfaces.

Theidentifier on theleft of the equals sign gives the name of thecallback function and the return type and argument list (matchingType andArgumentList) on the right side of the equalssign gives the signature of the callback function type.

Callback functions must notbe used as the type of aconstant.

The following extended attribute is applicable to callback functions:[LegacyTreatNonObjectAsNull].

CallbackOrInterfaceOrMixin ::callbackCallbackRestOrInterfaceinterfaceInterfaceOrMixin

CallbackRest ::identifier=Type(ArgumentList);

callbackAsyncOperationCallback =undefined (DOMStringstatus);[Exposed=Window]interfaceAsyncOperations {undefinedperformOperation(AsyncOperationCallbackwhenFinished);};

var ops= getAsyncOperations();// Get an instance of AsyncOperations.ops.performOperation(function(status){  window.alert("Operation finished, status is "+ status+".");});

2.11.Typedefs

Atypedef is a definition (matchingTypedef)used to declare a new name for a type. This new name is not exposedby language bindings; it is purely used as a shorthand for referencingthe type in the IDL.

typedeftypeidentifier;

Thetype being given a new name is specified after thetypedef keyword (matchingTypeWithExtendedAttributes), and theidentifier token following thetype gives the name.

TheType must notbe the identifier of the same or anothertypedef.

Noextended attributes defined in this specification are applicable totypedefs.

Typedef ::typedefTypeWithExtendedAttributesidentifier;

[Exposed=Window]interfacePoint {attributedoublex;attributedoubley;};typedefsequence<Point>Points;[Exposed=Window]interfaceWidget {booleanpointWithinBounds(Pointp);booleanallPointsWithinBounds(Pointsps);};

2.12.Objects implementing interfaces

In a given implementation of a set ofIDL fragments,an object can be described as being aplatform object.

Platform objects are objectsthat implement aninterface.

Legacy platform objects areplatform objects that implement aninterface whichdoes not have a [Global]extended attribute, and whichsupports indexed properties,named properties, or both.

In a browser, for example,the browser-implemented DOM objects (implementing interfaces such asNode andDocument) that provide access to a web page’s contentsto JavaScript running in the page would beplatform objects. These objects might be exotic objects,implemented in a language like C++, or they might be native JavaScript objects. Regardless,an implementation of a given set of IDL fragments needs to be able to recognize allplatform objects that are created by the implementation. This might be done by having some internal state that records whethera given object is indeed a platform object for that implementation, or perhaps by observingthat the object is implemented by a given internal C++ class. How exactly platform objectsare recognized by a given implementation of a set of IDL fragments is implementation specific.

All other objects in the system would not be treated as platform objects. For example, assume thata web page opened in a browser loads a JavaScript library that implements DOM Core. This librarywould be considered to be a different implementation from the browser provided implementation.The objects created by the JavaScript library that implement theNode interfacewill not be treated as platform objects that implementNode by the browser implementation.

Callback interfaces, on the other hand, can be implemented by any JavaScript object. Thisallows Web APIs to invoke author-defined operations. For example, the DOM Events implementationallows authors to register callbacks by providing objects that implement theEventListener interface.

2.13.Types

This section lists the types supported by Web IDL,the set of values orInfra typecorresponding to each type, and howconstants of that type are represented.

The following types are known asinteger types:byte,octet,short,unsigned short,long,unsigned long,long long andunsigned long long.

The following types are known asnumeric types:theinteger types,float,unrestricted float,double andunrestricted double.

Theprimitive types arebigint,boolean and thenumeric types.

Thestring types areDOMString, allenumeration types,ByteString andUSVString.

Thebuffer types areArrayBuffer andSharedArrayBuffer.

Thetyped array types areInt8Array,Int16Array,Int32Array,Uint8Array,Uint16Array,Uint32Array,Uint8ClampedArray,BigInt64Array,BigUint64Array,Float16Array,Float32Array, andFloat64Array.

Thebuffer view types areDataView and thetyped array types.

Thebuffer source types are thebuffer types and thebuffer view types.

Theobject type,allinterface types, andallcallback interface types are known asobject types.

When conversions are made from language binding specific types to IDL types in order to invoke anoperation or assign a value to anattribute, all conversions necessary will be performed before the specified functionality of the operation or attribute assignment is carried out. If the conversion cannot be performed, then the operation will not run or the attribute will not be updated. In some language bindings, type conversions could result in an exception being thrown. In such cases, these exceptions will be propagated to the code that made the attempt to invoke the operation or assign to the attribute.

Type ::SingleTypeUnionTypeNull

TypeWithExtendedAttributes ::ExtendedAttributeListType

SingleType ::DistinguishableTypeanyPromiseType

UnionType ::(UnionMemberTypeorUnionMemberTypeUnionMemberTypes)

UnionMemberType ::ExtendedAttributeListDistinguishableTypeUnionTypeNull

UnionMemberTypes ::orUnionMemberTypeUnionMemberTypes    ε

DistinguishableType ::PrimitiveTypeNullStringTypeNullidentifierNullsequence<TypeWithExtendedAttributes>Nullasync iterable<TypeWithExtendedAttributes>NullobjectNullsymbolNullBufferRelatedTypeNullFrozenArray<TypeWithExtendedAttributes>NullObservableArray<TypeWithExtendedAttributes>NullRecordTypeNullundefinedNull

ConstType ::PrimitiveTypeidentifier

PrimitiveType ::UnsignedIntegerTypeUnrestrictedFloatTypebooleanbyteoctetbigint

UnrestrictedFloatType ::unrestrictedFloatTypeFloatType

FloatType ::floatdouble

UnsignedIntegerType ::unsignedIntegerTypeIntegerType

IntegerType ::shortlongOptionalLong

OptionalLong ::long    ε

StringType ::ByteStringDOMStringUSVString

PromiseType ::Promise<Type>

RecordType ::record<StringType,TypeWithExtendedAttributes>

Null ::?    ε

2.13.1.any

Theany type is the union of all other possiblenon-union types.

Theany type is likea discriminated union type, in that each of its values has aspecific non-any typeassociated with it. For example, one value of theany type is theunsigned long 150, while another is thelong 150.These are distinct values.

The particular type of anany value is known as itsspecific type.(Values ofunion types also havespecific types.)

2.13.2.undefined

Theundefined type has a unique value.

undefined constant values in IDLare represented with theundefined token.

undefined must not be used as the type of an argument in any circumstance(in anoperation,callback function,constructor operation, etc),or as the type of adictionary member,whether directly or in a union.Instead, use anoptional argument or a non-requireddictionary member.

Note: This value was previously spelledvoid,and more limited in how it was allowed to be used.

2.13.3.boolean

Theboolean type corresponds tobooleans.

boolean constant values in IDL arerepresented with thetrue andfalse tokens.

2.13.4.byte

Thebyte type corresponds to8-bit signed integers.

byte constant values in IDL arerepresented withinteger tokens.

2.13.5.octet

Theoctet type corresponds to8-bit unsigned integers.

octet constant values in IDL arerepresented withinteger tokens.

2.13.6.short

Theshort type corresponds to16-bit signed integers.

short constant values in IDL arerepresented withinteger tokens.

2.13.7.unsigned short

Theunsigned short type corresponds to16-bit unsigned integers.

unsigned short constant values in IDL arerepresented withinteger tokens.