1. Principles behind design of Web APIs
The Design Principles are directly informed by the ethical framework set out in the Ethical Web Principles [ETHICAL-WEB]. These principles provide concrete practical advice in response to the higher level ethical responsibilities that come with developing the web platform.
1.1. Put user needs first (Priority of Constituencies)
If a trade-off needs to be made, always put user needs above all.
Similarly, when beginning to design an API, be sure to understand and document the user need that the API aims to address.
The internet is for end users: any change made to the web platform has the potential to affect vast numbers of people, and may have a profound impact on any person’s life. [RFC8890]
User needs come before the needs of web page authors, which come before the needs of user agent implementors, which come before the needs of specification writers, which come before theoretical purity.
Like all principles, this isn’t absolute. Ease of authoring affects how content reaches users. User agents have to prioritize finite engineering resources, which affects how features reach authors. Specification writers also have finite resources, and theoretical concerns reflect underlying needs of all of these groups.
See also:
1.2. It should be safe to visit a web page
When adding new features, design them to preserve the user expectation that visiting a web page is generally safe.
The Web is named for its hyperlinked structure. In order for the web to remain vibrant, users need to be able to expect that merely visiting any given link won’t have implications for the security of their computer, or for any essential aspects of their privacy.
For example, an API that allows any website to detect the use of assistive technologies may make users of these technologies feel unsafe visiting unknown web pages, since any web page may detect this private information.
If users have a realistic expectation of safety, they can make informed decisions between Web-based technologies and other technologies. For example, users may choose to use a web-based food ordering page, rather than installing an app, since installing a native app is riskier than visiting a web page.
To work towards making sure the reality of safety on the web matches users' expectations, we can take complementary approaches when adding new features:
-
We can improve the user interfaces through which the Web is used to make it clearer what users of the Web should (and should not) expect;
-
We can change the technical foundations of the Web so that they match user expectations of privacy;
-
We can consider the cases where users would be better off if expectations were higher, and in those cases try to change both technical foundations and expectations.
A new feature which introduces safety risks may still improve user safety overall, if it allows users to perform a task more safely on a web page than it would be for them to install a native app to do the same thing. However, this benefit needs to be weighed against the common goal of users having a reasonable expectation of safety on web pages.
See also:
1.3. Trusted user interface should be trustworthy
Consider whether new features impact trusted user interfaces.
Users depend on trusted user interfaces such as the address bar, security indicators and permission prompts, to understand who they are interacting with and how. These trusted user interfaces must be able to be designed in a way that enables users to trust and verify that the information they provide is genuine, and hasn’t been spoofed or hijacked by the website.
If a new feature allows untrusted user interfaces to resemble trusted user interfaces, this makes it more difficult for users to understand what information is trustworthy.
For example, JavaScript alert() allows a page to show a modal dialog which looks like part of the browser.
This is often used to attempt to trick users into visiting scam websites.
If this feature was proposed today, it would probably not proceed.
1.4. Ask users for meaningful consent
In the context of fulfilling a user need, a web page may want to make use of a feature that has the potential to cause harm. Features that have this potential for harm should be designed such that people can give meaningful consent for that feature to be used, and that they can refuse consent effectively.
In order to give meaningful consent, the user must:
-
understand what permission they may choose whether to grant the web page
-
be able to choose to give or refuse that permission effectively.
If a feature is powerful enough to require user consent, but it’s impossible to explain to a typical user what they are consenting to, that’s a signal that you may need to reconsider the design of the feature.
If a permission prompt is shown, and the user doesn’t grant permission, the Web page should not be able to do anything that the user believes they have refused consent for.
By asking for consent, we can inform the user of what capabilities the web page does or doesn’t have, reinforcing their confidence that the web is safe. However, the user benefit of a new feature must justify the additional burden on users to decide whether to grant permission for each feature whenever it’s requested by a Web page.
In your specification, the request permission to use and prompt the user to choose algorithms from [permissions] are good ways to ask for consent.
Refusal is most effective if the site cannot distinguish refusal from other, common situations. This can make it more difficult for a site to pressure users to grant consent.
For example, the Geolocation API grants access to a user’s location. This can help users in some contexts, like a mapping application, but may be dangerous to some users in other contexts - especially if used without the user’s knowledge. So that the user may decide whether their location may be used by a Web page, a permission prompt should be shown to the user asking whether to grant location access. If the user refuses permission, no location information is available to the Web page.
See also:
1.5. Use identity appropriately in context
Give people control over the identifying information about themselves they are presenting in different contexts on the web, and be transparent about it.
"Identity" is a complex concept that can be understood in many different ways. It can refer to how someone presents or sees themselves, how they relate to other people, groups, or institutions, and can determine how they behave or how they are treated by others. In web architecture, "identity" is often used as a shortcut to refer to identifiers, and the information attached to them.
Features that use or depend on identifiers and the attachment of data about a person to that identifier carry privacy risks which often reach beyond a single API or system. This includes data that has been passively generated (for example, about their behaviour on the web) as well as that which has been actively collected (for example, they have filled in a form).
For such features, you should understand the context in which it will be used, including how it will be used alongside other features of the web. Make sure the user can give appropriate consent. Design APIs to collect the smallest amount of data necessary. Use short-lived, temporary identifiers unless a persistent identifier is absolutely necessary.
1.6. Support the full range of devices and platforms (Media Independence)
As much as possible, ensure that features on the web work across different input and output devices, screen sizes, interaction modes, platforms, and media.
One of the main values of the Web is that it’s extremely flexible: a Web page may be viewed on virtually any consumer computing device at a very wide range of screen sizes, may be used to generate printed media, and may be interacted with in a large number of different ways. New features should match the existing flexibility of the web platform.
These features still work across a wide variety of contexts, and can be adapted to devices that don’t support their original intent - for example, a tap on a mobile device will fire a click event as a fallback.
Features should also be designed so that the easiest way to use them maintains flexibility.
Sometimes features aren’t yet available on some implementations or platforms despite working on others. In these cases, features should be designed such that it is possible for code to gracefully fail or be polyfilled. See § 2.6 New features should be detectable.
1.7. Add new capabilities with care
Add new capabilities to the web with consideration of existing functionality and content.
The Web includes many extension points that allow for additions; see for example HTML § 1.7.3 Extensibility.
Before adding items, consider integration with existing, similar capabilities. If this leads to a preferred design approach that cannot be implemented by only adding items, it might still be possible; see § 1.8 Remove or change capabilities only once you understand existing usage.
Do not assume that a change or removal is impossible without first checking.
1.8. Remove or change capabilities only once you understand existing usage
Prioritize compatibility with existing content when removing or changing functionality.
Once a significant amount of content has come to depend on a particular behavior, removing or changing that behavior is discouraged. Removing or changing features and capabilities is possible, but it first requires that the nature and scope of the impact on existing content is well understood. This might require research into how features are used by existing content.
The obligation to understand existing usage also applies to any features that content relies upon. This includes vendor-proprietary features and behavior that might be considered implementation bugs. Web features are not solely defined in specifications; they are also defined by how content uses those features.
1.9. Leave the web better than you found it
As you add new capabilities to the web platform, do so in a way that improves the overall platform, for example its security, privacy or accessibility characteristics.
The existence of a defect in one part of the platform must not be used to excuse an addition or extension to the defect, which would further decrease the overall platform quality. Where possible, build new web capabilities that improve the overall platform quality by mitigating existing defects. Do not degrade existing capabilities without good reason.
Parts of the web platform evolve independently. Issues that are present with a certain web technology now may be fixed in a subsequent iteration. Duplicating these issues makes fixing them more difficult. By adhering to this principle we can make sure overall platform quality improves over time.
1.10. Minimize user data
Design features to work with the minimum amount of data necessary to carry out their users' goals.
Data minimization limits the risks of data being inappropriately disclosed or misused.
Design Web APIs to make it easier for sites to request, collect, and/or transmit a small amount of data, or more granular or specific data, than it is to work with more generic or bulk data. APIs should also provide granularity and user controls, in particular over personal data, that is communicated to sites. When additional functionality requires additional data, APIs can enable this subject to user consent (e.g., a permission prompt or user activation).
2. API Design Across Languages
2.1. Prefer simple solutions
Look hard for simple solutions to the user needs you intend to address.
Simple solutions are generally better than complex solutions, although they may be harder to find. Simpler features are easier for user agents to implement and test, more likely to be interoperable, and easier for authors to understand. It is especially important to design your feature so that the most common use cases are easy to accomplish.
Make sure that your user needs are well-defined. This allows you to avoid scope creep, and make sure that your API does actually meet the needs of all users. Of course, complex or rare use cases are also worth solving, though their solutions may be more complicated to use. As Alan Kay said, "simple things should be simple, complex things should be possible."
Do note however that while common cases are often simple, commonality and complexity are not always correlated.
See also:
2.2. Consider tradeoffs between high level and low level APIs
High-level APIs allow user agents more ability to intervene in various ways on behalf of the user, such as to ensure accessibility, privacy, or usability.
A font picker (high level API) was recommended by the TAG over a Font Enumeration API (low level API) as it addresses the bulk of use cases, while preserving user privacy, as it is free from the fingerprinting concerns that accompany a general Font Enumeration API. A native font picker also comes with accessibility built-in, and provides consistency for end users.
Low-level APIs afford authors room for experimentation so that high level APIs can organically emerge from usage patterns over time. They also provide an escape hatch when the higher-level API is not adequate for the use case at hand.
Lower level building blocks cannot always be exposed as Web APIs. A few possible reasons for this are to preserve the user’s security and privacy, or to avoid tying Web APIs to specific hardware implementations. However, high level APIs should be designed in terms of building blocks over lower level APIs whenever possible. This may guide decisions on how high level the API needs to be.
A well-layered solution should ensure continuity of the ease-of-use vs power tradeoff curve and avoid sharp cliffs where a small amount of incremental use case complexity results in a large increase of code complexity.
2.3. Name things thoughtfully
Name APIs with care. Naming APIs well makes it much easier for authors to use them correctly.
See the more detailed Naming principles section for specific guidance on naming.
2.4. Be consistent
It is good practice to consider precedent in the design of your API and to try to be consistent with it.
There is often a tension between API ergonomics and consistency, when existing precedent is of poor usability. In some cases it makes sense to break consistency to improve usability, but the improvement should be very significant to justify this.
Since the web platform has gradually evolved over time, there are often multiple conflicting precedents which are mutually exclusive. You can weigh which precedent to follow by taking into account prevalence (all else being equal, follow the more popular precedent), API ergonomics (all else being equal, follow the more usable precedent), and API age (all else being equal, follow the newer precedent).
There is often a tension between internal and external consistency. Internal consistency is consistency with the rest of the system, whereas external consistency is consistency with the rest of the world. In the web platform, that might materialize in three layers: consistency within the technology the API belongs to (e.g. CSS), consistency with the rest of the web platform, and in some cases external precedent, when the API relates to a particular specialized outside domain. In those cases, it is useful to consider what the majority of users will be. Since for most APIs the target user is someone who is familiar with the technology they are defined in, err on the side of favoring consistency with that.
There is also a separate section on naming consistency.
2.5. Follow guidance from feature specifications
When using a feature, follow guidance in the specification for that feature.
Specifications for features that will be used by other specifications should include guidance for using those features. This ensures that the feature is used correctly and consistently throughout the platform.
An incomplete list of such guidance follows:
-
Building Protocols with HTTP, especially on defining header fields, and other HTTP RFCs
Consult with the relevant community when using their specification. This informs that community about new usage and creates opportunities for improvements to both the using and used specifications.
2.6. New features should be detectable
Provide a way for authors to programmatically detect whether your feature is available, so that web content may gracefully handle the feature not being present.
An existing feature may not be available on a page for a number of reasons. Two of the more common reasons are because it hasn’t been implemented yet, or because it’s only available in secure contexts.
Authors shouldn’t need to write different code to handle each scenario. That way, even if an author only knows or cares about one scenario, the code will handle all of them.
When a feature is available but isn’t feasible to use because a required device isn’t present, it’s better to expose that the feature is available and have a separate way to detect that the device isn’t. This allows authors to handle a device not being available differently from the feature not being available, for example by suggesting the user connect or enable the device.
See § 9.2 Use care when exposing APIs for selecting or enumerating devices.
Authors should always be able to detect a feature from JavaScript, and in some cases the feature should also be detectable in the language where it’s used (such as @supports in CSS).
In some cases, it may not be appropriate to allow feature detection. Whether the feature should be detectable or not should be based on the user need for the feature. If there is a user need or design principle which would fail if feature detection were available for the feature, then you should not support feature detection.
Detecting the availability of a feature does not imply detecting whether consent to use the feature has been granted. Generally, detecting whether the feature is implemented can be done separately from determining whether use of the feature has been authorized. In some cases, it might be necessary to disable feature detection in order to enable denying requests to use the feature.
Also, if a feature is generally not exposed to developers, it is not appropriate to support feature detection. For example, private browsing mode is a concept which is recognised in web specifications, but not exposed to authors. For private browsing mode to support the user’s needs, it must not be feature detected.
See also:
2.7. Design textual formats for humans
Design textual formats that can be easily produced and consumed by people. Textual formats also improve transparency.
Favor readability over compactness. File size can be optimized by tooling, and tends to become a lower priority over time. When file size is a significantly higher priority, perhaps a textual format is not appropriate.
People who are presented with a textual format should be able to use a text editor to easily produce or modify content. People who edit text will introduce a range of errors, but could struggle to identify and fix those errors.
People expect some amount of flexibility in terms of how their edits are processed. Clearly defining syntactic flexibility—such as in whitespace, quoting, or delimiters—could ensure that content is both easy to edit and produces consistent results.
Containing the scope of a format that is affected by a syntax error could improve robustness and human usability. This requires that specifications fully define processing and error handling so that all inputs result in consistent outcomes.
If your format is intended to be used only by machines, a binary format is likely to be more efficient, in addition to discouraging people from authoring or editing content directly.
2.8. Consider limiting new features to secure contexts
Always limit your feature to secure contexts if it would pose a risk to the user without the authentication, integrity, or confidentiality that’s present only in secure contexts.
For other features, TAG members past and present haven’t reached consensus on general advice. Some believe that all new features (other than features which are additions to existing features) should be limited to secure contexts. This would help encourage the use of HTTPS, helping users be more secure in general.
Others believe that features should only be limited to secure contexts if they have a known security or privacy impact. This lowers the barrier to entry for creating web pages that take advantage of new features which don’t impact user security or privacy.
SecureContext] extended attribute
on interfaces, namespaces, or their members (such as methods and attributes).
However, for some types of API (e.g., dispatching an event),
limitation to secure contexts should just
be defined in normative prose in the specification.
If this is the case,
consider whether there might be scope for adding a similar mechanism
to [SecureContext]
to make this process easier for future API developers.
However, if, for some reason there is no way for code to gracefully handle the feature not being present, limiting the feature to secure contexts might cause problems for code (such as libraries) that may be used in either secure or non-secure contexts.
2.9. Don’t reveal that private browsing mode is engaged
Make sure that your feature doesn’t give authors a way to detect private browsing mode.
Some people use private browsing mode to protect their own personal safety. Because of this, the fact that someone is using private browsing mode may be sensitive information about them. This information may harm people if it is revealed to a web site controlled by others who have power over them (such as employers, parents, partners, or state actors).
Given such dangers, websites should not be able to detect that private browsing mode is engaged.
to act as if the user had immediately aborted the payment request.
This enables User Agents to automatically abort payment requests in private browsing mode (thus protecting sensitive information such as the user’s shipping or billing address) without revealing that private browsing mode is engaged.
See also:
2.10. Consider how your API should behave in private browsing mode
If necessary, specify how your API should behave differently in private browsing mode.
For example, if your API would reveal information that would allow someone to correlate a single user’s activity both in and out of private browsing mode, consider possible mitigations such as introducing noise, or using permission prompts to give the user extra information to help them meaningfully consent to this tracking (see § 1.4 Ask users for meaningful consent).
Private browsing modes enable users to browse the web without leaving any trace of their private browsing on their device. Therefore, APIs which provide client-side storage should not persist data stored while private browsing mode is engaged after it’s disengaged. This can and should be done without revealing any detectable API differences to the site.
If the User Agent has two simultaneous sessions with a site, one in private browsing mode and one not, storage area changes made in the private browsing mode session should not be revealed to the other browsing session, and vice versa. (The storage event should not be fired at the other session’s window object.)
See also:
2.11. Don’t reveal that assistive technologies are being used
Make sure that your API doesn’t provide a way for authors to detect that a user is using assistive technology without the user’s consent.
The web platform must be accessible to people with disabilities. If a site can detect that a user is using an assistive technology, that site can deny or restrict the user’s access to the services it provides.
People who make use of assistive technologies are often vulnerable members of society; their use of assistive technologies is sensitive information about them. If an API provides access to this information without the user’s consent, this sensitive information may be revealed to others (including state actors) who may wish them harm.
Sometimes people propose features which aim to improve the user experience for users of assistive technology, but which would reveal the user’s use of assistive technology as a side effect. While these are well intentioned, they violate § 1.2 It should be safe to visit a web page, so alternative solutions must be found.
The Accessibility Object Model (AOM) used to define a set of events which, when fired, revealed the use of assistive technology.
AOM has since removed these events and replaced them with synthetic DOM events which don’t reveal the use of assistive technology.
See also:
2.12. Require user activation for powerful APIs
Some powerful APIs can produce intrusive UI (eg. auto-playing audio), expose user data (eg. interacting with the clipboard), perform a background activity without an obvious indicator to the user (eg. accessing local storage), or prompt the user to interact with trusted UI (eg. permission prompts, device hardware features). These APIs should be designed to require some indication of user intention (such as user activation) in order to function. This indicates that the user is intentionally interacting with the web page in question.
User activation is defined in detail in the HTML standard. You should think about the effect your API has on the user experience, as well as any risks presented to the user, when deciding whether user activation needs to only occur once overall (sticky), periodically (transient) or once per API call (transient consuming).
Note that while user activation is in many cases necessary, it is not always sufficient to protect users from invasive behaviours, and seeking meaningful consent is also important.
2.13. Support non-fully active BFCached documents
Specify how your feature behaves in non-fully active BFCached (Back/forward cached) documents if possible.
If your feature does anything that falls into the following categories:
-
Interacts with a document from the "outside" (e.g. sends information to a document)
-
Makes cross-document interaction/resource sharing possible (e.g. holding locks)
-
May malfunction when a document is kept in a non-fully active BFCached state (instead of getting destroyed) after the user navigates away from it or gets restored (e.g. expects that a state saved in the document won’t span multiple navigations)
Specify how your feature works with non-fully active BFCached documents, following the guidelines in the Supporting BFCached Documents guide.
Note: It is possible for a document to become non-fully active for other reasons not related to BFcaching, such as when the iframe holding the document gets detached. This guidance only focuses on the case where BFCache is involved, and not other cases that might cause a document to become non-fully active.
2.14. Prioritize usability over compatibility with third-party tools
Design new features with usability as the primary goal, and compatibility with third-party tooling as a secondary goal.
The web platform benefits from a wide ecosystem of tooling to facilitate easier and faster development. A lot of the time, the syntax of an upcoming web platform feature may conflict with that of a third-party tool causing breakage. This is especially common as third-party tools are often used to prototype new web platform features.
In general, web platform features last a lot longer than most third-party tools, and thus giving them the optimal syntax and functionality should be of high priority.
In some cases, the conflict will introduce problems across a large number of web sites, necessitating the feature’s syntax to be redesigned to avoid clashes.
Array.prototype.contains() had to be renamed to Array.prototype.includes() to avoid clashes with
the identically named but incompatible method from PrototypeJS,
a library that was in use in millions of websites. However, these cases should be exceptions.
When deciding whether to break third party tools with new syntax, there are several factors to consider, such as severity of the breakage, popularity of the third party tool, and many more.
Possibly the most important factor is how severely would the usability of the web platform feature be compromised if its syntax was changed to avoid breaking the third party tool? If several alternatives of similar usability are being considered, it is usually preferable to prioritize the ones that inconvenience third party tools the least.
However, if avoiding breaking the third party tool would lead to a significant negative impact on of the feature’s usability, that is rarely an acceptable tradeoff, unless it causes significant breakage of live websites.
Languages should also provide mechanisms for extensibility that authors can use to extend the language without breaking future native functionality, to reduce such dilemmas in the future.
2.15. Build complex types by composing simpler types
Define subtypes that can always be used in place of a supertype. Avoid interfaces that use inheritance unless everything that can be said about an instance of the parent always applies to the child as well.
With inheritance, a subtype creates a type of item that can stand in for its supertype. A subtype needs to provide the same attributes and methods as its supertype. The subtype also needs to maintain consistent behavior. If the subtype changes the way that an item works, something that handles the supertype might not work properly.
In the theory of type systems, this is known as the Liskov Substitution Principle.
Event type is a super-type of KeyboardEvent and PointerEvent.
Events always have the same basic set of properties and actions that apply,
like whether the event bubbles.
The subtypes add new properties and actions,
but instances of those subtypes still act in every way as an Event. A simpler approach is often to avoid inheritance and reuse existing capabilities by composition. New items can define properties that hold any existing components that are needed.
HTMLInputElement would be difficult,
because an input element is quite complex
and a specialization of HTMLInputElement would need to maintain that complexity.
Custom elements can attach (i.e., compose) items that are necessary to
interact with a form
without having to deal with the complications of HTMLInputElement. 3. HTML
This section details design principles for features which are exposed via HTML.
3.1. Re-use HTML attribute names (only) for similar functionality
If you are adding a feature that is specified through an HTML attribute, check if there is an existing attribute name on another element that specifies similar functionality. Re-using an existing HTML attribute name means authors can utilize existing knowledge, maintains consistency across the language, and keeps its vocabulary small.
multiple,
is used on both select to allow selection of multiple values,
as well as on input to allow entry of multiple values. If you do re-use an existing HTML attribute, try to keep its syntax as close as possible to the syntax of the existing attribute.
for attribute was introduced on the label element,
for specifying which form element it should be associated with.
It was later re-used by output,
for specifying which elements contributed
input values to or otherwise affected the calculation.
The syntax of the latter is broader:
it accepts a space-separated list of ids,
whereas the former only accepts one id.
However, they both still conform to the same syntax,
whereas e.g. if one of them accepted a list of ids,
and the other one a selector, that would be an antipattern. The inverse also applies: do not re-use an existing HTML attribute name if the functionality you are adding is not similar to that of the existing attribute.
type attribute is used on the input and button elements
to further specialize the element type,
whereas on every other element (e.g. link, script, style)
it specifies MIME type.
This is an antipattern; one of these groups of attributes should have had a different name. 3.2. Use space-separated attributes for short lists of values, separate elements for longer lists
When specifying metadata about an element that can be a list of values,
common practice is to use a space-separated list and expose it as a DOMTokenList.
The class attribute on elements takes a space-separated list of class names. classList is a DOMTokenList that allows authors to add and remove class names.
The sandbox attribute takes a space-separated list of sandbox flags. iframe.sandbox is a DOMTokenList that allows authors to add and remove sandbox flags.
Consistency with other parts of the Web Platform is important, even if this means using another character to separate values.
The accept attribute is a comma-separated list of values,
because it needs to match the syntax of the `Accept` HTTP header.
Regardless of syntax, attributes should only be used for short lists of values. For longer lists, embedding the entire list in an attribute is discouraged. Instead, current practice is to use separate elements to represent the list items (and any metadata about them). These elements could either be children of the element in question, or linked through an attribute.
The list of values for the select element is provided as a series of option element children.
However, when providing a list of recommended values for an input element, a separate element is used (datalist),
linked through a list attribute.
The list of media sources for a video or audio element is provided as a series of source element children.
In rare instances, other tradeoffs are necessary.
The srcset attribute allows for a comma-separated list of image candidate strings.
This syntax was chosen over a list of child elements to avoid verbosity
and because the img element is an empty element that does not permit child elements.
A space-separated syntax would not have been possible, as each list item includes multiple values.
3.3. Do not pause the HTML parser
Ensure that your design does not require HTML parser to pause to handle external resources.
As a page parses, the browser discovers assets that the page needs, and figures out a priority in which they should be loaded in parallel. Such parsing can be disrupted by a resource which blocks the discovery of subsequent resources. At worst, it means the browser downloads items in series rather than parallel. At best, it means the browser queues downloads based on speculative parsing, which may turn out to be incorrect.
Features that block the parser generally do so
because they want to feed additional content into the parser
before subsequent content.
This is the case of legacy
Index
Terms defined by this specification
Terms defined by reference
References
Normative References
Informative References
Property Index
Name
Value
Initial
Applies to
Inh.
%ages
Animation type
Canonical order
Computed value
font-size-adjust
none | [ ex-height | cap-height | ch-width | ic-width | ic-height ]? [ from-font | none
all elements and text
yes
N/A
discrete if the keywords differ, otherwise by computed value type
per grammar
a number or the keyword nonethe keyword none, or a pair of a metric keyword and a