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

Merge pull request #1834 from matrix-org/travis/misc/event-formats

Browse source 
Represent event format changes more clearly in the spec
This commit is contained in:
Travis Ralston 2019-02-01 13:57:25 -07:00 • committed by GitHub
commit 9923584c24
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
15 changed files with 394 additions and 387 deletions
Download patch file Download diff file Expand all files Collapse all files

6
api/check_examples.py
View file

@ -75,6 +75,12 @@ def check_response(filepath, request, code, response):
filepath, request, code
))
check_schema(filepath, example, schema)
except jsonschema.SchemaError as error:
for suberror in sorted(error.context, key=lambda e: e.schema_path):
print(list(suberror.schema_path), suberror.message, sep=", ")
raise ValueError("Error validating JSON schema for %r %r" % (
request, code
), e)
except Exception as e:
raise ValueError("Error validating JSON schema for %r %r" % (
request, code

29
api/server-server/backfill.yaml
View file

@ -65,22 +65,6 @@ paths:
event(s), up to the given limit.
schema:
$ref: "definitions/transaction.yaml"
# Override the example to show the response of the request a bit better
examples:
application/json: {
"$ref": "examples/transaction.json",
"pdus": [
{
"$ref": "pdu.json",
"room_id": "!SomeRoom:matrix.org",
"event_id": "$abc123:matrix.org"
},
{
"$ref": "pdu.json",
"room_id": "!SomeRoom:matrix.org"
},
]
}
"/get_missing_events/{roomId}":
post:
summary: Retrieves events that the sender is missing
@ -114,14 +98,14 @@ paths:
earliest_events:
type: array
description: |-
The latest events that the sender already has. These are skipped when retrieving
The latest event IDs that the sender already has. These are skipped when retrieving
the previous events of ``latest_events``.
items:
type: string
example: ["$missing_event:example.org"]
latest_events:
type: array
description: The events to retrieve the previous events for.
description: The event IDs to retrieve the previous events for.
items:
type: string
example: ["$event_that_has_the_missing_event_as_a_previous_event:example.org"]
@ -136,13 +120,16 @@ paths:
properties:
events:
type: array
description: The missing events.
description: |-
The missing events. The event format varies depending on the room version - check
the `room version specification`_ for precise event formats.
items:
$ref: definitions/pdu.yaml
type: object
title: PDU
required: ['events']
examples:
application/json: {
"events": [
{"$ref": "examples/pdu.json"}
{"$ref": "examples/minimal_pdu.json"}
]
}

44
api/server-server/definitions/invite_event.yaml
View file

@ -1,4 +1,4 @@
# Copyright 2018 New Vector Ltd
# Copyright 2018-2019 New Vector Ltd
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
@ -13,15 +13,14 @@
# limitations under the License.
type: object
title: Invite Event
description: An invite event
description: |-
An invite event. Note that events have a different format depending on the
room version - check the `room version specification`_ for precise event formats.
allOf:
- $ref: "pdu.yaml"
- type: object
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
type: string
# TODO: Verify/clarify this - it doesn't seem right, given this is a 'regular' invite
description: |-
The matrix ID of the user who sent the original ``m.room.third_party_invite``.
example: "@someone:example.org"
@ -46,7 +45,7 @@ allOf:
type: object
title: Membership Event Content
description: |-
The content of the event, matching what is available in the
The content of the event, matching what is available in the
`Client-Server API`_. Must include a ``membership`` of ``invite``.
example: {"membership": "invite"}
properties:
@ -55,33 +54,10 @@ allOf:
description: The value ``invite``.
example: "invite"
required: ['membership']
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to be invited to the room.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key
- sender
- origin
- origin_server_ts
- type
- content

16
api/server-server/definitions/transaction.yaml
View file

@ -26,12 +26,22 @@ properties:
type: integer
format: int64
description: |-
POSIX timestamp in milliseconds on originating homeserver when this
POSIX timestamp in milliseconds on originating homeserver when this
transaction started.
example: 1532991320875
pdus:
type: array
description: List of persistent updates to rooms. Must not include more than 50 PDUs.
description: |-
List of persistent updates to rooms. Must not include more than 50 PDUs. Note that
events have a different format depending on the room version - check the
`room version specification`_ for precise event formats.
items:
$ref: "pdu.yaml"
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ contained in the transaction. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
properties: []
example:
$ref: "../examples/minimal_pdu.json"
required: ['origin', 'origin_server_ts', 'pdus']

50
api/server-server/event_auth.yaml
View file

@ -20,7 +20,7 @@ host: localhost:8448
schemes:
- https
basePath: /_matrix/federation/v1
consumes:
consumes:
- application/json
produces:
- application/json
@ -58,10 +58,19 @@ paths:
type: array
description: |-
The full set of authorization events that make up the state of
the room, and their authorization events, recursively.
the room, and their authorization events, recursively. Note that
events have a different format depending on the room version -
check the `room version specification`_ for precise event formats.
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ contained in the auth chain. The event format
varies depending on the room version - check the `room version specification`_
for precise event formats.
properties: []
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain']
"/query_auth/{roomId}/{eventId}":
post:
@ -98,10 +107,20 @@ paths:
properties:
auth_chain:
type: array
description: The auth chain (the "remote auth").
description: |-
The auth chain (the "remote auth"). Note that events have a different
format depending on the room version - check the `room version specification`_
for precise event formats.
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ contained in the auth chain. The event format
varies depending on the room version - check the `room version specification`_
for precise event formats.
properties: []
example:
$ref: "examples/minimal_pdu.json"
missing:
type: array
description: |-
@ -142,14 +161,23 @@ paths:
type: array
description: |-
The auth chain the receiver has, and used to determine the auth
chain differences (the "local auth").
chain differences (the "local auth"). Note that events have a different
format depending on the room version - check the `room version specification`_
for precise event formats.
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ contained in the auth chain. The event format
varies depending on the room version - check the `room version specification`_
for precise event formats.
properties: []
example:
$ref: "examples/minimal_pdu.json"
missing:
type: array
description: |-
The list of event IDs that the receiver believes it is missing,
The list of event IDs that the receiver believes it is missing,
after comparing the "remote auth" and "local auth" chains.
items:
type: string

30
api/server-server/events.yaml
View file

@ -59,17 +59,35 @@ paths:
type: array
description: |-
The full set of authorization events that make up the state
of the room, and their authorization events, recursively.
of the room, and their authorization events, recursively. Note that
events have a different format depending on the room version -
check the `room version specification`_ for precise event formats.
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ contained in the auth chain. The event format
varies depending on the room version - check the `room version specification`_
for precise event formats.
properties: []
example:
$ref: "examples/minimal_pdu.json"
pdus:
type: array
description: |-
The fully resolved state of the room at the given event.
The fully resolved state of the room at the given event. Note that
events have a different format depending on the room version -
check the `room version specification`_ for precise event formats.
items:
$ref: "definitions/pdu.yaml"
example: [{"$ref": "examples/pdu.json"}]
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format
varies depending on the room version - check the `room version specification`_
for precise event formats.
properties: []
example:
$ref: "examples/minimal_pdu.json"
required: ['auth_chain', 'pdus']
"/state_ids/{roomId}":
get:

7
api/server-server/examples/minimal_pdu.json Normal file
View file

@ -0,0 +1,7 @@
{
"type": "m.room.minimal_pdu",
"room_id": "!somewhere:example.org",
"content": {
"see_room_version_spec": "The event format changes depending on the room version."
}
}

6
api/server-server/examples/transaction.json
View file

@ -1,5 +1,7 @@
{
"origin": "matrix.org",
"origin_server_ts": 1234567890,
"pdus": [{"$ref": "pdu.json"}]
}
"pdus": [{
"$ref": "minimal_pdu.json"
}]
}

18
api/server-server/invites-v1.yaml
View file

@ -38,6 +38,11 @@ paths:
Servers should prefer to use the v2 API for invites instead of the v1 API. Servers
which receive a v1 invite request must assume that the room version is either ``"1"``
or ``"2"``.
Note that events have a different format depending on the room version - check the
`room version specification`_ for precise event formats. **The request and response
bodies here describe the common event fields in more detail and may be missing other
required fields for a PDU.**
operationId: sendInviteV1
security:
- signedRequest: []
@ -107,9 +112,12 @@ paths:
}
]
example: {
"$ref": "examples/pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{
@ -143,7 +151,8 @@ paths:
200:
description: |-
The event with the invited server's signature added. All other fields of the events
should remain untouched.
should remain untouched. Note that events have a different format depending on the
room version - check the `room version specification`_ for precise event formats.
schema:
type: array
minItems: 2
@ -164,9 +173,12 @@ paths:
200,
{
"event": {
"$ref": "examples/pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{

18
api/server-server/invites-v2.yaml
View file

@ -42,6 +42,11 @@ paths:
This endpoint is preferred over the v1 API as it is more useful for servers. Senders
which receive a 400 or 404 response to this endpoint should retry using the v1
API as the server may be older, if the room version is "1" or "2".
Note that events have a different format depending on the room version - check the
`room version specification`_ for precise event formats. **The request and response
bodies here describe the common event fields in more detail and may be missing other
required fields for a PDU.**
operationId: sendInviteV2
security:
- signedRequest: []
@ -111,9 +116,12 @@ paths:
example: {
"room_version": "2",
"event": {
"$ref": "examples/pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@joe:elsewhere.com",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "invite"
},
@ -146,7 +154,8 @@ paths:
200:
description: |-
The event with the invited server's signature added. All other fields of the events
should remain untouched.
should remain untouched. Note that events have a different format depending on the
room version - check the `room version specification`_ for precise event formats.
schema:
type: object
description: An object containing the signed invite event.
@ -158,9 +167,12 @@ paths:
examples:
application/json: {
"event": {
"$ref": "examples/pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"unsigned": {
"invite_room_state": [
{

284
api/server-server/joins.yaml
View file

@ -61,7 +61,11 @@ paths:
responses:
200:
description: |-
A template to be used for the rest of the `Joining Rooms`_ handshake.
A template to be used for the rest of the `Joining Rooms`_ handshake. Note that
events have a different format depending on the room version - check the
`room version specification`_ for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
schema:
type: object
properties:
@ -72,96 +76,65 @@ paths:
the room version is assumed to be either "1" or "2".
example: "2"
event:
allOf:
- $ref: "definitions/unsigned_pdu.yaml"
- description: |-
An unsigned template event.
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the `room version specification`_
for precise event formats.
type: object
title: Event Template
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
membership:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value ``join``.
example: "join"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to join the room. This should normally be the
``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
events.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key
description: The value ``join``.
example: "join"
required: ['membership']
required:
- state_key
- origin
- origin_server_ts
- type
- content
- sender
examples:
application/json: {
"room_version": "2",
"event": {
"$ref": "examples/unsigned_pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join"
},
"auth_events": [
["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
]
}
}
}
400:
@ -193,7 +166,12 @@ paths:
summary: Submit a signed join event to a resident server
description: |-
Submits a signed join event to the resident server for it
to accept it into the room's graph.
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
the `room version specification`_ for precise event formats.
**The request and response body here describes the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendJoin
security:
- signedRequest: []
@ -215,81 +193,54 @@ paths:
type: object
required: true
schema:
allOf:
- $ref: "definitions/pdu.yaml"
- type: object
type: object
properties:
sender:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
membership:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
origin:
type: string
description: The name of the joining homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the joining homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the joining member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "join"}
properties:
membership:
type: string
description: The value ``join``.
example: "join"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to join the room.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key
description: The value ``join``.
example: "join"
required: ['membership']
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
example: {
"$ref": "examples/pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "join"
}
@ -315,25 +266,44 @@ paths:
description: The resident server's DNS name.
auth_chain:
type: array
description: The auth chain.
description: |-
The auth chain. Note that events have a different format depending on
the room version - check the `room version specification`_ for precise
event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ that make up the auth chain. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
$ref: "definitions/pdu.yaml"
type: object
properties: []
example:
$ref: "examples/minimal_pdu.json"
state:
type: array
description: The room state.
description: |-
The room state. The event format varies depending on the room version -
check the `room version specification`_ for precise event formats.
items:
type: object
title: PDU
description: |-
The `PDUs <#pdus>`_ for the fully resolved state of the room. The event format varies depending
on the room version - check the `room version specification`_ for precise event formats.
schema:
$ref: "definitions/pdu.yaml"
type: object
properties: []
example:
$ref: "examples/minimal_pdu.json"
required: ["auth_chain", "state", "origin"]
examples:
application/json: [
200,
{
"origin": "matrix.org",
"auth_chain": [{"$ref": "examples/pdu.json"}],
"state": [{"$ref": "examples/pdu.json"}]
"auth_chain": [{"$ref": "examples/minimal_pdu.json"}],
"state": [{"$ref": "examples/minimal_pdu.json"}]
}
]

254
api/server-server/leaving.yaml
View file

@ -52,7 +52,11 @@ paths:
responses:
200:
description: |-
A template to be used to call ``/send_leave``.
A template to be used to call ``/send_leave``. Note that
events have a different format depending on the room version - check the
`room version specification`_ for precise event formats. **The response body
here describes the common event fields in more detail and may be missing other
required fields for a PDU.**
schema:
schema:
type: object
@ -64,92 +68,65 @@ paths:
the room version is assumed to be either "1" or "2".
example: "2"
event:
allOf:
- $ref: "definitions/unsigned_pdu.yaml"
- description: |-
An unsigned template event.
description: |-
An unsigned template event. Note that events have a different format
depending on the room version - check the `room version specification`_
for precise event formats.
type: object
title: Event Template
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
membership:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the resident homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the resident homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
membership:
type: string
description: The value ``leave``.
example: "leave"
required: ['membership']
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to leave the room. This should normally be the
``m.room.create``, ``m.room.power_levels``, and ``m.room.join_rules``
events.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key
description: The value ``leave``.
example: "leave"
required: ['membership']
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- content
examples:
application/json: {
"room_version": "2",
"event": {
"$ref": "examples/unsigned_pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
},
"auth_events": [
["$room_cre4te_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_j0in_rul3s_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}],
["$room_p0wer_l3vels_3vent:matrix.org", {"sha256": "abase64encodedsha256hashshouldbe43byteslong"}]
]
}
}
}
403:
@ -167,7 +144,12 @@ paths:
summary: Submit a signed leave event to a resident server
description: |-
Submits a signed leave event to the resident server for it
to accept it into the room's graph.
to accept it into the room's graph. Note that events have
a different format depending on the room version - check
the `room version specification`_ for precise event formats.
**The request and response body here describes the common
event fields in more detail and may be missing other required
fields for a PDU.**
operationId: sendLeave
security:
- signedRequest: []
@ -189,81 +171,59 @@ paths:
type: object
required: true
schema:
allOf:
- $ref: "definitions/pdu.yaml"
- type: object
type: object
properties:
sender:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
# Note: we override a bunch of parameters to change their descriptions
sender:
membership:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
origin:
type: string
description: The name of the leaving homeserver.
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: A timestamp added by the leaving homeserver.
example: 1234567890
type:
type: string
description: The value ``m.room.member``.
example: "m.room.member"
state_key:
type: string
description: The user ID of the leaving member.
example: "@someone:example.org"
content:
type: object
title: Membership Event Content
description: The content of the event.
example: {"membership": "leave"}
properties:
membership:
type: string
description: The value ``leave``.
example: "leave"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
auth_events:
type: array
description: |-
An event reference list containing the authorization events that would
allow the member to leave the room.
items:
type: array
maxItems: 2
minItems: 2
items:
- type: string
title: Event ID
example: "$abc123:matrix.org"
- type: object
title: Event Hash
example: {
"sha256": "abase64encodedsha256hashshouldbe43byteslong"
}
properties:
sha256:
type: string
description: The event hash.
example: abase64encodedsha256hashshouldbe43byteslong
required: ['sha256']
redacts:
type: string
description: Not used.
required:
# Every other field is already flagged as required by the $ref
- state_key
description: The value ``leave``.
example: "leave"
required: ['membership']
depth:
type: integer
description: This field must be present but is ignored; it may be 0.
example: 12
required:
- state_key
- sender
- origin
- origin_server_ts
- type
- depth
- content
example: {
"$ref": "examples/pdu.json",
"$ref": "examples/minimal_pdu.json",
"type": "m.room.member",
"state_key": "@someone:example.org",
"origin": "example.org",
"origin_server_ts": 1549041175876,
"sender": "@someone:example.org",
"content": {
"membership": "leave"
}

2
api/server-server/third_party_invite.yaml
View file

@ -85,6 +85,7 @@ paths:
third_party_invite:
type: object
description: The third party invite
title: Third Party Invite
properties:
display_name:
type: string
@ -97,6 +98,7 @@ paths:
description: |-
A block of content which has been signed, which servers can use to
verify the event.
title: Invite Signatures
properties:
signatures:
type: object

3
api/server-server/transactions.yaml
View file

@ -37,6 +37,9 @@ paths:
The sending server must wait and retry for a 200 OK response before sending a
transaction with a different ``txnId`` to the receiving server.
Note that events have a different format depending on the room version - check
the `room version specification`_ for precise event formats.
operationId: sendTransaction
security:
- signedRequest: []

14
specification/client_server_api.rst
View file

@ -1267,7 +1267,21 @@ point in time::
[E0]->[E1]->[E2]->[E3]->[E4]->[E5]
.. WARNING::
The format of events can change depending on room version. Check the
`room version specification`_ for specific details on what to expect for
event formats. Examples contained within the client-server specification
are expected to be compatible with all specified room versions, however
some differences may still apply.
For this version of the specification, clients only need to worry about
the event ID format being different depending on room version. Clients
should not be parsing the event ID, and instead be treating it as an
opaque string. No changes should be required to support the currently
available room versions.
.. _`room version specification`: ../index.html#room-versions
Types of room events
~~~~~~~~~~~~~~~~~~~~