Add ObjectData json type and UNKNOWN enum sentinels to objects spec#495
Add ObjectData json type and UNKNOWN enum sentinels to objects spec#495sacOO7 wants to merge 2 commits into
Conversation
sacOO7
force-pushed
the
fix/liveobjects-spec-objectdata-json-type
branch
from
d85dcf3 to
a829907
Compare
Extend the LiveObjects wire types in features.md: - OD2g: add a `json` value field to `ObjectData`, holding a JSON object or array leaf value, sent/received as a JSON-encoded string over the JSON protocol. Update OD2c-OD2f so `json` is listed among the mutually-exclusive value fields, and add the field to the IDL. - OD3a / OD3g: include `json` in the `ObjectData` size calculation; its size is the byte length of its JSON-encoded string representation. This matches both reference implementations (ably-js _getObjectDataSize and ably-java ObjectData.size()). - OOP2a / OMP2a: add a client-side `UNKNOWN` sentinel to the `ObjectOperationAction` and `ObjectsMapSemantics` enums. It has no wire value and is never encoded or sent; decoding an unrecognised action or semantics value yields `UNKNOWN` instead of failing, giving clients a defined way to detect and safely ignore operations they do not understand (e.g. introduced by a newer protocol version). Reflected in the IDL. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
sacOO7
force-pushed
the
fix/liveobjects-spec-objectdata-json-type
branch
from
a829907 to
5ddc271
Compare
|
|
||
| - `(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` |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
Good call — reworded both OOP2a and OMP2a to specify only the behaviour (decode an unrecognised action/semantics without failing; never encode/send it; ignore ops with an unrecognised action) and left the representation to the implementation (sentinel value, nullable field, etc.). I've also dropped UNKNOWN from the wire-ordered enums in the IDL, since adding it there contradicted ably-js, where the numeric wire enum stays pure and 'unknown' lives only on the decoded type. Done in 1230e2c.
| - `(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 |
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
They weren't just trailing spaces — each line was adding json to the "only one set at a time" list. Rather than repeat that across all five value fields, I've hoisted the exclusivity rule into the parent OD2 clause and removed the per-line duplication, so OD2c–OD2g are now back to a single descriptive sentence each and future value fields won't churn every line. Done in 1230e2c.
…jectData value-field exclusivity - OOP2a/OMP2a: specify the decode-without-failing behaviour for unrecognised action/semantics rather than mandating an UNKNOWN enum member; leave the representation to the implementation. Removes the UNKNOWN members from the wire-ordered enums in the IDL, which contradicted the reference (ably-js) wire enums. - OD2: hoist the "at most one value field set at a time" rule into the parent clause and drop the duplicated sentence from OD2c-OD2g. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2 participants
Summary
Extends the LiveObjects wire types in
features.mdwith a newjsonvalue type forObjectData, plusUNKNOWNforward-compatibility sentinels on two wire enums.Changes
ObjectData.jsonvalue field (OD2g)jsonfield holding a JSON object or array leaf value in the object graph.OD2c–OD2fupdated sojsonis included in the set of mutually-exclusive value fields (boolean,bytes,number,string,json).json: String?.ObjectDatasize calculation (OD3a,OD3g)OD3aupdated to includejsonin the summed properties.OD3g: the size of ajsonproperty is the byte length of its JSON-encoded string representation._getObjectDataSize→dataSizeBytes(data.json); ably-javaObjectData.size()→json.toString().byteSize).UNKNOWNenum sentinels (OOP2a,OMP2a)UNKNOWNvalue to bothObjectOperationActionandObjectsMapSemantics.action/semanticsvalue that doesn't map to a known member must decode toUNKNOWNrather than failing.ObjectOperationwith anUNKNOWNaction can be safely ignored and not applied.Validation
npm run lint) — no duplicate spec IDs.🤖 Generated with Claude Code