Satori Docs

Your definitive guide to subscribing and publishing live data

RTM API Direct link

Version: v2

Overview Direct link

The RTM protocol is our wire protocol, which enables direct two-way communication between a client and RTM. Clients communicate with RTM by establishing a secure WebSocket connection and exchanging JSON formatted units.

RTM implements the publish-subscribe pattern where users publish messages to a channel and all subscribers to that channel receive those messages.

The RTM API defines the structure, rules and semantics for exchanging the JSON objects. We call these JSON objects Protocol Data Units (PDUs). A PDU can carry a request to RTM to perform a particular action (such as to publish a message), its response from RTM, or an unsolicited message, such as subscription data.


Message Order Guarantees

RTM  forwards published messages to the subscribers in the same order as it received them. The order of messages between different publishers is not guaranteed. All subscribers will receive the published messages in the same order.


Protocol Data Unit (PDU) Direct link

Definition

A PDU is a JSON-formatted unit with a specific structure enabling meaningful communication between RTM and clients. Each PDU is encoded into a single WebSocket frame. RTM supports UTF-8.

We use custom self-explanatory “mini schema” to define the format of the PDUs. It lists JSON fields (possibly optional) followed by their type or placeholder values (which in turned are defined the same way). Fields order does not matter. See Mini-schema Reference for more details.

The following mini schema  defines the structure of a PDU. Note that this structure holds for all PDUs in RTM API.

{
     "action": string,
     "id": string | integer OPTIONAL,
     "body": object
}


PDU Types

A PDU can represent any of the following units of communication:

  • A request to RTM. A request to perform an action, for example, to publish a message.

  • A response from RTM. The response to a client request.

  • Unsolicited subscription messages from RTM. Messages as they have been published to the channel for simple subscriptions, or resulting messages for subscriptions with views.

  • An unsolicited error or information updates. Channel-specific informational or error messages, or system error messages, sent by RTM to the client.


PDU Size

User generated "payload" is limited to 64kB: such as message in the Publish PDU or filter in the Subscribe PDU. The total size of an unparsed PDU is limited to 65kB. RTM may drop the client connection if the size exceeds the limit.


action Field

The action field specifies the purpose of a PDU and determines the content of the body.

The action field consists of up to three components separated by forward slash: <service>/<operation>/<outcome>.

The following table explains the meaning of each component, as well as the rule for parsing it out from the full action string value.  


Action component

Meaning

Parsing rules

service

Name of the service responsible for handling incoming requests or sending responses and unsolicited PDUs.

The first part of the action string up to the first backslash character ‘/’.

operation

Operation the client wants the service to perform.

After the first backslash character "/" up to the outcome or end of the string.

Note that it may contain backslashes as part of the operation.

outcome

Represents the result of the request or the type of information provided to the client.

Present only in responses and unsolicited PDUs. The part after the last backslash "/".


The following table summarizes possible values used in the action field:

Service

Operation

Outcome

rtm

publish
subscribe
unsubscribe

read
write
delete

ok
error

subscription

data
info
ok
error

auth

handshake
authenticate

ok
error


id Field

The id field in a request PDU instructs RTM to send a response and enables a client to match a response to a request. If the id field is not present in a request, RTM does not acknowledge it: no response will be sent to a client, regardless of the outcome. Note that id field and its semantics applies to every PDU in the RTM protocol.

The id field can be a JSON int() or string() type.

Even though specifying id field in a request is optional, only a few cases benefit from omitting it (e.g. high throughput publishing);  some operation cannot be completed without id at all (e.g. authentication). Clients should specify id in a request, unless client logic identified a concrete motivation not to do so, for a specific use case.


Use the following rules and guidelines with the id field:

Rule/Guideline

Description

Include id field to get a response from RTM

In most cases, there is no significant traffic savings from omitting the id but by doing so, client forfeits an opportunity to detect failing requests (error outcome).

Avoid reusing id value in different requests

RTM does not enforce uniqueness on the id field. Two requests with the same id are treated as two separate requests by RTM.


body Field

The body field’s content is specific to the PDU's action. The structure and semantics of the body field’s content must be followed for each action field type.

See the definitions of the specific PDU types.


Channels Direct link

Channel is a named stream of messages.

A channel is unique per Dev Portal project. If two projects have channels with the same name, RTM treats them as separate channels: they have their own content, history, settings, permissions, etc.


Subscription

Subscription is a client’s interest in messages published to a channel, accepted and served by RTM.

In the simplest case, subscription establishes a client’s interest in all messages as they arrive to a channel. Client may also request a subscription to include past messages (see history and position). In more involved cases, messages data can be filtered or/and transformed (see Views)


Position

Position is a message offset relative to other messages in a channel. It uniquely identifies a message location in a channel and may refer to an expired (no longer stored), available (stored, retrievable), or future message (not yet occupied location).


Next channel position is the first available unoccupied position in a channel: next published message to arrive will be placed at the next position.


The position field can be used to read a particular message from a channel or to subscribe from a specific position, typically in order to avoid skipping message when re-subscribing.

Operation PDU type Meaning of the position

RTM includes position 


(in responses or data PDUs).

publish, write, delete

ok response

Location of the published message

subscribe

ok response

Location of the first message to be received for the subscription

unsubscribe

ok response

Location that can be used to seamlessly resubscribe

subscription

unsolicited data

next location after the last message contained in the PDU. Client can use this location to resubscribe preserving stream continuity (no message loss).

User can include position

(in request PDUs)

subscribe

request

Location to start a subscription at

read

request

Location from which to read a message


Implicit Channel Creation and Deletion

Channel instances are automatically created by RTM on demand: upon the first subscribe or publish request to a specified channel name, RTM creates a corresponding channel instance.

RTM automatically garbage collects channels when it is safe to do so (channel is empty and no one has been accessing it for some time).

Channel instance creation and deletion should not be confused with managing channel bookeeping in Dev Portal, such as setting permissions or history for specific channel names or namespaces.

Permissions

Channel access can be controlled by configuring publish and subscribe permissions (akin to write/read permissions) in Dev Portal.


History

In addition to forwarding published messages to all subscribers, RTM also stores all messages for at least 1 minute. Additionally, longer storage is available with channel history: users can configure how many messages should be stored for a longer period of time for a given channel. History settings are configured in Dev Portal and default to one message for 6 hours.

A subscription to a channel can be requested starting at a historical message; similarly read operation can retrieve messages published in the past.


Naming

Channel names are case sensitive.

Channel names starting with character ‘$’ are reserved by RTM.



Publish PDU Direct link

Messages can be published to a channel by sending a Publish PDU request to RTM.

The following specification shows the publish request and response PDUs.

request
{
  "action":"rtm/publish",
  "id":RequestId OPTIONAL,
  "body":{
    "channel":ChannelName,
    "message":Message
  }
}
response (ok) response (error)
{
  "action":"rtm/publish/ok",
  "id": RequestId,
  "body":{
    "position":Position
  }
}
{
  "action":"rtm/publish/error",
  "id":RequestId,
  "body":{
    "error":ErrorName,
    "reason":ErrorReason
   }
}


Field Value

Type

Description

ChannelName

string

The name of the channel to publish to.

Message

value

The message to publish to the channel.

Message size is limited to 64 kB. RTM may disconnect if the size exceeds the limit. See PDU Size in Protocol Data Unit (PDU) section. 


Although any JSON value is allowed, publishers should publish JSON object messages to facilitate subscribers with views. See Views.    

Position

string

The channel location of the published message. See Position in Channels.

ErrorName

string

See Error Reference.

ErrorReason

text

Human readable error description. See PDU Error Reference.



Subscribe PDU Direct link

A client subscribes to a channel by sending a request Subscribe PDU to RTM.


position

By default, a new subscription starts at the next channel position (from the next published message, see position in Channels). That is, no previously published (historic) messages are returned. A client may start a subscription at an  earlier (historic) message by specifying the position in the subscribe request PDU.


subscription_id

A subscription is identified by the subscription_id field. Multiple subscriptions can be made to the same channel, as long as different subscription id’s are used.

For a subscription without a view (default), the subscription_id must be equal to the channel name, and is optional.

For a subscription with a view, the subscription_id field is required and the channel field is optional (the channel name must match what is specified in the filter (view) field).


Subscribe without View (no filter field)
request
{
  "action":"rtm/subscribe",
  "id":RequestId OPTIONAL,
  "body":{
    "channel":ChannelName,
    "subscription_id":SubId OPTIONAL,
    "force":Force OPTIONAL,
    "fast_forward":FastForward OPTIONAL,
    "position":Position OPTIONAL,
    "history":{ 
      "count":Count OPTIONAL,
      "age":Age OPTIONAL
    } OPTIONAL
  }
}
response (ok) response (error)
{
  "action":"rtm/subscribe/ok",
  "id":RequestId
  "body":{
    "position":Position,
    "subscription_id":SubId
  }
}
{
  "action":"rtm/subscribe/error",
  "id":RequestId,
  "body":{
    "error":ErrorName,
    "reason":ErrorReason OPTIONAL,
    "subscription_id":SubId
   }
}


Subscribe with View (filter field)
request (subscription id)
{
  "action":"rtm/subscribe",
  "id":RequestId OPTIONAL,
  "body":{
    "filter":SQL,
    "subscription_id":SubId,
    "force":Force OPTIONAL,
    "fast_forward":FastForward OPTIONAL,
    ”period”:Period OPTIONAL,
    ”position”:Position OPTIONAL,
    "history":{ 
      "count":Count OPTIONAL,
      "age":Age OPTIONAL
    } OPTIONAL
  }
}
response (ok) response (error)
{
  "action":"rtm/subscribe/ok",
  "id":RequestId,
  "body":{
    ”position”:Position,
    ”subscription_id”:SubId
  } 
}
{
  "action":"rtm/subscribe/error",
  "id":RequestId,
  "body":{
    "error":ErrorName,
    "reason":ErrorReason OPTIONAL,
    "subscription_id":SubId
   }
}


Field

Type

Description

ChannelName

string

The name of the channel to subscribe to.

SubId

string

Either a channel name or a unique client-generated identifier for the subscription (when applicable)

Position

string

Channel location to start the subscription at. Default is the next channel position.

See position in Channels section.

SQL

string

SQL statement to run on messages before sending them to the client. The size is limited to 64 kB. See Views.

Period

int

Time partition on the channel messages, in seconds, for which RTM aggregates the view result per partition. See Views.

Force

boolean

Directs RTM how to behave in case the client has a pre-existing subscription with the same subscripiton_id.

If true, RTM accepts a resubscription, keeps the position of the pre-existing subscription, and resets the view (filter field) for this subscription.

If false, RTM rejects the  subscription request (sends error outcome).

Default is false.

FastForward

boolean

Specifies preferred behavior if an out_of_sync error situation occurs.

true directs RTM to fast-forward the subscription to the oldest available message

false directs RTM to force unsubscription

Default is false

history

object

Contains a non-negative integer in the age field or count field.

See history in Channels section.

history:{} returns no history.

Age

int

RTM starts the subscription this many seconds earlier than the value in the position field.

Count

int

RTM starts the subscription this many messages before the value in the position field.

ErrorName

string

See Error Reference.

ErrorReason

text

Human readable error description. See Error Reference.

RequestId

int | string

See id field in PDU section.


out_of_sync and fast_forward

RTM sends subscription messages to the client as fast as the physical network link to the client allows it. If the rate of incoming (published) messages is higher than the outgoing rate (rate at which messages are delivered to a particular client subscription), we say that a client subscription is falling behind. If this situation persists, undelivered messages accumulate on the RTM side and eventually RTM expires (deletes) them. By default, messages are deleted after 60 seconds and the last message in a channel - after 6h. We call this situation out_of_sync: messages stream continuity cannot be sustained for a subscriber; message drop is inevitable.

Subscriber can change this behavior by setting the fast_forward field to true in the request Subscribe PDU. In this case, RTM “fast-forwards” the client to the oldest not yet deleted message, instead of forcing unsubscription, and sends an info Subscription PDU.


Updating a Subscription

filter and period fields can be changed on-the-fly for a pre-existing active subscription: by sending a Subscribe PDU with the force field set to true. Without "force":true, RTM responds with an already_subscribed error and does not update the current subscription.



Subscription PDUs (unsolicited) Direct link

RTM sends subscription data (channel messages) or subscription related status (info or error) using Subscription PDUs.

Subscription PDU can be:

  • data.  A Subscription Data PDU delivers channel messages (possibly filtered and transformed messages in case of a viewed subscription). Note that a single Subscription Data PDU can contain multiple messages grouped in the array messages field (for optimization purposes). 
  • info. A Subscription Info PDU contains information about a subscription, which includes the type of info and the reason why RTM sent it. For a fast_forward info, it also includes the count of skipped messages due to RTM fast-forwarding the subscription.
  • error. A Subscription Error PDU notifies of subscription termination (forceful unsubscription) due to a subscription-related error. For example, if a client subscription falls behind and fast-forward has not been enabled, RTM sends an out_of_sync error and unsubscribes the client (see out_of_sync in Subscribe PDU section)


subscription data
{
  "action":"rtm/subscription/data",
  "body":{
    "position":Position,
    "messages":[Message]*,
    "subscription_id":SubId
   }
}
subscription info subscription error
{
  "action":"rtm/subscription/info",
  "body":{
    "info":InfoType,
    "reason":InfoReason,
    "position":Position,
    "subscription_id:SubId, 
    "missed_message_count":Count OPTIONAL
   }
}
{
 "action":"rtm/subscription/error",
  "body":{
    "error":ErrorName,
    "reason":ErrorReason,
    "position":Position,
    "subscription_id":SubId,
    "missed_message_count":Count OPTIONAL
   }
} 

field name or placeholder

Type

Description

Position

string

See position in the Channels section.

Provided to enable clients to resubscribe preserving stream continuity (in the event of a disconnect).

Message

value

A channel message (as it was published, or - when applicable - a message result according to the subscription view)

SubId

string

Id for the subscription for which the PDU was sent.

InfoType

string

Information type. See Service-Specific Info Messages.

InfoReason

text

Text description intended for human use.

Count

int

Number of skipped messages in the channel.

ErrorName

string

See Error Reference.

ErrorReason

text

Human readable error description. See Error Reference.


Unsubscribe PDU Direct link

A subscriber requests to terminate its subscription by sending an Unsubscribe PDU request to RTM.

In case a client endpoint has multiple subscriptions to the same channel, it must send a PDU for each subscription it wants to end.

request
{
  "action":"rtm/unsubscribe",
  "id":RequestId OPTIONAL,
  "body":{
    ”subscription_id”:SubId
  }
}
response (ok) response (error)
{
  "action":"rtm/unsubscribe/ok",
  "id":RequestId,
  "body":{
    ”position”:Position,
    ”subscription_id”:SubId
  }
}
{
  "action":"rtm/unsubscribe/error",
  "id":RequestId,
  "body":{
    ”error”:ErrorName,
    ”reason”:ErrorReason,
    ”subscription_id”:SubId OPTIONAL
   }
}


Field placeholder

Type

Description

SubId

string

Id of the subscription that you want to cancel.

Position

string

RTM response includes current location in the channel message stream at the time unsubscribe operation has completed.

Enables a client to resubscribe to the channel from the position where it unsubscribed

ErrorName

string

See Error Reference.

ErrorReason

text

Human readable error description. See Error Reference.



Read PDU Direct link

A particular message in a channel can be retrieved by sending a Read PDU request to RTM.

RTM returns the message at the position specified in the request. If there is no position specified, RTM defaults to the position of the latest message in the channel. A null message in the response PDU means that there were no messages at that position.

request
{
  "action":"rtm/read",
  "id":RequestId OPTIONAL,
  "body":{
    ”channel”:ChannelName,
    ”position”:Position OPTIONAL
   }
} 
response (ok) response (error)
{
  "action":"rtm/read/ok",
  "id":RequestId,
  "body":{
    "position":Position,
    "message":Message
  }
}
{
  "action":"rtm/read/error",
  "id":RequestId,
  "body":{
    ”error”:ErrorName,
    ”reason”:ErrorReason
  }
}

Field

Type

Description

ChannelName

string

The name of the channel to read from.

Position

string

The channel location to retrieve a message at.

See position in the Channels section.

Message

value

Message returned by RTM.

ErrorName

string

See Error Reference.

ErrorReason

text

Human readable error description. See Error Reference.

RequestId

int | string

See id Field in the Channels section.


Write PDU Direct link

Write PDU is provided for key-value (dictionary storage) semantics: channel name represents a key and the last (and the only used) message the channel represents a value. In other words, a channel serves as a dictionary entry.  

Current implementation and specifications are the same as publish PDU but using write operation in action: "action":"rtm/write".

Delete PDU Direct link

Delete PDU is provided for key-value (dictionary storage) semantics to erase a value for a given key. Key is represented by a channel, and only the last message in the channel is relevant (represents the value). Hence, publishing a null value, serves as deletion of the the previous value (if any).

Sending a Delete PDU request is the same as publishing or writing a null value to the channel.

Delete operation requires publish permission.


request
{
  "action":"rtm/delete",
  "id":RequestId OPTIONAL,
  "body":{
    "channel":Channel
  }
}
response (ok) response (error)
{
  "action":"rtm/delete/ok",
  "id":RequestId,
  "body":{
    "position":Position OPTIONAL
  } 
} 
{
  "action":"rtm/delete/error",
  "id":RequestId,
  "body":{
    "error":ErrorName,
    "reason":ErrorReason
  }
}

Field

Type

Description

ChannelName

string

The name of the channel.

Position

string

Present only in a response.

Channel location at which the message has been deleted, when purge is false.

When purge is true, position is not returned.

See position in the Channels section.

ErrorName

string

See PDU Error Reference.

ErrorReason

text

Human readable error description. See Error Reference.

RequestId

int | string

See id field in the PDU section.


Using Delete

Deleting a channel message is the same as publishing or writing null to the channel. For example, these three requests to RTM accomplish identical result:

{"action":"rtm/publish","body":{"channel":"x","message":null}}

{"action":"rtm/write","body":{"channel":"x","message":null}}

{"action":"rtm/delete","body":{"channel":"x"}}



Handshake & Authenticate PDUs Direct link

RTM uses role-based authentication and authorization. Roles and their channel permissions are configured in Dev Portal.

Client connection to RTM is established in default role. Client can acquire different the permissions by authenticating for a different role. This is done in a two-step process using the Handshake and then Authenticate PDU.


Handshake PDU

Client sends the Handshake PDU to obtain the nonce required to perform role-based authentication.

In case of ok outcome, RTM returns the nonce. In case of an error, RTM cancels the handshake request. For example, negative response may occur if the role did not exist in the Dev Portal.


request
{
  "action":"auth/handshake",
  "id":RequestId OPTIONAL
  "body":{
    "method":AuthMethod,
    "data":{
      "role":Role
     }
  }
}
response (ok) response (error)
{
  "action":"auth/handshake/ok",
  "id":RequestId,
  "body":{
    "data":{
      "nonce":Nonce
     }
  }
}
{
  "action":"auth/handshake/error",
  "id":RequestId,
  "body":{
    “error”:ErrorName,
    “reason”:ErrorReason
   }
  }
}

Field

Type

Description

AuthMethod

string

Method of authentication to perform. Only “role_secret” is currently supported.

Role

string

Role to authenticate as.

Nonce

string

Cryptographic random value to be combined with the secret by the client to produce the hash. Hash is sent in rtm/authenticate request.

ErrorName

string

See Error Reference.

ErrorReason

text

Human readable error description. See Error Reference.


Authenticate PDU

Client sends the Authenticate PDU to complete the authentication process. After authentication is complete, the client has the permissions associated with the role with which it has authenticated.

In case of an error, RTM cancels the authenticate request. Negative confirmation occurs, for example, if the hashes did not match or the role did not exist in the Dev Portal.

request
{
  "action":"auth/authenticate",
  "id":RequestId OPTIONAL,
  "body":{
    "method":AuthMethod,
    "credentials":{
      "hash":Hash
    }
  }
}
response (ok) response (error)
{
  "action":"auth/authenticate/ok",
  "id":RequestId,
  "body":{}
}
{
  "action":"auth/authenticate/error",
  "id":RequestId,
  "body":{
    "error":ErrorName
    "reason":ErrorReason
  }
}

Field

Type

Description

AuthMethod

text

Method of authentication to perform. Only “role_secret” is currently supported.

Role

text

Role to authenticate as.

Project roles and their permissions  are managed in Dev Portal.

Hash

string

HMAC-MD5 hash value computed for the secret key and the nonce received in rtm/handshake/ok.

ErrorName

string

See Error Reference.

ErrorReason

text

Human readable error description. See Error Reference.


Hash computation

Hash is calculated for a secret key (K) and a nonce (N).  The secret key is obtained from the Dev Portal; nonce is received in Handshake response PDU.

Hash = base64( HMAC-MD5( utf8(K), utf8(N) ) )

Existing HMAC-MD5 implementations are commonly available for any language. For completeness:

HMAC-MD5 is the algorithm specified in [RFC 2104] using MD5 [RFC 1321] as the underlying hash function. base64 is a string representation of a byte array described in [RFC 3548]. Note that the result of the base64 operation is the actual hash value and shall be used as it is. utf8 is the binary representation of string described in [RFC 3629].

Hash computation example

Let secret key K = "secret-key" and nonce N = "nonce"

utf8(K) = [73 65 63 72 65 74 2D 6B 65 79]
utf8(N) = [6E 6F 6E 63 65]
HMAC-MD5(utf8(SK), utf8(N)) = [1B 5D 80 F0 3B 74 45 D8 C7 37 1F 0F D2 57 22 F7]
hash = 'G12A8Dt0RdjHNx8P0lci9w=='



Error Reference Direct link

Every error includes error and reason fields, - additional fields may be present, specific to a PDU type.

Error PDU body

{
  "error": string,   
  "reason": text,
  // other PDU-specific fields
}

error

Name of the error. This string is intended for use in code.

reason

Describes the error. This text is intended for human use; the text may change in the future and should not be used in code conditioning logic.


Error Types

Errors are categorized into two types:

Error Type

Description

Unclassified

Errors not associated with a particular operation. It may be unknown which operation is triggering it, or potentially affecting overall communication consistency.  


For example, if RTM cannot parse a PDU or cannot parse an action, it has no choice but to return a general system error.

Operation-specific

Errors returned in direct response to a request sent by a client, or unsolicited errors associated with a particular operation.


Unclassified Errors

An unclassified error action has no service or operation components, only 'error' outcome component:

{ 
  "action": "/error", // unclassified
  "body": {
    "error": string, 
    "reason": text
  }
}

The following table lists system errors:

Error

Description

json_parse_error

A request PDU could not be parsed as JSON or exceeds PDU size limit.

invalid_format

Occurs if the action field is missing or is not a string.


Note:  Client that receives an unclassified error should disconnect, and RTM may disconnect.


Operation-specific Errors

The action field of a solicited (response) operation-specific error includes the action field from the request, followed by error outcome. For example, an error to a publish request, rtm/publish, is returned to the client in the response PDU as rtm/publish/error.


The action field of an unsolicited operation-specific error includes the operation it is associated with. For example rtm/subscription/error.


The following table lists operation-specific error names and descriptions.


Error

DescriptionReason

invalid_service

invalid_operation

The service is unknown or the operation is not supported by the service.

See Protocol Data Unit (PDU).

already_subscribed

A subscription with the specified subscription_id is already active.

See Subscribe PDU.

auth_method_not_allowed

The authentication method field in the handshake or authenticate PDU was not “role_secret”.

See Handshake and Authenticate PDUs.

authentication_failed

The hash value in an authenticate PDU was invalid.

See Authenticate PDU.

authorization_denied

You do not have the necessary permissions.

expired_position

The position field in a subscribe PDU is expired.

For more information, see Channels and position Field.

invalid_filter

The fSQL statement in a subscribe PDU was invalid.

invalid_format

fields are missing or invalid.

not_subscribed

You attempted to unsubscribe a non-existent subscription.

out_of_sync

The client is applying too much back-pressure and cannot keep up with the messages from RTM.

See out_of_sync and fast-forward and Channels section.

quota_exceeded

You attempted to perform an operation but your account limits are already at the maximum.



Operation-specific Info

RTM sends info updates when it takes specific actions on behalf of the client. For example, RTM sends an info Subscription PDU when RTM fast-forwards a subscription.

The following table lists info updates and descriptions

Info

Reason

fast_forward

The client is applying too much back-pressure and cannot keep up with the messages from RTM, and the subscription has fast-forwarding enabled .

See out_of_sync and fast-forward


Mini-schema Reference Direct link

The JSON format for a PDU is the concrete transfer syntax, and the PDU specifications used in this reference define a specific JSON pattern. The specifications may include different keywords as placeholders for the types of variable data.


Data Types

The following data types are used for field values or placeholders.

Datatype

Examples

Description

string

"abc", "json-data", ""

Any string that conforms to the JSON string data structure. Limited to 256 bytes.

text

"Hello, world"

Similar to string, but contains text designed for users to read.

int

42, 3

Any non-negative  signed integer value that conforms to the JSON number data structure, without fractions or exponents.

boolean

true, falseBoolean.

value

null, true, false, 42, "Hello, world", [3.14, 2.71], {"key":"value"}

Any value of any valid JSON type.

object

{"key":"value"}

Any json object



Structure

FOO = type or placeholder  

Examples

Description

[FOO]*

[]

[1, 2, 3]

[int]*

An array of zero or more FOO structures  

[FOO]+

[1]

["abc", "def"]

An array of one or more values of the specified type or placeholders. For example, [string()]+ indicates non-empty array of strings.

FOO1|FOO2

true | false

Value can be either of the two listed values or placeholders.

Keywords

Keyword

Example

Description

OPTIONAL

For example, id field may be absent in a request PDU.

The corresponding field may be omitted.