1.Introduction

This section is informative.

Technical reports published by the W3C that include programminglanguage interfaces have typically been described using theObject Management Group’s Interface Definition Language (IDL)[OMGIDL]. The IDL provides a means todescribe these interfaces in a language independent manner. Usually,additional language binding appendices are included in suchdocuments which detail how the interfaces described with the IDLcorrespond to constructs in the given language.

However, the bindings in these specifications for the language mostcommonly used on the web, ECMAScript, are consistently specified withlow enough precision as to result in interoperability issues. Inaddition, each specification must describe the same basic information,such as DOM interfaces described in IDL corresponding to propertieson the ECMAScript global object, or theunsigned long IDL type mapping to the Numbertype in ECMAScript.

This specification defines an IDL language similar to OMG IDLfor use by specifications that define interfaces for Web APIs. A number of extensions aregiven to the IDL to support common functionality that previously musthave been written in prose. In addition, precise language bindingsfor the ECMAScript language are given.

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 ECMAScript language binding are discussedin§ 3.3 ECMAScript-specific 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;voiddrawRectangle(doublex,doubley,doublewidth,doubleheight);voiddrawText(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 LOW LINE ("_") character (underscore) removed.

Note: A leading"_" is used to escape an identifier from lookinglike a reserved word so that, for example, an interface named "interface" can bedefined. The leading"_" 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 LOW LINE ("_") character (underscore) 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 aU+005F LOW LINE ("_") character. 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 may 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 {voidf(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 COLON (":") characterand 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 theECMAScript 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 {voidf();voidg();};[Exposed=Window]interfaceB :A {voidf();voidg(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 must 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:[Exposed],[Global],[LegacyWindowAlias],[NamedConstructor],[NoInterfaceObject],[OverrideBuiltins], and[SecureContext].

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

Interfaces which are not annotatedwith a [NoInterfaceObject]extended attribute 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 ::ConstOperationStringifierStaticMemberIterableAsyncIterableReadOnlyMemberReadWriteAttributeReadWriteMaplikeReadWriteSetlike

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);voidaddEventListener(DOMStringtype,EventListenerlistener);};callbackinterfaceEventListener {voidhandleEvent(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 except forstringifiers, 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 theECMAScript binding.

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

Of the extended attributes defined in this specification,only the [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_indentifier;

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 ECMAScript, 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 {voidaddEventListener(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 ::ConstRegularOperationStringifierReadOnlyAttributeRest

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 matchingcallbackinterfaceInterfaceRest.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.

The algorithm steps for everyregular operation,regular attribute getter, andregular attribute setter’s 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.

Attribute setter’s algorithm 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 ECMAScript 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 is 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:[Exposed],[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,staticReadOnlyAttributeRest,stringifierReadOnlyAttributeRest,ReadOnlyAttributeRest,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.

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

• 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 [LenientSetter], [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.1 Stringifiers for details.

interfaceinterface_identifier {stringifierattributeDOMStringidentifier;};

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

The followingextended attributes are applicable only to regular attributes:[LenientSetter],[LenientThis],[PutForwards],[Replaceable],[Unforgeable].

ReadOnlyMember ::readonlyReadOnlyMemberRest

ReadOnlyMemberRest ::AttributeRestMaplikeRestSetlikeRest

ReadWriteAttribute ::inheritAttributeRestAttributeRest

AttributeRest ::attributeTypeWithExtendedAttributesAttributeName;

AttributeName ::AttributeNameKeywordidentifier

AttributeNameKeyword ::asyncrequired

ReadOnly ::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 interfacemember ornamespace member (matchingstaticRegularOperation,stringifierRegularOperation,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.5 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.

Theidentifier of astatic operation also must not be the same as the identifierof aregular operation defined on the sameinterface.

Thereturn type of the operation is givenby the type (matchingReturnType)that appears before the operation’s optionalidentifier.A return type ofvoid indicates that the operation returns no value.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.voidsetDimensions(Dimensionssize);voidsetDimensions(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 ([NamedConstructor], 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;voidunion(long...ints);voidintersection(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 aU+003D EQUALS SIGN ("=") 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).

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 norequired members, 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.

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 auniontype 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:[Default],[Exposed],[NewObject],[SecureContext],[Unforgeable].

DefaultValue ::ConstValuestring[]{}null

Operation ::RegularOperationSpecialOperation

RegularOperation ::ReturnTypeOperationRest

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

ReturnType ::Typevoid

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 ECMAScript language binding,this is done by exposing atoJSON methodwhich returns theJSON type converted into an ECMAScript valuethat can be turned into a JSON stringby theJSON.stringify() function.Additionally, in the ECMAScript language binding,thetoJSON operation can take a [Default]extended attribute,in which case thedefault toJSON operation is 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.

The prose definition of aconstructor operation must either initialize the value passed asthis, or throw an exception.

See§ 3.6.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();// The 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.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 four 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);settervoid (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 tosimplify prose descriptions of an interface’s operations.

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

[Exposed=Window]interfaceDictionary {readonlyattributeunsignedlongpropertyCount;doublegetProperty(DOMStringpropertyName);voidsetProperty(DOMStringpropertyName,doublepropertyValue);getterdouble (DOMStringpropertyName);settervoid (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.5.2 Indexed properties and§ 2.5.5.3 Named properties for details.

On a giveninterface,there must exist at most onestringifier, 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.5.1.Stringifiers

When aninterface has astringifier, it indicates that objects that implementthe interface have a non-default conversion to a string. As mentioned above,stringifiers can be specified using anoperation declared with thestringifier keyword.

interfaceinterface_identifier {stringifierDOMStringidentifier();stringifierDOMString ();};

If an operation used to declare a stringifier does not have anidentifier, then proseaccompanying the interface must definethestringification behavior of the interface. If the operation does have an identifier,then the object is converted to a string by invoking theoperation to obtain the string.

Stringifiers declared with operations mustbe declared to take zero arguments and return aDOMString.

As a shorthand, if thestringifier keywordis declared using an operation with no identifier, then theoperation’sreturn type andargument list can be omitted.

interfaceinterface_identifier {stringifier;};

[Exposed=Window]interfaceA {stringifierDOMString ();};

[Exposed=Window]interfaceA {stringifier;};

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;};

Stringifier ::stringifierStringifierRest

StringifierRest ::ReadOnlyAttributeRestRegularOperation;

[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;stringifierDOMString ();};

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

2.5.5.2.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);settervoidsetByIndex(unsignedlongindex,anyvalue);getteranyget(DOMStringname);settervoidset(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.5.3.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.6.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 ::ReadOnlyAttributeRestRegularOperation

[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.7.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.

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

[Exposed=Window]interfaceA {voidf();};partialinterfaceA {voidf(doublex);voidg();};partialinterfaceA {voidg(DOMStringx);};

Aneffective overload set represents the allowable invocations for a particularoperation,constructor (specified with aconstructor operation or [NamedConstructor]), 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 named constructors

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

• theidentifier of the named constructors

• 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 fornamed constructors.

• 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 */voidf(DOMStringa);  /* f2 */voidf(Nodea,DOMStringb,double...c);  /* f3 */voidf();  /* f4 */voidf(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

   	boolean	numeric types	string types	object	symbol	interface-like	callback function	dictionary-like	sequence-like
   boolean		●	●	●	●	●	●	●	●
   numeric types			●	●	●	●	●	●	●
   string types				●	●	●	●	●	●
   object					●
   symbol						●	●	●	●
   interface-like						(a)	●	●	●
   callback function									●
   dictionary-like									●
   sequence-like

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

   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 {voidhandle();};[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.

[Exposed=Window]interfaceB {voidf(DOMStringx);voidf(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 */voidf(DOMStringw);  /* f2 */voidf(longw,doublex,Nodey,Nodez);  /* f3 */voidf(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.7.1.Overloading vs. union types

This section is informative.

interfaceCanvasDrawPathExcerpt {voidstroke();voidstroke(Path2Dpath);};

interfaceCanvasDrawPathExcerptOptional {voidstroke(optionalPath2Dpath);};

2.5.8.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 ECMAScript language binding, an interface that is iterablewill haveentries,forEach,keys,values, and@@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@@iterator areactualarray iterator objects.

Interfaces with iterable declarations must nothave anyinterface members named "entries", "forEach","keys", or "values",or have anyinherited interfaces that havemembers 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 objecttypeof 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:[Exposed],[SecureContext].

Iterable ::iterable<TypeWithExtendedAttributesOptionalType>;

OptionalType ::,TypeWithExtendedAttributes    ε

2.5.9.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<key_type,value_type>;};

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

Note: In the ECMAScript language binding, an interface that is asynchronously iterable will haveentries,keys,values,and@@asyncIterator properties on itsinterface prototype object.

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 undefined to signal the end of theiteration, or resolves with a tuple containing two elements:

1. a value of the first type given in the declaration;

2. 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 ECMAScript 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, as well as the newly-createditerator object.

Interfaces with anasynchronously iterable declaration must not have anyinterface members named "entries", "keys", or "values",or have anyinherited interfaces that haveinterface members 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".for await(let usernameof sm.keys()){  console.log(username);}// Yet another way of accomplishing the same.for await(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:[Exposed],[SecureContext].

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

AsyncIterable ::asynciterable<TypeWithExtendedAttributes,TypeWithExtendedAttributes>;

2.5.10.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 an ordered list of key–value pairs known as itsmap entries.The types used for the keys and values are given in the anglebrackets of the maplike declaration. Keys are required to be unique.

Themap entries of an objectimplementing amaplike interface is empty atthe of the object’s creation. Prose accompanying the interface candescribe how themap entries of an object change.

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 ECMAScript language binding, the API for interactingwith the map entries is similar to that available on ECMAScriptMap objects. If thereadonly keyword is used, this includesentries,forEach,get,has,keys,values,@@iterator methods, and asize getter.For read–write maplikes, it also includesclear,delete, andset methods.

Maplike interfaces must nothave anyinterface members named "entries", "forEach","get", "has","keys", "size", or"values",or have anyinherited interfaces that havemembers with these 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: Operations named "clear", "delete",or "set" are allowed on read–write maplikeinterfaces and will prevent the default implementation of these methods beingadded to the interface prototype object in the ECMAScript language binding.This allows the default behavior of these operations to be overridden.

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.11.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 an ordered list of values known as itsset entries.The type of the values is given in the anglebrackets of the setlike declaration. Values are required to be unique.

Theset entries of an objectimplementing asetlike interface is empty atthe of the object’s creation. Prose accompanying the interface candescribe how theset entries of an object change.

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 ECMAScript language binding, the API for interactingwith the set entries is similar to that available on ECMAScriptSet objects. If thereadonly keyword is used, this includesentries,forEach,has,keys,values,@@iterator methods, and asize getter.For read–write setlikes, it also includesadd,clear, anddelete methods.

Setlike interfaces must nothave anyinterface members named "entries", "forEach","has", "keys","size", or "values",or have anyinherited interfaces that havemembers 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: Operations named "add", "clear",or "delete" are allowed on read–write setlikeinterfaces and will prevent the default implementation of these methods beingadded to the interface prototype object in the ECMAScript language binding.This allows the default behavior of these operations to be overridden.

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 andread onlyregular attributes that appear between the braces inthe namespace declaration. These operations and attributes describe the behaviors packaged into thenamespace.

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 theECMAScript binding.

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

Of the extended attributes defined in this specification, only the [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 ::RegularOperationreadonlyAttributeRest

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... */};

Dictionaries are always passed by value. In language bindings where a dictionary is represented by an object of some kind, passing adictionary to aplatform object will not result in a reference to the dictionary being kept by that object.Similarly, any dictionary returned from a platform object will be a copy and modifications made to it will not be visible to the platform object.

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.

A dictionary value of typeD can have key–value pairs correspondingto the dictionary members defined onD and on any ofD’sinherited dictionaries.On a given dictionary value, the presence of each dictionary memberis optional, unless that member is specified as required.A dictionary member is said to bepresent in a dictionary value if the valuecontains an entry with the key given by the member’sidentifier, otherwise it isnot present.Dictionary members can also optionally have adefault value, which isthe value to use for the dictionary member when passing a value to aplatform object that doesnot have a specified value. Dictionary members with default values arealways considered to be present.

In the ECMAScript binding, a value ofundefined is treated asnot present, or will trigger thedefault value where applicable.

Anordered map with stringkeys can be implicitly treated as a dictionary value of aspecific dictionaryD if all of itsentries correspond todictionary members, in thecorrect order and with the correct types, and with appropriateentries for any requireddictionary members.

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

As withoperation argument default values, it is strongly suggested 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).

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 is followed by aU+003D EQUALS SIGN ("=") and a value (matchingDefaultValue),then that gives the dictionary member itsdefault value.

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 arequired dictionary member and must be present on the dictionary.

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 {voidf(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.

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

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[]{}null

Inheritance :::identifier    ε

[Exposed=Window]interfacePoint {constructor();attributedoublex;attributedoubley;};dictionaryPaintOptions {DOMString?fillPattern = "black";DOMString?strokePattern =null;Pointposition;};[Exposed=Window]interfaceGraphicsContext {voiddrawRectangle(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 thatrepresents an error and which can be thrown or treated as a firstclass value by implementations. Web IDL does not allow exceptionsto be defined, but instead has a number of pre-defined exceptionsthat specifications can reference and throw in their definition ofoperations, attributes, and so on. Exceptions have anerror name,aDOMString,which is the type of error the exception represents, and amessage, which is an optional,user agent-defined value that provides human readable details of the error.

There are two kinds of exceptions available to be thrown from specifications.The first is asimple exception, whichis identified by one of the following types:

• EvalError

• RangeError

• ReferenceError

• TypeError

• URIError

These correspond to all of the ECMAScripterror objects (apart fromSyntaxError andError,which are deliberately omitted as they are reserved for useby the ECMAScript parser and by authors, respectively).The meaning of eachsimple exception matchesits corresponding error object in theECMAScript specification.

The second kind of exception is aDOMException,which is an exception that encapsulates a name and an optional integer code,for compatibility with historically defined exceptions in the DOM.

Forsimple exceptions, theerror name is the type of the exception.For aDOMException, theerror name must be one of the nameslisted in theerror names table below.The table also indicates theDOMException's integer code for that error name,if it has one.

Note: AsDOMException is aninterface type, it can be used as a type in IDL.This allows for example anoperation to be declared to have aDOMExceptionreturn type.

Simple exceptions can becreated by providing theirerror name.ADOMException can becreated by providing itserror name followed byDOMException.Exceptions can also bethrown, by providing thesame details required tocreate one.

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

Note: See§ 3.12.3 Creating and throwing exceptions for details on what creating and throwing an exceptionentails in the ECMAScript language binding.

2.8.1.Error names

Theerror names table below lists all the allowed error namesforDOMException, a description, and legacy code values.

TheDOMException names marked as deprecated are kept for legacy purposes but their usage is discouraged.

Note: If an error name is not listed here, please file a bug as indicated at the top of this specification and it will be addressed shortly. Thanks!

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

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 one 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 ECMAScript 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 gramsvoidinitialize(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 (matchingReturnType 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:[TreatNonObjectAsNull].

CallbackOrInterfaceOrMixin ::callbackCallbackRestOrInterfaceinterfaceInterfaceOrMixin

CallbackRest ::identifier=ReturnType(ArgumentList);

callbackAsyncOperationCallback =void (DOMStringstatus);[Exposed=Window]interfaceAsyncOperations {voidperformOperation(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 ECMAScript running in the page would beplatform objects. These objects might be exotic objects,implemented in a language like C++, or they might be native ECMAScript 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 an ECMAScript library that implements DOM Core. This librarywould be considered to be a different implementation from the browser provided implementation.The objects created by the ECMAScript 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 ECMAScript 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 valuescorresponding 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 areboolean and thenumeric types.

Thestring types areDOMString, allenumeration types,ByteString andUSVString.

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

Thebuffer source types areArrayBuffer,DataView,and thetyped array types.

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

Every type has atype name, whichis a string, not necessarily unique, that identifies the type.Each sub-section below defines what the type name is for eachtype.

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>NullobjectNullsymbolNullBufferRelatedTypeNullFrozenArray<TypeWithExtendedAttributes>NullRecordTypeNull

ConstType ::PrimitiveTypeidentifier

PrimitiveType ::UnsignedIntegerTypeUnrestrictedFloatTypebooleanbyteoctet

UnrestrictedFloatType ::unrestrictedFloatTypeFloatType

FloatType ::floatdouble

UnsignedIntegerType ::unsignedIntegerTypeIntegerType

IntegerType ::shortlongOptionalLong

OptionalLong ::long    ε

StringType ::ByteStringDOMStringUSVString

PromiseType ::Promise<ReturnType>

RecordType ::record<StringType,TypeWithExtendedAttributes>

Null ::?    ε

2.13.1.any

Theany type is the union of all other possiblenon-union types.Itstype name is "Any".

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.void

Thevoid type has a unique value.

It can only be used as thereturn type of anoperation or the parameter of apromise type.

Thetype name of thevoid type is "Void".

2.13.3.boolean

Theboolean type has two values:true andfalse.

boolean constant values in IDL arerepresented with thetrue andfalse tokens.

Thetype name of theboolean type is "Boolean".

2.13.4.byte

Thebyte type is a signed integertype that has values in the range [−128, 127].

byte constant values in IDL arerepresented withinteger tokens.

Thetype name of thebyte type is "Byte".

2.13.5.octet

Theoctet type is an unsigned integertype that has values in the range [0, 255].

octet constant values in IDL arerepresented withinteger tokens.

Thetype name of theoctet type is "Octet".

2.13.6.short

Theshort type is a signed integertype that has values in the range [−32768, 32767].

short constant values in IDL arerepresented withinteger tokens.

Thetype name of theshort type is "Short".

2.13.7.unsigned short

Theunsigned short type is an unsigned integertype that has values in the range [0, 65535].

unsigned short constant values in IDL arerepresented withinteger tokens.

Thetype name of theunsigned short type is "UnsignedShort".

2.13.8.long

Thelong type is a signed integertype that has values in the range [−2147483648, 2147483647].

long constant values in IDL arerepresented withinteger tokens.

Thetype name of thelong type is "Long".

2.13.9.unsigned long

Theunsigned long type is an unsigned integertype that has values in the range [0, 4294967295].

unsigned long constant values in IDL arerepresented withinteger tokens.

Thetype name of theunsigned long type is "UnsignedLong".

2.13.10.long long

Thelong long type is a signed integertype that has values in the range [−9223372036854775808, 9223372036854775807].

long long constant values in IDL arerepresented withinteger tokens.

Thetype name of thelong long type is "LongLong".

2.13.11.unsigned long long

Theunsigned long long type is an unsigned integertype that has values in the range [0, 18446744073709551615].

unsigned long long constant values in IDL arerepresented withinteger tokens.

Thetype name of theunsigned long long type is "UnsignedLongLong".

2.13.12.float

Thefloat type is a floating point numerictype that corresponds to the set of finite single-precision 32 bitIEEE 754 floating point numbers.[IEEE-754]

float constant values in IDL arerepresented withdecimal tokens.

Thetype name of thefloat type is "Float".

Unless there are specific reasons to use a 32 bit floating point type, specifications should usedouble rather thanfloat, since the set of values that adouble can represent more closely matches an ECMAScript Number.

2.13.13.unrestricted float

Theunrestricted float type is a floating point numerictype that corresponds to the set of all possible single-precision 32 bitIEEE 754 floating point numbers, finite, non-finite, and special "not a number" values (NaNs).[IEEE-754]

unrestricted float constant values in IDL arerepresented withdecimal tokens.

Thetype name of theunrestricted float type is "UnrestrictedFloat".

2.13.14.double

Thedouble type is a floating point numerictype that corresponds to the set of finite double-precision 64 bitIEEE 754 floating point numbers.[IEEE-754]

double constant values in IDL arerepresented withdecimal tokens.

Thetype name of thedouble type is "Double".

2.13.15.unrestricted double

Theunrestricted double type is a floating point numerictype that corresponds to the set of all possible double-precision 64 bitIEEE 754 floating point numbers, finite, non-finite, and special "not a number" values (NaNs).[IEEE-754]

unrestricted double constant values in IDL arerepresented withdecimal tokens.

Thetype name of theunrestricted double type is "UnrestrictedDouble".

2.13.16.DOMString

TheDOMString type corresponds tothe set of all possible sequences ofcode units.Such sequences are commonly interpreted as UTF-16 encoded strings[RFC2781] although this is not required.WhileDOMString is defined to bean OMG IDL boxedsequence<unsigned short> valuetypeinDOM Level 3 Core §The DOMString Type,this document definesDOMString to be an intrinsic typeso as to avoid special casing that sequence typein various situations where a string is required.

Note: Note also thatnull is not a value of typeDOMString.To allownull, anullableDOMString,written asDOMString? in IDL, needs to be used.

Nothing in this specification requires aDOMString value to be a valid UTF-16 string. For example, aDOMString value might include unmatched surrogate pair characters. However, authorsof specifications using Web IDL might want to obtain a sequence ofUnicode scalar values given a particular sequence ofcode units.

There is no way to represent a constantDOMString value in IDL, althoughDOMStringdictionary memberdefault values andoperation optional argumentdefault values can be set tothe value of astring literal.

Thetype name of theDOMString type is "String".

2.13.17.ByteString

TheByteString typecorresponds to the set of all possible sequences of bytes.Such sequences might be interpreted as UTF-8 encoded strings[RFC3629] or strings in some other 8-bit-per-code-unit encoding, although this is not required.

There is no way to represent a constantByteString value in IDL, althoughByteStringdictionary memberdefault values andoperation optional argumentdefault values can be set tothe value of astring literal.

Thetype name of theByteString type is "ByteString".

Specifications should only useByteString for interfacing with protocols that use bytes and strings interchangeably, such as HTTP. In general, strings should be represented withDOMString values, even if it is expected that values of the string will always be in ASCII or some 8 bit character encoding.Sequences orfrozen arrays withoctet orbyte elements,Uint8Array, orInt8Array should be used for holding 8 bit data rather thanByteString.

2.13.18.USVString

TheUSVString typecorresponds to the set of all possible sequences ofUnicode scalar values,which are all of the Unicode code points apart from thesurrogate code points.

There is no way to represent a constantUSVString value in IDL, althoughUSVStringdictionary memberdefault values andoperation optional argumentdefault values can be set tothe value of astring literal.

Thetype name of theUSVString type is "USVString".

Specifications should only useUSVString for APIs that perform text processing and need a string of Unicode scalar values to operate on. Most APIs that use strings should instead be usingDOMString, which does not make any interpretations of thecode units in the string. When in doubt, useDOMString.

2.13.19.object

Theobject type corresponds to the set ofall possible non-null object references.

There is no way to represent a constantobject value in IDL.

To denote a type that includes all possible object references plus thenull value, use thenullable typeobject?.

Thetype name of theobject type is "Object".

2.13.20.symbol

Thesymbol type corresponds to the set of all possible symbol values. Symbol values are opaque,non-object values which nevertheless have identity (i.e., are only equal to themselves).

There is no way to represent a constantsymbol value in IDL.

Thetype name of thesymbol type is "Symbol".

2.13.21.Interface types

Anidentifier thatidentifies aninterface is used to refer toa type that corresponds to the set of all possible non-null references to objects thatimplement that interface.

An IDL value of the interface type is represented justby an object reference.

There is no way to represent a constant object reference value fora particular interface type in IDL.

To denote a type that includes all possible references to objects implementingthe given interface plus thenull value,use anullable type.

Thetype name of an interface typeis theidentifier of the interface.

2.13.22.Callback interface types