wholetrans/docs-matrix-spec
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Merge pull request #164 from matrix-org/rav/SPEC-254

Browse source 
Fix /sync documentation, post SPEC-254
This commit is contained in:
Richard van der Hoff 2015-11-20 15:17:55 +00:00
commit d8dd380dfa
7 changed files with 114 additions and 99 deletions
Download patch file Download diff file Expand all files Collapse all files

1
api/client-server/v2_alpha/core-event-schema
View file

@ -1 +0,0 @@
../../../event-schemas/schema/v1/core-event-schema

53
api/client-server/v2_alpha/definitions/event.json Normal file
View file

@ -0,0 +1,53 @@
{
"type": "object",
"title": "Event",
"properties": {
"content": {
"type": "object",
"title": "EventContent",
"description": "The content of this event. The fields in this object will vary depending on the type of event."
},
"origin_server_ts": {
"type": "integer",
"format": "int64",
"description": "Timestamp in milliseconds on originating homeserver when this event was sent."
},
"sender": {
"type": "string",
"description": "The MXID of the user who sent this event."
},
"state_key": {
"type": "string",
"description": "Optional. This key will only be present for state events. A unique key which defines the overwriting semantics for this piece of room state."
},
"type": {
"type": "string",
"description": "The type of event."
},
"unsigned": {
"type": "object",
"title": "Unsigned",
"description": "Information about this event which was not sent by the originating homeserver",
"properties": {
"age": {
"type": "integer",
"format": "int64",
"description": "Time in milliseconds since the event was sent."
},
"prev_content": {
"title": "EventContent",
"type": "object",
"description": "Optional. The previous ``content`` for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
},
"replaces_state": {
"type": "string",
"description": "Optional. The event_id of the previous event for this state. This will be present only for state events appearing in the ``timeline``. If this is not a state event, or there is no previous content, this key will be missing."
},
"transaction_id": {
"type": "string",
"description": "Optional. The transaction ID set when this message was sent. This key will only be present for message events sent by the device calling this API."
}
}
}
}
}

4
api/client-server/v2_alpha/definitions/event_batch.json
View file

@ -5,8 +5,8 @@
"type": "array", "type": "array",
"description": "List of events", "description": "List of events",
"items": { "items": {
"title": "Event", "type": "object",
"type": "object" "allOf": [{"$ref": "event.json" }]
} }
} }
} }

12
api/client-server/v2_alpha/definitions/room_event_batch.json
View file

@ -1,12 +0,0 @@
{
"type": "object",
"properties": {
"events": {
"type": "array",
"description": "List of event ids",
"items": {
"type": "string"
}
}
}
}

6
api/client-server/v2_alpha/definitions/timeline_batch.json
View file

@ -1,14 +1,14 @@
{ {
"type": "object", "type": "object",
"allOf": [{"$ref":"definitions/room_event_batch.json"}], "allOf": [{"$ref":"definitions/event_batch.json"}],
"properties": { "properties": {
"limited": { "limited": {
"type": "boolean", "type": "boolean",
"description": "Whether there are more events on the server" "description": "True if the number of events returned was limited by the ``limit`` on the filter"
}, },
"prev_batch": { "prev_batch": {
"type": "string", "type": "string",
"description": "If the batch was limited then this is a token that can be supplied to the server to retrieve more events" "description": "If the batch was limited then this is a token that can be supplied to the server to retrieve earlier events"
} }
} }
} }

127
api/client-server/v2_alpha/sync.yaml
View file

@ -95,33 +95,26 @@ paths:
description: |- description: |-
Updates to rooms. Updates to rooms.
properties: properties:
joined: join:
title: Joined title: Joined Rooms
type: object type: object
description: |-
The rooms that the user has joined.
additionalProperties: additionalProperties:
title: Joined Room title: Joined Room
type: object type: object
properties: properties:
event_map:
title: EventMap
type: object
description: |-
A map from event ID to events for this room. The
events are referenced from the ``timeline`` and
``state`` keys for this room.
additionalProperties:
title: Event
description: An event object.
type: object
allOf:
- $ref: "core-event-schema/event.json"
state: state:
title: State title: State
type: object type: object
description: |- description: |-
The state updates for the room. Updates to the state, between the time indicated by
the ``since`` parameter, and the start of the
``timeline`` (or all state up to the start of the
``timeline``, if ``since`` is not given, or
``full_state`` is true).
allOf: allOf:
- $ref: "definitions/room_event_batch.json" - $ref: "definitions/event_batch.json"
timeline: timeline:
title: Timeline title: Timeline
type: object type: object
@ -139,8 +132,8 @@ paths:
e.g. typing. e.g. typing.
allOf: allOf:
- $ref: "definitions/event_batch.json" - $ref: "definitions/event_batch.json"
invited: invite:
title: Invited title: Invited Rooms
type: object type: object
description: |- description: |-
The rooms that the user has been invited to. The rooms that the user has been invited to.
@ -166,37 +159,22 @@ paths:
``invite_state``. ``invite_state``.
allOf: allOf:
- $ref: "definitions/event_batch.json" - $ref: "definitions/event_batch.json"
archived: leave:
title: Archived title: Left rooms
type: object type: object
description: |- description: |-
The rooms that the user has left or been banned from. The The rooms that the user has left or been banned from.
entries in the room_map will lack an ``ephemeral`` key.
additionalProperties: additionalProperties:
title: Archived Room title: Left Room
type: object type: object
properties: properties:
event_map:
title: EventMap
type: object
description: |-
A map from event ID to events for this room. The
events are referenced from the ``timeline`` and
``state`` keys for this room.
additionalProperties:
title: Event
description: An event object.
type: object
allOf:
- $ref: "core-event-schema/event.json"
state: state:
title: State title: State
type: object type: object
description: |- description: |-
The state updates for the room up to the point when The state updates for the room up to the start of the timeline.
the user left.
allOf: allOf:
- $ref: "definitions/room_event_batch.json" - $ref: "definitions/event_batch.json"
timeline: timeline:
title: Timeline title: Timeline
type: object type: object
@ -226,47 +204,43 @@ paths:
] ]
}, },
"rooms": { "rooms": {
"joined": { "join": {
"!726s6s6q:example.com": { "!726s6s6q:example.com": {
"event_map": {
"$66697273743031:example.com": {
"sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@alice:example.com",
"content": {"membership": "join"},
"origin_server_ts": 1417731086795
},
"$7365636s6r6432:example.com": {
"sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "join"},
"unsigned": {
"prev_content": {"membership": "invite"}
},
"origin_server_ts": 1417731086795
},
"$74686972643033:example.com": {
"sender": "@alice:example.com",
"type": "m.room.message",
"unsigned": {"age": "124524", "txn_id": "1234"},
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797
}
},
"state": { "state": {
"events": [ "events": [
"$66697273743031:example.com", {
"$7365636s6r6432:example.com" "sender": "@alice:example.com",
"type": "m.room.member",
"state_key": "@alice:example.com",
"content": {"membership": "join"},
"origin_server_ts": 1417731086795,
"event_id": "$66697273743031:example.com"
}
] ]
}, },
"timeline": { "timeline": {
"events": [ "events": [
"$7365636s6r6432:example.com", {
"$74686972643033:example.com" "sender": "@bob:example.com",
"type": "m.room.member",
"state_key": "@bob:example.com",
"content": {"membership": "join"},
"prev_content": {"membership": "invite"},
"origin_server_ts": 1417731086795,
"event_id": "$7365636s6r6432:example.com"
},
{
"sender": "@alice:example.com",
"type": "m.room.message",
"age": 124524,
"txn_id": "1234",
"content": {
"body": "I am a fish",
"msgtype": "m.text"
},
"origin_server_ts": 1417731086797,
"event_id": "$74686972643033:example.com"
}
], ],
"limited": true, "limited": true,
"prev_batch": "t34-23535_0_0" "prev_batch": "t34-23535_0_0"
@ -274,7 +248,6 @@ paths:
"ephemeral": { "ephemeral": {
"events": [ "events": [
{ {
"room_id": "!726s6s6q:example.com",
"type": "m.typing", "type": "m.typing",
"content": {"user_ids": ["@alice:example.com"]} "content": {"user_ids": ["@alice:example.com"]}
} }
@ -282,7 +255,7 @@ paths:
} }
} }
}, },
"invited": { "invite": {
"!696r7674:example.com": { "!696r7674:example.com": {
"invite_state": { "invite_state": {
"events": [ "events": [
@ -302,6 +275,6 @@ paths:
} }
} }
}, },
"archived": {} "leave": {}
} }
} }

10
specification/events.rst
View file

@ -30,12 +30,14 @@ formatted for federation by:
``auth_events``, ``prev_events``, ``hashes``, ``signatures``, ``depth``, ``auth_events``, ``prev_events``, ``hashes``, ``signatures``, ``depth``,
``origin``, ``prev_state``. ``origin``, ``prev_state``.
* Adding an ``age`` to the ``unsigned`` object which gives the time in * Adding an ``age`` to the ``unsigned`` object which gives the time in
milliseconds that has ellapsed since the event was sent. milliseconds that has elapsed since the event was sent.
* Adding a ``prev_content`` to the ``unsigned`` object if the event is * Adding ``prev_content`` and ``prev_sender`` to the ``unsigned`` object if the
a ``state event`` which gives previous content of that state key. event is a ``state event``, which give the previous content and previous
sender of that state key
* Adding a ``redacted_because`` to the ``unsigned`` object if the event was * Adding a ``redacted_because`` to the ``unsigned`` object if the event was
redacted which gives the event that redacted it. redacted which gives the event that redacted it.
* Adding a ``transaction_id`` if the event was sent by the client requesting it. * Adding a ``transaction_id`` to the ``unsigned`` object if the event was sent
by the client requesting it.
Events in responses for APIs with the /v1 prefix are generated from an event Events in responses for APIs with the /v1 prefix are generated from an event
formatted for the /v2 prefix by: formatted for the /v2 prefix by: