Improve upon the transaction schema and examples

Reduces data duplication and makes the objects more reusable for other areas of the spec
pull/1406/head
Travis Ralston 6 years ago
parent 374ec00046
commit e5da1e1741

@ -1,28 +0,0 @@
# Copyright 2018 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.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Transaction
description: Transaction
example:
$ref: "../examples/full_transaction.json"
allOf:
- $ref: "transaction.yaml"
- type: object
properties:
edus:
type: array
description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
items:
$ref: "edu.yaml"
required: ['origin', 'origin_server_ts', 'pdus']

@ -16,131 +16,37 @@ title: Persistent Data Unit
description: A persistent data unit (event) description: A persistent data unit (event)
example: example:
$ref: "../examples/pdu.json" $ref: "../examples/pdu.json"
properties: allOf:
room_id: - $ref: "unsigned_pdu.yaml"
type: string - type: object
description: Room identifier
example: "!abc123:matrix.org"
sender:
type: string
description: The ID of the user sending the event
example: "@someone:matrix.org"
origin:
type: string
description: The ``server_name`` of the homeserver that created this event
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: Timestamp in milliseconds on origin homeserver when this event was created.
example: 1234567890
type:
type: string
description: Event type
required: true
example: "m.room.message"
state_key:
type: string
description: |-
If this key is present, the event is a state event, and it will replace previous events
with the same ``type`` and ``state_key`` in the room state.
example: "my_key"
content:
type: object
description: The content of the event
prev_events:
type: array
description: |-
Event IDs and hashes of the most recent events in the room that the homeserver was aware
of when it made this event
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']
depth:
type: integer
description: The maximum depth of the ``prev_events``, plus one
example: 12
auth_events:
type: array
description: Event IDs and hashes for the "auth events" of this event
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']
hashes:
type: object
title: Event Hash
description: Hashes of the PDU, following the algorithm specified in `Signing Events`_
example: {
"sha256": "thishashcoversallfieldsincasethisisredacted"
}
properties: properties:
sha256: hashes:
type: string type: object
description: The hash title: Event Hash
example: thishashcoversallfieldsincasethisisredacted description: Hashes of the PDU, following the algorithm specified in `Signing Events`_
required: ['sha256'] example: {
signatures: "sha256": "thishashcoversallfieldsincasethisisredacted"
type: object }
description: |- properties:
Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_ sha256:
example: { type: string
"example.com": { description: The hash
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" example: thishashcoversallfieldsincasethisisredacted
} required: ['sha256']
} signatures:
additionalProperties: type: object
type: object description: |-
title: Server Signatures Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_
additionalProperties: example: {
type: string "example.com": {
redacts: "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
type: string }
description: For redaction events, the ID of the event being redacted }
example: "$def456:matrix.org" additionalProperties:
unsigned: type: object
type: object title: Server Signatures
description: Additional data added by the origin server but not covered by the ``signatures`` additionalProperties:
required: type: string
- room_id required:
- sender - hashes
- origin - signatures
- origin_server_ts
- type
- content
- prev_events
- depth
- auth_events
- hashes
- signatures

@ -0,0 +1,119 @@
# Copyright 2018 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.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
type: object
title: Unsigned Persistent Data Unit
description: An unsigned persistent data unit (event)
example:
$ref: "../examples/unsigned_pdu.json"
properties:
room_id:
type: string
description: Room identifier
example: "!abc123:matrix.org"
sender:
type: string
description: The ID of the user sending the event
example: "@someone:matrix.org"
origin:
type: string
description: The ``server_name`` of the homeserver that created this event
example: "matrix.org"
origin_server_ts:
type: integer
format: int64
description: Timestamp in milliseconds on origin homeserver when this event was created.
example: 1234567890
type:
type: string
description: Event type
required: true
example: "m.room.message"
state_key:
type: string
description: |-
If this key is present, the event is a state event, and it will replace previous events
with the same ``type`` and ``state_key`` in the room state.
example: "my_key"
content:
type: object
description: The content of the event
example: {"key": "value"}
prev_events:
type: array
description: |-
Event IDs and hashes of the most recent events in the room that the homeserver was aware
of when it made this event
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']
depth:
type: integer
description: The maximum depth of the ``prev_events``, plus one
example: 12
auth_events:
type: array
description: Event IDs and hashes for the "auth events" of this event
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: For redaction events, the ID of the event being redacted
example: "$def456:matrix.org"
unsigned:
type: object
description: Additional data added by the origin server but not covered by the ``signatures``
example: {"key": "value"}
required:
- room_id
- sender
- origin
- origin_server_ts
- type
- content
- prev_events
- depth
- auth_events

@ -1,6 +0,0 @@
{
"origin": "matrix.org",
"origin_server_ts": 1234567890,
"pdus": [{"$ref": "pdu.json"}],
"edus": [{"$ref": "edu.json"}]
}

@ -1,16 +1,5 @@
{ {
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org", "$ref": "unsigned_pdu.json",
"sender": "@alice:example.com",
"origin": "example.com",
"event_id": "$a4ecee13e2accdadf56c1025:example.com",
"origin_server_ts": 1404838188000,
"type": "m.room.message",
"prev_events": [
[
"$af232176:example.org",
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
]
],
"hashes": { "hashes": {
"sha256": "thishashcoversallfieldsincasethisisredacted" "sha256": "thishashcoversallfieldsincasethisisredacted"
}, },
@ -18,8 +7,5 @@
"example.com": { "example.com": {
"ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus"
} }
},
"content": {
"key": "value"
} }
} }

@ -0,0 +1,17 @@
{
"room_id": "!UcYsUzyxTGDxLBEvLy:example.org",
"sender": "@alice:example.com",
"origin": "example.com",
"event_id": "$a4ecee13e2accdadf56c1025:example.com",
"origin_server_ts": 1404838188000,
"type": "m.room.message",
"prev_events": [
[
"$af232176:example.org",
{"sha256": "abase64encodedsha256hashshouldbe43byteslong"}
]
],
"content": {
"key": "value"
}
}

@ -43,8 +43,21 @@ paths:
- in: body - in: body
name: body name: body
type: object type: object
required: true
schema: schema:
$ref: "definitions/full_transaction.yaml" allOf:
- $ref: "definitions/transaction.yaml"
- type: object
properties:
edus:
type: array
description: List of ephemeral messages. May be omitted if there are no ephemeral messages to be sent.
items:
$ref: "definitions/edu.yaml"
example: {
"$ref": "examples/transaction.json",
"edus": [{"$ref": "edu.json"}] # Relative to the examples directory
}
responses: responses:
200: 200:
# TODO: Spec this (and figure out what it is) # TODO: Spec this (and figure out what it is)

@ -138,6 +138,10 @@ def inherit_parents(obj):
Recurse through the 'allOf' declarations in the object Recurse through the 'allOf' declarations in the object
""" """
logger.debug("inherit_parents %r" % obj) logger.debug("inherit_parents %r" % obj)
if isinstance(obj, list):
return [inherit_parents(obj[i]) for i in range(0, len(obj))]
parents = obj.get("allOf", []) parents = obj.get("allOf", [])
if not parents: if not parents:
return obj return obj
@ -379,6 +383,10 @@ def get_tables_for_response(schema):
def get_example_for_schema(schema): def get_example_for_schema(schema):
"""Returns a python object representing a suitable example for this object""" """Returns a python object representing a suitable example for this object"""
schema = inherit_parents(schema) schema = inherit_parents(schema)
if isinstance(schema, list):
return [get_example_for_schema(v) for v in schema]
if 'example' in schema: if 'example' in schema:
example = schema['example'] example = schema['example']
return example return example
@ -398,7 +406,10 @@ def get_example_for_schema(schema):
if proptype == 'array': if proptype == 'array':
if 'items' not in schema: if 'items' not in schema:
raise Exception('"array" property has neither items nor example') raise Exception('"array" property has neither items nor example')
return [get_example_for_schema(schema['items'])] result = get_example_for_schema(schema['items'])
if isinstance(result, list):
return result
return [result]
if proptype == 'integer': if proptype == 'integer':
return 0 return 0

Loading…
Cancel
Save