# services.json

- Application properties
- Service properties
- Command properties
- Schemas
- Security

The `services.json` file is in the root directory of a Mojo service, and describes how the service is constructed, and how it operates. Generally, only a subset of this `services.json` file is required to correctly define a service. Here we provide a reference for all properties defined in the file:

>     {
>       "description": <optional string>,
>       "commandTimeout", <optional number>,
>       "activityTimeout", <optional number>,
>       "services":
>       [
>           {
>               "name": <string>,
>               "description": <optional string>,
>               "assistant": <optional string>,
>               "commandTimeout", <optional number>,
>               "commands":
>               [
>                   {
>                       "name": <string>,
>                       "description", <optional string>,
>                       "assistant", <string>,
>                       "watch", <optional boolean>,
>                       "subscribe", <optional boolean>,
>                       "schema", <optional string or object>,
>                       "commandTimeout", <optional number>,
>                   },
>                   <...more commands...>
>               ]
>           },
>           <...more services...>
>       ],
>       "schemas": <optional object>
>       {
>           <schema name>: <schema>
>       }
>     }

## Application properties

The top-level properties are the application properties. These provide configuration for the overall application.

### description

An optional property that should be used to provide an informative aaplication description.

### commandTimeout

Defines the number of seconds commands should run before a timeout error is returned to the caller. This can be overridden (see below). If not defined, this defaults to 60 seconds.

### activityTimeout

Defines the number of seconds the application continues to run after the completion of the last activity, before it terminates. Services do not run all the time, but launch when needed, and terminate when not in use. Typically, a command is considered to be an activity, so the application will not terminate while a command is being processed. It is also possible to have other non-command activities (e.g., background activities). If not defined, this defaults to 60 seconds.

### services

Defines an array of services being provided by this application. Typically, an application will only provide one service. However, there may be reasons to provide multiple services within the same application (e.g., old API versions). An application must define at least one service (since an application without services probably does not make sense). The properties of a service are defined below.

Note: more than one service per application is not currently supported.

### schemas

This optional property contains an set of string/schema pairs. See the separate section below on schemas.

## Service properties

Each application defines one or more services.

### name

The name of the service on the Palm Message Bus. All services must define a name. The name must begin with the app name. For example:

app name: 'com.palmdts.testacct' service name: 'com.palmdts.testacct.contacts.service'

### description

An optional property providing an informative description of this service.

### assistant

An optional property defining the name of a class that should be instantiated to manage this service. The service assistant runs only once when the service starts. However, it can be used to store more-persistent state since command assistants are only around when processing a request.

For example:

>      var assistant = this.controller.service.assistant;
>      assistant.saveState(someState);

### commandTimeout

Defines the number of seconds commands should run before a timeout error is returned to the caller. This overrides any value defined at the application level for this service, but may be overridden in turn by a command (see below). If not defined, this inherits the value defined for the application.

### commands

Defines an array of commands being provided by this service. A service may provide zero or more commands per service (a service with no commands may simply want to run once when the application is started). The properties of a command are defined below.

## Command properties

Each service defines a number of commands.

### name

The name of the command in this service. All commands must define a name.

### description

An optional property providing an informative description of this command.

### assistant

A required property defining the name of a class that should be instantiated to manage this command. The command assistant's run method will ultimately be called to actually execute the command.

### watch

An optional boolean value, defaulting to false if not present. If defined as true, this command is watchable. A watchable command has two return values to the caller. The first return value is the usual response to the command. The second return value, which is sent sometime later, indicates that the command should be re-executed, because the value it returns may be different from the last time it was called. This mechanism is similar to subscriptions, but is naturally rate-limited by the consumer of the service, resulting in less unnecessary bus traffic and fewer application stampedes when service state changes.

### subscribe

An optional boolean value, defaulting to false if not present. If defined as true, this command supports subscriptions. An application or another service can request a subscription by setting subscribe to true in the request.

A subscription is typically used for a command which can take a long time to run, but where incremental progress can be indicated to the caller. The webOS Download Manager is an example of a service that implements subscriptions.

Commands which have a subscription active do not time out.

For a subscribeable command, the run() function is passed a second parameter, which is a FutureFactory object, which provides Future objects for subsequent responses.

Example:

>     run: function(future, subscription) {
>       var count = 1;
>       future.result = { reply: "this is the initial response"};
>       this.interval = setInterval(function ping() {
>           // subscription.get() returns a future to use for the next response
>           var f = subscription.get();
>           f.result = { reply: "response #"+count++};
>       }, 1000);
>     },

Apps implementing a subscribable ommand should make requests from the application with Mojo.Service.Request, rather than using the Mojo.Controller.SceneController's request() method, since the controller cancels any requests when the scene closes.

### schema

An optional property defining the JSON schema to use to validate the incoming arguments for the command. The property can either be a JSON schema or a string. If a string is used, this should match a property in the application-level schema object.

### commandTimeout

Defines the number of seconds this command should run before a timeout error is returned to the caller. This overrides any value defined at the service or application level. If not defined, this inherits the value defined by the service or the application.

## Schemas

Command arguments may be optionally validated using a JSON Schema. If a schema is used, only commands that pass validation will be executed by the service. Otherwise, schema errors are returned to the caller.

### schema

The schema property at the application level defines a set of string/schema pairs. Each named schema can be referenced by zero or more commands using their schema property. The value of the pair corresponds to a JSON schema, which will be used for command validation.

## Security

The LS2 security role files will be automatically created from `services.json` at build time. You will be able to override certain default behavior with custom properties in the `services.json` file. Check back soon for details.