This specification provides a way to point into a Web IDL schema and to decorate it by applying extended attributes to them.

This document describes a completely experimental avenue of thinking and may have no future.

Introduction

Web IDL [[!WEBIDL]] is a schema language used for the description of APIs. A feature of the language, called "Extended Attributes", allows annotations to be applied to schema constructs in order to refine the way in which they apply within a specific context. Since Web IDL schemata are intended to be reused by possibly large and varied communities, it can be impractical to place all Extended Attributes onto the same definition. This specification provides a way to decorate a Web IDL schema by pointing to its independent components and applying extended attributes to them.

Definitions

extended attribute
An information item corresponding to the ExtendedAttribute construct in Web IDL.

Information Set of Web IDL Schemata

We define an abstract information set for Web IDL Schemata that does not intend to capture the full breadth of information that may be in a schema but rather the minimal set that is needed to support the purpose of this specification. It can be extended later.

root

The root is a specific module that has no name. It is the outermost scope in the tree and contains all other information items directly or indirectly. Its properties are the same as those of module information items, except that it has no name.

module

A module is a container used to structure namespaces in a Web IDL schema.

name
A string identifying the module inside its parent module.
extended attributes
An ordered list of zero or more extended attributes.
modules
An unordered list of zero or more modules directly contained inside this module.
interfaces
An unordered list of zero or more interfaces directly contained inside this module.
exceptions
An unordered list of zero or more exceptions directly contained inside this module.
typedefs
An unordered list of zero or more typedefs directly contained inside this module.
implements
An unordered list of zero or more implements statements directly contained inside this module.

interface

An interface is a container for a coherent unit of data and behaviour.

name
A string identifying the interface inside its parent module.
extended attributes
An ordered list of zero or more extended attributes.
constants
An unordered list of zero or more constants directly contained inside this interface.
attributes
An unordered list of zero or more attributes directly contained inside this interface.
operations
An unordered list of zero or more operations directly contained inside this interface.

exception

An exception is a container for data used to describe exceptional situations.

name
A string identifying the exception inside its parent module.
extended attributes
An ordered list of zero or more extended attributes.
constants
An unordered list of zero or more constants directly contained inside this exception.
fields
An unordered list of zero or more fields directly contained inside this exception.

typedef

A typedef describes the binding of a name to a type.

name
A string identifying the name that is bound inside this scope.
extended attributes
An ordered list of zero or more extended attributes.

implements statement

An implements statement is an indication that a given target interface implements another source interface.

target
The identifier of the interface that implements the source interface.
source
The identifier of the interface that is implemented by the target interface.
extended attributes
An ordered list of zero or more extended attributes.

constant

A constant is an unchanging data item.

name
A string identifying the constant inside its parent.
extended attributes
An ordered list of zero or more extended attributes.

attribute

An attribute is a data item inside an interface.

name
A string identifying the attribute inside its parent interface.
extended attributes
An ordered list of zero or more extended attributes.

operation

An operation is a unit of behaviour inside an interface.

name
A string participating in the identification of the operation inside its parent interface.
extended attributes
An ordered list of zero or more extended attributes.
arguments
An ordered list of zero or more arguments. Collectively the list defines a sufficient signature to identify an operation when combined with its name.

argument

A argument is a unit of data provided to an operation.

name
A string identifying the argument.
type name
A string identifying the type of the argument.
extended attributes
An ordered list of zero or more extended attributes.

field

A field is a data item inside an exception.

name
A string identifying the field inside its parent exception.
extended attributes
An ordered list of zero or more extended attributes.

Component Designators

A component designator is a structured string that navigates inside a Web IDL schema. It is guaranteed to return either exactly one information item, or nothing. Some examples: 

        /module:crypto/module:alpine/interface:Dahut/attribute:chirality
        /interface:Unicorn/operation:neigh(DOMString,float)
        /module:nitro/exception:Boom/constant:sound
        /interface:Node
        /interface:Examples/operation:build(Unicorn,Dahut)/argument:dahut

Syntax

The formalism used here is created completely out of thin air, hopefully it is intuitively understandable. There is no white space in a designator. The $variable tokens map to the information set properties, which are in turn based on the Web IDL syntax. 

Designator      = ModuleStep* (InterfaceStep | ExceptionStep | TypeDefStep | ImplementsStep)*
ModuleStep      = "/module:" $module-name
InterfaceStep   = "/interface:" $interface-name (ConstantStep | AttributeStep | OperationStep)?
ExceptionStep   = "/exception:" $exception-name (ConstantStep | FieldStep)?
TypeDefStep     = "/typedef:" $typedef-name
ImplementsStep  = "/implements:" $target "(" $source ")"
ConstantStep    = "/constant:" $constant-name
AttributeStep   = "/attribute:" $attribute-name
OperationStep   = "/operation:" $operation-name "(" Arguments ")" ArgumentStep?
FieldStep       = "/field:" $field-name
Arguments       = $type-name ("," $type-name)* | ""
ArgumentStep    = "/argument:" $argument-name

Resolution

Given a designator parsed into a set of steps and a Web IDL schema, the designator is processed as follows in order to return either an information item, or nothing.

  1. Set context to the root information item
  2. If there are no more steps: if the context is root, return nothing, otherwise return the context.
  3. If the next step is a module step and there is a module contained in the current context with that exact module name, set context to that module and go to 2; otherwise return nothing.
  4. If the next step is an interface step and there is an interface contained in the current context with that exact interface name, set context to that interface and go to 2; otherwise return nothing.
  5. If the next step is an exception step and there is an exception contained in the current context with that exact exception name, set context to that exception and go to 2; otherwise return nothing.
  6. If the next step is a typedef step and there is a typedef contained in the current context with that exact typedef name, return it; otherwise return nothing.
  7. If the next step is an implements step and there is an implements statement contained in the current context with those exact target and source, return it; otherwise return nothing.
  8. If the next step is a constant step and there is a constant contained in the current context with that exact name, return it; otherwise return nothing.
  9. If the next step is an attribute step and there is an attribute contained in the current context with that exact name, return it; otherwise return nothing.
  10. If the next step is a field step and there is a field contained in the current context with that exact name, return it; otherwise return nothing.
  11. If the next step is an operation step and there is an operation contained in the current context with those exact name and list of argument types in the same order, set context to that operation and go to 2; otherwise return nothing.
  12. If the next step is a argument step and there is a argument contained in the current context with that exact name, return it; otherwise return nothing.

Actions

An action is a an operation that applies a modification to a Web IDL schema in order to produce a new one. Actions are grouped inside an action sheet, which is an ordered list of actions to be performed one after the other, alongside a touch of metadata. 

        {
          "name": "Coolness Action Sheet",
          "description":  "Attributes coolness to various parts of a Web IDL schema",
          "actions": [
            { "action": "addExtAttr", "path": "/module:Cryptoids/interface:Unicorn", "value": "[Coolness=prettyGood]" },
            { "action": "addExtAttr", "path": "/module:Mammals/interface:Dahut", "value": "[Coolness=hyper]" },
            { "action": "addExtAttr", "path": "/module:Memetics/exception:Dahunicorn", "value": "[Coolness=storeMeatInIt]" },
          ]
        }

The only action defined in this specification is the addExtAttr action.

Structure

An action sheet is a JSON document [[!RFC4627]] with the following properties.

name
The human-readable name of the action sheet.
description
The human-readable description of the action sheet.
actions
An array of actions. If this property is not present, or if it does not contain an array, then implementations MUST ignore it.

Every action is an object that has an action property which identifies the type of the action. If the action property is absent, or does not contain a string, then implementations MUST ignore that action. Other fields of the action depend on the action type.

Implementations MUST ignore other properties of action sheets.

Execution

The execution model for action sheets is simple: for each action in the action sheet in order the implementation MUST execute the action completely and move on to the next action. When all actions have been executed, the process comes to an end. The execution model for individual actions depends on the action type.

The addExtAttr action

The addExtAttr action is used to add extended attributes to information items that can receive them. It makes use of the following two properties:

path
A component designator used to address the item in the schema to which the action applies. If the path is not a valid component designator, then implementations MUST ignore this action.
value
A string in the ExtendedAttributeList syntax containing one or more extended attributes to be added to the designated component. If the value does not match the syntax, then implementations MUST ignore this action. Implementations MUST append the extended attributes in the value to those that may already be present on the designated component.

An addExtAttr action is executed in the following manner: the path is resolved against the Web IDL schema. If it returns nothing, execution stops. If the returned component supports an extended attributes property, the one(s) contained in the action value are added at the end of the extended attributes list.

Acknowledgements

This specification has no relationship whatsoever to W3C XML Schema Definition Language (XSD): Component Designators.