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, these specification levels indicate which features a viewer is required to support in order to be compatible, and which features they are not required to support.

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

Adherence to Behavior Specifications
This should go without saying, but is worth saying outright: For both required and optional features, an implementation must adhere to the specifications described for each feature in the API. Obviously, this is necessary for compatibility, since an implementation which behaves in unexpected ways is surely incompatible.

So, if the specifications says the viewer responds with Error.ChatInvalidChannel when a requested chat channel number is too high, then all implementations must adhere to that behavior. Likewise, if the specification says that the "rotation" property of a prim means the prim's rotation relative to the world, expressed as a quaternion, the implementation must adhere to that definition.

In some cases, the specification offers some leeway for the implementation author to decide on certain minor details. In these cases, of course, the implementation can vary somewhat, but only within the parameters described in the specification.

For extra features, an implementation is not required to adhere to any specific behavior (since the API contains no specifications for extra features). However, new implementations are strongly encouraged to respect the behavior of existing implementations that support those extra features. This is particularly true if there exists a specification somewhere (not part of the standard API specification) for that feature.