User:Jacek Antonelli/Plugin System/Message Syntax

This page describes the overall style of the syntax of the messages passed back and forth between a plugin and the viewer.

JSON vs XML
In thinking about the Plugin System, we considered (briefly) the format data structures should be sent as. The contenders were XML and JSON, due to their widespread use and support in a large number of programming languages.

XML has been a standard for years, and is widely used for many purposes. However, it is very verbose (often more bytes spent on boilerplate than on actual data), and relatively slow to parse.

JSON is a newer standard, but is already widely used and has excellent support in many programming languages. Its syntax is simple and frugal, but can express most (if not all) of the things XML can.

Given the equal expressive power and superior transmission and parsing speed of JSON, it's highly likely that it will be used for passing messages between the viewer and plugins.

Glossary of Terms

 * Array: A JSON array, an ordered list of elements. E.g.
 *  : Within the syntax examples, words starting with a dollar sign ($) are placeholders for the actual data. The type and meaning of the expected data are described after the examples.
 * Plugin-Viewer Programming Interface (PVPI): The sockets-based API that plugins can use to interface with the viewer; the defined catalogue of requests and responses that can be sent to and from the viewer.
 * Request: A plugin-initiated message sent to the viewer to instruct the viewer to perform an action or to retrieve some data.
 * Response: A message sent from the viewer to the plugin in response to a request. Often this carries some data, but other times is just a simple acknowledgement that the request was received.
 * Struct: A JSON object, an unordered, string-indexed list of elements. AKA. a dict, hash, or associative array. E.g.

Request / Response Format
General format for requests and response exchanged between the plugin and viewer.

["$request_id", "$request", ... ]

is an arbitrary string provided by the plugin when sending a request. The viewer will include the same string as  in the response. This is intended to allow the plugin to keep track of which response goes with which request. If the plugin doesn't care about that, it can provide an empty string or something.

is the request name, as defined in the PVPI. E.g. "GetProps".

The types and meaning of the remaining elements in the array (if there are any) vary with the specific request. If you care to think of these messages as being equivalent to method calls, then the remaining elements are the "arguments" to the method.

General Entity Struct
General struct format for entities. That could be avatars, inventory items, prim objects, UI widgets, etc.

{"entity"    : "$entity_id", "$property1" : $value1, "$property2" : $value2, ... }

is the string identifying the entity. It it consists of "$type:$id" -- the entity type, a colon, then a string that uniquely identifies that entity. The exact system used for the identifying string varies from type to type, but for many types it would be a UUID. E.g. the entity ID for a texture might be.

and  are property names and their corresponding values, such as color, UUID, position, etc. The catalogue of supported properties varies by entity type.

Error Messages
Format for error messages when an request fails for some reason.

["$request_id", "$error_type", "$message", { $extra_data } ]

is the type name of the error as defined in the PVPI, which can be used by the plugin to identify what sort of error occured. Example: "MissingArgument".

is a descriptive string explaining what the error is, intended to be read by a human being. The exact message may vary between implementations, or even within an implementation, since it may need to be translated to another tongue or tailored to different user technical levels. For this reason, plugins should never try to scan the message text to deduce what the error was (that's what  is for!). Example message: "The Object.Delete request was missing a required argument: uuid".

is an optional struct holding any other data that can help indicate what the error was. If there's no extra data, this can be omitted. Example: