Plugin System/API/Specification Levels

Introduction
This page explains the multiple levels of specification for API features. Anticipating that there may be future or alternative viewers which wish to be compatible with plugins using this API.

In this context, the term "features" includes:
 * Requests (e.g. SendChat, GetProps)
 * Entity properties (e.g. color, position)
 * Event properties (e.g. sender_name, time)

The specification levels are:


 * Required Features: Features which every implementation MUST provide.
 * Optional Features: Features which an implementation MAY provide.
 * Extra Features: Optional features not specified in the API.

Required Features
There are some features which are so fundamental that a plugin should be able to rely on every implementation supporting them. Therefore, these features and their meanings are specified in the API, and every implementations is required to provide them.

For example, a menu widget fundamentally has a label and a number of child menu items. Without these things, the menu widget cannot function, so those features are required.

However, anticipating that the API will be extended from time to time to add new features, and that some implementations will not need all features, the following qualification is necessary:


 * If an implementation claims to support a specific feature set, it must support all required features in that feature set. If it does not support all required features in that feature set, it should support no features in that set, and must not claim to support that feature set.

Optional Features
In addition to required features, there are optional properties. These are distinguished by the fact that the system can reasonably be expected to function without.

For example, style properties like color or font family are not necessary for a menu widget to function, so those features are optional.

Like required features, optional features and their meanings are specified in the API. Unlike required features, an implementation is not required to support all or any of the optional features.

However, an implementation must not break if it receives an unsupported optional feature, and it also must not break if it doesn't receive an optional feature that it expected. However, in the case of unsupported requests (but not entity or event properties), the implementation should respond with Error.NotImplemented.

Extra Features
It's inevitable that there will be unanticipated extra features which are meant for use on only one or a few implementations, due to the unique abilities offered by those implementations. Extra features are, by their nature, not specified in the standard API, and implementations are not required to support them.

The requirements of extra features are similar to those of optional features, including the requirement of gracefully handling both unexpected features and expected-but-not-received features, and of responding to unsupported requests with Error.NotImplemented.

An extra feature may not override a feature of the same name in the same context (i.e. an implementation can't give a special new meaning to an API-defined feature.)