Skip to content

Add ObjectData json type and UNKNOWN enum sentinels to objects spec #495

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sacOO7 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Add ObjectData json type and UNKNOWN enum sentinels to objects spec #495

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 12 additions & 5 deletions specifications/features.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1311,6 +1311,7 @@ The core SDK provides an API for wrapper SDKs to supply Ably with analytics info

- `(OOP1)` An `ObjectOperation` describes an operation to be applied to an object on a channel
- `(OOP2)` `ObjectOperationAction` enum has the following values in order from zero: `MAP_CREATE`, `MAP_SET`, `MAP_REMOVE`, `COUNTER_CREATE`, `COUNTER_INC`, `OBJECT_DELETE`, `MAP_CLEAR`
- `(OOP2a)` The enum additionally has an `UNKNOWN` value, which has no wire representation. When decoding, an `action` that does not map to any of the wire-ordered members above must be decoded as `UNKNOWN` rather than failing. The client library must never encode or send `UNKNOWN`, and must ignore (not apply) any `ObjectOperation` whose `action` is `UNKNOWN`

@ttypic ttypic Jun 19, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it can be implemented differently (for example, as a nullable field). The main point is that if we receive an unknown value, we shouldn’t fail. Anyway, we agreed that we don’t want to add spec points that contradict the js implementation.

- `(OOP3)` The attributes available in an `ObjectOperation` are:
- `(OOP3a)` `action` `ObjectOperationAction` enum - defines the operation to be applied to the object
- `(OOP3b)` `objectId` string - the object ID of the object on a channel to which the operation should be applied
Expand Down Expand Up @@ -1474,6 +1475,7 @@ The core SDK provides an API for wrapper SDKs to supply Ably with analytics info

- `(OMP1)` An `ObjectsMap` object represents a map of key-value pairs
- `(OMP2)` `ObjectsMapSemantics` enum has the following values in order from zero: `LWW`
- `(OMP2a)` The enum additionally has an `UNKNOWN` value, which has no wire representation. When decoding, a `semantics` value that does not map to any of the wire-ordered members above must be decoded as `UNKNOWN` rather than failing. The client library must never encode or send `UNKNOWN`
- `(OMP3)` The attributes available in an `ObjectsMap` are:
- `(OMP3a)` `semantics` `ObjectsMapSemantics` enum - the conflict-resolution semantics used by the map object
- `(OMP3b)` `entries` `Dict<String, ObjectsMapEntry>` - the map entries, indexed by key
Expand Down Expand Up @@ -1512,16 +1514,18 @@ The core SDK provides an API for wrapper SDKs to supply Ably with analytics info
- `(OD2)` The attributes available in an `ObjectData` are:
- `(OD2a)` `objectId` string - a reference to another object
- `(OD2b)` `encoding` string - may be set by the client library to indicate that value in `string` field have an encoding
- `(OD2c)` `boolean` boolean - a primitive boolean leaf value in the object graph. Only one of the value fields - `boolean`, `bytes`, `number` or `string` - must be set at a time
- `(OD2d)` `bytes` binary \| string - a primitive binary leaf value in the object graph. It is sent to and received from the server as a Base64-encoded string when using the JSON protocol. Only one of the value fields - `boolean`, `bytes`, `number` or `string` - must be set at a time
- `(OD2e)` `number` number - a primitive number leaf value in the object graph. Only one of the value fields - `boolean`, `bytes`, `number` or `string` - must be set at a time
- `(OD2f)` `string` string - a primitive string leaf value in the object graph. Only one of the value fields - `boolean`, `bytes`, `number` or `string` - must be set at a time
- `(OD2c)` `boolean` boolean - a primitive boolean leaf value in the object graph. Only one of the value fields - `boolean`, `bytes`, `number`, `string` or `json` - must be set at a time

@ttypic ttypic Jun 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

weird, don't see any changes to the (OD2c-f), if it's just trailing spaces could we revert them to keep the git history cleaner?

- `(OD2d)` `bytes` binary \| string - a primitive binary leaf value in the object graph. It is sent to and received from the server as a Base64-encoded string when using the JSON protocol. Only one of the value fields - `boolean`, `bytes`, `number`, `string` or `json` - must be set at a time
- `(OD2e)` `number` number - a primitive number leaf value in the object graph. Only one of the value fields - `boolean`, `bytes`, `number`, `string` or `json` - must be set at a time
- `(OD2f)` `string` string - a primitive string leaf value in the object graph. Only one of the value fields - `boolean`, `bytes`, `number`, `string` or `json` - must be set at a time
- `(OD2g)` `json` JsonObject \| JsonArray - a primitive JSON leaf value (an object or array) in the object graph. It is sent to and received from the server as a JSON-encoded string when using the JSON protocol. Only one of the value fields - `boolean`, `bytes`, `number`, `string` or `json` - must be set at a time
- `(OD3)` The size of the `ObjectData` is calculated as follows:
- `(OD3a)` The size is the sum of the sizes of the `boolean`, `bytes`, `number`, and `string` properties
- `(OD3a)` The size is the sum of the sizes of the `boolean`, `bytes`, `number`, `string`, and `json` properties
- `(OD3b)` If set, the size of a `boolean` property is 1
- `(OD3c)` If set, the size of a `bytes` property is its size in bytes (of the actual binary, not the base64 representation, regardless of whether the binary protocol is in use)
- `(OD3d)` If set, the size of a `number` property is 8
- `(OD3e)` If set, the size of a `string` property is its length
- `(OD3g)` If set, the size of a `json` property is the byte length of its JSON-encoded string representation
- `(OD3f)` The size of a `null` or omitted property is zero
- `(OD4)` `ObjectData` encoding:
- `(OD4a)` Payloads must be booleans, binary, numbers, strings, or JSON-encodable objects or arrays. Any other data type must not be permitted and result in an error with code 40013
Expand Down Expand Up @@ -2488,9 +2492,11 @@ Each type, method, and attribute is labelled with the name of one or more clause
COUNTER_INC // OOP2
OBJECT_DELETE // OOP2
MAP_CLEAR // OOP2
UNKNOWN // OOP2a, client-side sentinel, never sent/received over the wire

enum ObjectsMapSemantics: // OMP2, internal
LWW // OMP2
UNKNOWN // OMP2a, client-side sentinel, never sent/received over the wire

enum AnnotationAction: // TAN2b
ANNOTATION_CREATE
Expand Down Expand Up @@ -2628,6 +2634,7 @@ Each type, method, and attribute is labelled with the name of one or more clause
bytes: Binary? | String? // OD2d
number: Number? // OD2e
string: String? // OD2f
json: String? // OD2g

class Annotation // TAN*
+fromEncoded(JsonObject, ChannelOptions?) -> Annotation // TAN3
Expand Down
Loading