Fix a number of untruths in the documentation about /sync.

Attempts to make the /sync documentation better represent fact as it currently
stands - in particular document the structure of the returned events.
pull/977/head
Richard van der Hoff 9 years ago
parent 3f0262081c
commit 57995a815a

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

@ -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."
},
"txn_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."
}
}
}
}
}

@ -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" }]
} }
} }
} }

@ -4,11 +4,11 @@
"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"
} }
} }
} }

@ -96,8 +96,10 @@ paths:
Updates to rooms. Updates to rooms.
properties: properties:
joined: joined:
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
@ -114,7 +116,7 @@ paths:
description: An event object. description: An event object.
type: object type: object
allOf: allOf:
- $ref: "core-event-schema/event.json" - $ref: "definitions/event.json"
state: state:
title: State title: State
type: object type: object
@ -144,7 +146,7 @@ paths:
allOf: allOf:
- $ref: "definitions/event_batch.json" - $ref: "definitions/event_batch.json"
invited: invited:
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.
@ -171,11 +173,10 @@ paths:
allOf: allOf:
- $ref: "definitions/event_batch.json" - $ref: "definitions/event_batch.json"
archived: archived:
title: Archived title: Archived 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: Archived Room
type: object type: object
@ -192,7 +193,7 @@ paths:
description: An event object. description: An event object.
type: object type: object
allOf: allOf:
- $ref: "core-event-schema/event.json" - $ref: "definitions/event.json"
state: state:
title: State title: State
type: object type: object
@ -276,7 +277,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"]}
} }

@ -30,12 +30,13 @@ 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 a ``prev_content`` to the ``unsigned`` object if the event is
a ``state event`` which gives previous content of that state key. a ``state event`` which gives previous content 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 ``txn_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:

Loading…
Cancel
Save