From 374ec00046d0366c88a8e6cfd40c70c9624ed264 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 11 Jul 2018 16:51:24 -0600 Subject: [PATCH 01/10] Convert things that mention "Transaction" to swagger There's two kinds of transactions currently: one with EDUs and one without. The one with EDUs is only used on /send, however the schema is still somewhat worth splitting out for simplicity. The examples are brought apart to make them slightly more reusable for when they get dumped into the relevant sections of the spec (see TODO in server_server_api.rst) Further, the Transactions stuff introduces tuples to the spec. The units.py has been updated to support this. --- api/server-server/definitions/edu.yaml | 37 +++++ .../definitions/full_transaction.yaml | 28 ++++ api/server-server/definitions/pdu.yaml | 146 ++++++++++++++++++ .../definitions/transaction.yaml | 35 +++++ api/server-server/events.yaml | 118 ++++++++++++++ api/server-server/examples/edu.json | 8 + .../examples/full_transaction.json | 6 + api/server-server/examples/pdu.json | 25 +++ api/server-server/examples/transaction.json | 5 + api/server-server/transactions.yaml | 51 ++++++ scripts/templating/matrix_templates/units.py | 25 ++- specification/server_server_api.rst | 55 +------ 12 files changed, 485 insertions(+), 54 deletions(-) create mode 100644 api/server-server/definitions/edu.yaml create mode 100644 api/server-server/definitions/full_transaction.yaml create mode 100644 api/server-server/definitions/pdu.yaml create mode 100644 api/server-server/definitions/transaction.yaml create mode 100644 api/server-server/events.yaml create mode 100644 api/server-server/examples/edu.json create mode 100644 api/server-server/examples/full_transaction.json create mode 100644 api/server-server/examples/pdu.json create mode 100644 api/server-server/examples/transaction.json create mode 100644 api/server-server/transactions.yaml diff --git a/api/server-server/definitions/edu.yaml b/api/server-server/definitions/edu.yaml new file mode 100644 index 00000000..4597ca62 --- /dev/null +++ b/api/server-server/definitions/edu.yaml @@ -0,0 +1,37 @@ +# 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. + +# TODO: Address any concerns about this being inaccurate (flagged as such in the EDUs section) + +type: object +title: Ephemeral Data Unit +description: An ephemeral data unit +example: + $ref: "../examples/edu.json" +properties: + edu_type: + type: string + description: The type of ephemeral message + example: "!abc123:matrix.org" + origin: + type: string + description: The server name sending the ephemeral message + example: "matrix.org" + destination: + type: string + description: The server name receiving the ephemeral message + example: "elsewhere.com" + content: + type: object + description: The content of the ephemeral message diff --git a/api/server-server/definitions/full_transaction.yaml b/api/server-server/definitions/full_transaction.yaml new file mode 100644 index 00000000..39250433 --- /dev/null +++ b/api/server-server/definitions/full_transaction.yaml @@ -0,0 +1,28 @@ +# 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'] \ No newline at end of file diff --git a/api/server-server/definitions/pdu.yaml b/api/server-server/definitions/pdu.yaml new file mode 100644 index 00000000..b3f25ccf --- /dev/null +++ b/api/server-server/definitions/pdu.yaml @@ -0,0 +1,146 @@ +# 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: Persistent Data Unit +description: A persistent data unit (event) +example: + $ref: "../examples/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 + 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: + sha256: + type: string + description: The hash + example: thishashcoversallfieldsincasethisisredacted + required: ['sha256'] + signatures: + type: object + description: |- + Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_ + example: { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } + } + additionalProperties: + type: object + title: Server Signatures + additionalProperties: + type: string + 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`` +required: + - room_id + - sender + - origin + - origin_server_ts + - type + - content + - prev_events + - depth + - auth_events + - hashes + - signatures diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml new file mode 100644 index 00000000..630d2ba3 --- /dev/null +++ b/api/server-server/definitions/transaction.yaml @@ -0,0 +1,35 @@ +# 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/transaction.json" +properties: + origin: + type: string + description: |- + The ``server_name`` of hoemserver sending this transaction + example: "example.org" + origin_server_ts: + type: integer + format: int64 + description: Timestamp in milliseconds on originating homeserver when this transaction started + example: 1234567890 + pdus: + type: array + description: List of persistent updates to rooms + items: + $ref: "pdu.yaml" +required: ['origin', 'origin_server_ts', 'pdus'] \ No newline at end of file diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml new file mode 100644 index 00000000..055883c2 --- /dev/null +++ b/api/server-server/events.yaml @@ -0,0 +1,118 @@ +# 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. + +swagger: '2.0' +info: + title: "Matrix Federation Events API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +paths: + "/state/{roomId}": + get: + summary: Get all the state of a given room + description: |- + Retrieves a snapshot of the entire current state of the given room. + operationId: getRoomState + parameters: + - in: path + name: roomId + type: string + description: The room ID to get state for + required: true + x-example: "!abc123:matrix.org" + responses: + 200: + description: The room state for the room (kept under ``pdus``) + schema: + $ref: "definitions/transaction.yaml" + "/event/{eventId}": + get: + summary: Get a single event + description: |- + Retrieves a single event + operationId: getEvent + parameters: + - in: path + name: eventId + type: string + description: The event ID to get + required: true + x-example: "$abc123:matrix.org" + responses: + 200: + description: A transaction containing a single PDU which is the event requested + schema: + $ref: "definitions/transaction.yaml" + "/backfill/{roomId}": + get: + summary: Retrieves the events which precede the given event + description: |- + Retreives a sliding-window history of previous PDUs that occurred on the given room. + Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it + are retrived, up to the total number given by the ``limit``. + operationId: backfillRoom + parameters: + - in: path + name: roomId + type: string + description: The room ID to backfill + required: true + x-example: "!abc123:matrix.org" + - in: query + name: v + type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it + description: The event ID to backfill from + required: true + x-example: "$abc123:matrix.org" + - in: query + name: limit + type: integer + description: The maximum number of events to retrieve + required: true # TODO: Verify + x-example: 10 + responses: + 200: + description: A transaction containing the PDUs that preceded the given event(s). + schema: + $ref: "definitions/transaction.yaml" + "/pull": + get: + summary: Stream events later than a given point in history + description: |- + Retrieves all of the transactions later than any version given by the ``v`` arguments. + operationId: pull + parameters: + - in: query + name: v + type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it + description: The event ID to backfill from + required: true + x-example: "$abc123:matrix.org" + - in: query + name: origin + type: string + description: The origin # TODO: What is this actually? + required: true # TODO: Verify + x-example: "matrix.org" + responses: + 200: + # TODO: This could do with a better description + description: A transaction containing multiple PDUs + schema: + $ref: "definitions/transaction.yaml" \ No newline at end of file diff --git a/api/server-server/examples/edu.json b/api/server-server/examples/edu.json new file mode 100644 index 00000000..95a7b55d --- /dev/null +++ b/api/server-server/examples/edu.json @@ -0,0 +1,8 @@ +{ + "edu_type": "m.presence", + "origin": "blue", + "destination": "orange", + "content": { + "key": "value" + } +} \ No newline at end of file diff --git a/api/server-server/examples/full_transaction.json b/api/server-server/examples/full_transaction.json new file mode 100644 index 00000000..c453d6ed --- /dev/null +++ b/api/server-server/examples/full_transaction.json @@ -0,0 +1,6 @@ +{ + "origin": "matrix.org", + "origin_server_ts": 1234567890, + "pdus": [{"$ref": "pdu.json"}], + "edus": [{"$ref": "edu.json"}] +} \ No newline at end of file diff --git a/api/server-server/examples/pdu.json b/api/server-server/examples/pdu.json new file mode 100644 index 00000000..531f4a37 --- /dev/null +++ b/api/server-server/examples/pdu.json @@ -0,0 +1,25 @@ +{ + "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"} + ] + ], + "hashes": { + "sha256": "thishashcoversallfieldsincasethisisredacted" + }, + "signatures": { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } + }, + "content": { + "key": "value" + } +} \ No newline at end of file diff --git a/api/server-server/examples/transaction.json b/api/server-server/examples/transaction.json new file mode 100644 index 00000000..bd8ac3dc --- /dev/null +++ b/api/server-server/examples/transaction.json @@ -0,0 +1,5 @@ +{ + "origin": "matrix.org", + "origin_server_ts": 1234567890, + "pdus": [{"$ref": "pdu.json"}] +} \ No newline at end of file diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml new file mode 100644 index 00000000..389eecc7 --- /dev/null +++ b/api/server-server/transactions.yaml @@ -0,0 +1,51 @@ +# 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. + +swagger: '2.0' +info: + title: "Matrix Federation Transaction API" + version: "1.0.0" +host: localhost:8448 +schemes: + - https +basePath: /_matrix/federation/v1 +produces: + - application/json +paths: + "/send/{txnId}": + put: + summary: Send a transaction + description: |- + Push messages representing live activity to another server. The destination name + will be set to that of the receiving server itself. Each embedded PDU in the + transaction body will be processed. + operationId: sendTransaction + parameters: + - in: path + name: txnId + type: string + # TODO: "Overrides any ID given in the JSON body" - What does this mean? + description: |- + The transaction ID. Overrides any ID given in the JSON body. + required: true + x-example: TODO # No examples in the spec so far + - in: body + name: body + type: object + schema: + $ref: "definitions/full_transaction.yaml" + responses: + 200: + # TODO: Spec this (and figure out what it is) + description: TODO diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index dac183d1..7819dbf9 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -292,10 +292,19 @@ def process_data_type(prop, required=False, enforce_title=True): is_object = True elif prop_type == "array": - nested = process_data_type(prop["items"]) - prop_title = "[%s]" % nested["title"] - tables = nested["tables"] - enum_desc = nested["enum_desc"] + items = prop["items"] + if isinstance(items, list): + prop_title = "[" + for i in items: + nested = process_data_type(i) + tables.extend(nested['tables']) + prop_title = "%s%s, " % (prop_title, nested['title']) + prop_title = prop_title[:-2] + "]" + else: + nested = process_data_type(prop["items"]) + prop_title = "[%s]" % nested["title"] + tables = nested["tables"] + enum_desc = nested["enum_desc"] else: prop_title = prop_type @@ -505,7 +514,13 @@ class MatrixUnits(Units): if val_type == "array": items = param.get("items") if items: - val_type = "[%s]" % items.get("type") + if isinstance(items, list): + val_type = "[" + for i in items: + val_type += "%s, " % items.get("type") + val_type = val_type[:-2] + "]" + else: + val_type = "[%s]" % items.get("type") if param.get("enum"): val_type = "enum" diff --git a/specification/server_server_api.rst b/specification/server_server_api.rst index f2b3204a..7b66584d 100644 --- a/specification/server_server_api.rst +++ b/specification/server_server_api.rst @@ -360,6 +360,10 @@ the destination. PDU Fields ~~~~~~~~~~ +.. TODO-spec + + Figure out how to embed swagger definitions in here (or improve the section) + ==================== ================== ======================================= Key Type Description ==================== ================== ======================================= @@ -749,57 +753,10 @@ All these URLs are name-spaced within a prefix of:: /_matrix/federation/v1/... -For active pushing of messages representing live activity "as it happens":: - PUT .../send// - Body: JSON encoding of a single Transaction - Response: TODO-doc - -The transaction_id path argument will override any ID given in the JSON body. -The destination name will be set to that of the receiving server itself. Each -embedded PDU in the transaction body will be processed. - - -To fetch all the state of a given room:: - - GET .../state// - Response: JSON encoding of a single Transaction containing multiple PDUs - -Retrieves a snapshot of the entire current state of the given room. The -response will contain a single Transaction, inside which will be a list of PDUs -that encode the state. - - -To fetch a particular event:: - - GET .../event// - Response: JSON encoding of a partial Transaction containing the event - -Retrieves a single event. The response will contain a partial Transaction, -having just the ``origin``, ``origin_server_ts`` and ``pdus`` fields; the -event will be encoded as the only PDU in the ``pdus`` list. - - -To backfill events on a given room:: - - GET .../backfill// - Query args: v, limit - Response: JSON encoding of a single Transaction containing multiple PDUs - -Retrieves a sliding-window history of previous PDUs that occurred on the given -room. Starting from the PDU ID(s) given in the "v" argument, the PDUs that -preceded it are retrieved, up to a total number given by the "limit" argument. - - -To stream all the events:: - - GET .../pull/ - Query args: origin, v - Response: JSON encoding of a single Transaction consisting of multiple PDUs - -Retrieves all of the transactions later than any version given by the "v" -arguments. +{{transactions_ss_http_api}} +{{events_ss_http_api}} To make a query:: From e5da1e17412c99437d2af50b9b62c150c1c40662 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Thu, 12 Jul 2018 21:34:52 -0600 Subject: [PATCH 02/10] Improve upon the transaction schema and examples Reduces data duplication and makes the objects more reusable for other areas of the spec --- .../definitions/full_transaction.yaml | 28 --- api/server-server/definitions/pdu.yaml | 160 ++++-------------- .../definitions/unsigned_pdu.yaml | 119 +++++++++++++ .../examples/full_transaction.json | 6 - api/server-server/examples/pdu.json | 16 +- api/server-server/examples/unsigned_pdu.json | 17 ++ api/server-server/transactions.yaml | 15 +- scripts/templating/matrix_templates/units.py | 13 +- 8 files changed, 196 insertions(+), 178 deletions(-) delete mode 100644 api/server-server/definitions/full_transaction.yaml create mode 100644 api/server-server/definitions/unsigned_pdu.yaml delete mode 100644 api/server-server/examples/full_transaction.json create mode 100644 api/server-server/examples/unsigned_pdu.json diff --git a/api/server-server/definitions/full_transaction.yaml b/api/server-server/definitions/full_transaction.yaml deleted file mode 100644 index 39250433..00000000 --- a/api/server-server/definitions/full_transaction.yaml +++ /dev/null @@ -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'] \ No newline at end of file diff --git a/api/server-server/definitions/pdu.yaml b/api/server-server/definitions/pdu.yaml index b3f25ccf..2b6328be 100644 --- a/api/server-server/definitions/pdu.yaml +++ b/api/server-server/definitions/pdu.yaml @@ -16,131 +16,37 @@ title: Persistent Data Unit description: A persistent data unit (event) example: $ref: "../examples/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 - 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" - } +allOf: + - $ref: "unsigned_pdu.yaml" + - type: object properties: - sha256: - type: string - description: The hash - example: thishashcoversallfieldsincasethisisredacted - required: ['sha256'] - signatures: - type: object - description: |- - Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_ - example: { - "example.com": { - "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" - } - } - additionalProperties: - type: object - title: Server Signatures - additionalProperties: - type: string - 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`` -required: - - room_id - - sender - - origin - - origin_server_ts - - type - - content - - prev_events - - depth - - auth_events - - hashes - - signatures + hashes: + type: object + title: Event Hash + description: Hashes of the PDU, following the algorithm specified in `Signing Events`_ + example: { + "sha256": "thishashcoversallfieldsincasethisisredacted" + } + properties: + sha256: + type: string + description: The hash + example: thishashcoversallfieldsincasethisisredacted + required: ['sha256'] + signatures: + type: object + description: |- + Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_ + example: { + "example.com": { + "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" + } + } + additionalProperties: + type: object + title: Server Signatures + additionalProperties: + type: string + required: + - hashes + - signatures diff --git a/api/server-server/definitions/unsigned_pdu.yaml b/api/server-server/definitions/unsigned_pdu.yaml new file mode 100644 index 00000000..173bddd4 --- /dev/null +++ b/api/server-server/definitions/unsigned_pdu.yaml @@ -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 diff --git a/api/server-server/examples/full_transaction.json b/api/server-server/examples/full_transaction.json deleted file mode 100644 index c453d6ed..00000000 --- a/api/server-server/examples/full_transaction.json +++ /dev/null @@ -1,6 +0,0 @@ -{ - "origin": "matrix.org", - "origin_server_ts": 1234567890, - "pdus": [{"$ref": "pdu.json"}], - "edus": [{"$ref": "edu.json"}] -} \ No newline at end of file diff --git a/api/server-server/examples/pdu.json b/api/server-server/examples/pdu.json index 531f4a37..81981b23 100644 --- a/api/server-server/examples/pdu.json +++ b/api/server-server/examples/pdu.json @@ -1,16 +1,5 @@ { - "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"} - ] - ], + "$ref": "unsigned_pdu.json", "hashes": { "sha256": "thishashcoversallfieldsincasethisisredacted" }, @@ -18,8 +7,5 @@ "example.com": { "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" } - }, - "content": { - "key": "value" } } \ No newline at end of file diff --git a/api/server-server/examples/unsigned_pdu.json b/api/server-server/examples/unsigned_pdu.json new file mode 100644 index 00000000..6ed4b79d --- /dev/null +++ b/api/server-server/examples/unsigned_pdu.json @@ -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" + } +} \ No newline at end of file diff --git a/api/server-server/transactions.yaml b/api/server-server/transactions.yaml index 389eecc7..13ba6826 100644 --- a/api/server-server/transactions.yaml +++ b/api/server-server/transactions.yaml @@ -43,8 +43,21 @@ paths: - in: body name: body type: object + required: true 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: 200: # TODO: Spec this (and figure out what it is) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 7819dbf9..8037bb61 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -138,6 +138,10 @@ def inherit_parents(obj): Recurse through the 'allOf' declarations in the object """ 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", []) if not parents: return obj @@ -379,6 +383,10 @@ def get_tables_for_response(schema): def get_example_for_schema(schema): """Returns a python object representing a suitable example for this object""" schema = inherit_parents(schema) + + if isinstance(schema, list): + return [get_example_for_schema(v) for v in schema] + if 'example' in schema: example = schema['example'] return example @@ -398,7 +406,10 @@ def get_example_for_schema(schema): if proptype == 'array': if 'items' not in schema: 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': return 0 From 89384c96c18310d084fa3c2695c51109780b9f53 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Wed, 18 Jul 2018 11:06:23 -0600 Subject: [PATCH 03/10] Full stops, language. --- api/server-server/definitions/edu.yaml | 10 ++++----- api/server-server/definitions/pdu.yaml | 8 +++---- .../definitions/transaction.yaml | 6 ++--- .../definitions/unsigned_pdu.yaml | 22 +++++++++---------- api/server-server/events.yaml | 21 +++++++++--------- 5 files changed, 34 insertions(+), 33 deletions(-) diff --git a/api/server-server/definitions/edu.yaml b/api/server-server/definitions/edu.yaml index 4597ca62..af12752c 100644 --- a/api/server-server/definitions/edu.yaml +++ b/api/server-server/definitions/edu.yaml @@ -22,16 +22,16 @@ example: properties: edu_type: type: string - description: The type of ephemeral message - example: "!abc123:matrix.org" + description: The type of ephemeral message. + example: "m.presence" origin: type: string - description: The server name sending the ephemeral message + description: The server name sending the ephemeral message. example: "matrix.org" destination: type: string - description: The server name receiving the ephemeral message + description: The server name receiving the ephemeral message. example: "elsewhere.com" content: type: object - description: The content of the ephemeral message + description: The content of the ephemeral message. diff --git a/api/server-server/definitions/pdu.yaml b/api/server-server/definitions/pdu.yaml index 2b6328be..a5da57c0 100644 --- a/api/server-server/definitions/pdu.yaml +++ b/api/server-server/definitions/pdu.yaml @@ -23,20 +23,20 @@ allOf: hashes: type: object title: Event Hash - description: Hashes of the PDU, following the algorithm specified in `Signing Events`_ + description: Hashes of the PDU, following the algorithm specified in `Signing Events`_. example: { "sha256": "thishashcoversallfieldsincasethisisredacted" } properties: sha256: type: string - description: The hash - example: thishashcoversallfieldsincasethisisredacted + description: The hash. + example: thishashcoversallfieldsincasthisisredacted required: ['sha256'] signatures: type: object description: |- - Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_ + Signatures of the redacted PDU, following the algorithm specified in `Signing Events`_. example: { "example.com": { "ed25519:key_version:": "these86bytesofbase64signaturecoveressentialfieldsincludinghashessocancheckredactedpdus" diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml index 630d2ba3..e4c1f559 100644 --- a/api/server-server/definitions/transaction.yaml +++ b/api/server-server/definitions/transaction.yaml @@ -20,16 +20,16 @@ properties: origin: type: string description: |- - The ``server_name`` of hoemserver sending this transaction + The ``server_name`` of the hoemserver sending this transaction. example: "example.org" origin_server_ts: type: integer format: int64 - description: Timestamp in milliseconds on originating homeserver when this transaction started + description: Timestamp in milliseconds on originating homeserver when this transaction started. example: 1234567890 pdus: type: array - description: List of persistent updates to rooms + description: List of persistent updates to rooms. items: $ref: "pdu.yaml" required: ['origin', 'origin_server_ts', 'pdus'] \ No newline at end of file diff --git a/api/server-server/definitions/unsigned_pdu.yaml b/api/server-server/definitions/unsigned_pdu.yaml index 173bddd4..ca0a1183 100644 --- a/api/server-server/definitions/unsigned_pdu.yaml +++ b/api/server-server/definitions/unsigned_pdu.yaml @@ -19,15 +19,15 @@ example: properties: room_id: type: string - description: Room identifier + description: Room identifier. example: "!abc123:matrix.org" sender: type: string - description: The ID of the user sending the event + 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 + description: The ``server_name`` of the homeserver that created this event. example: "matrix.org" origin_server_ts: type: integer @@ -47,13 +47,13 @@ properties: example: "my_key" content: type: object - description: The content of the event + 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 + of when it made this event. items: type: array maxItems: 2 @@ -70,16 +70,16 @@ properties: properties: sha256: type: string - description: The event hash + description: The event hash. example: abase64encodedsha256hashshouldbe43byteslong required: ['sha256'] depth: type: integer - description: The maximum depth of the ``prev_events``, plus one + 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 + description: Event IDs and hashes for the "auth events" of this event. items: type: array maxItems: 2 @@ -96,16 +96,16 @@ properties: properties: sha256: type: string - description: The event hash + description: The event hash. example: abase64encodedsha256hashshouldbe43byteslong required: ['sha256'] redacts: type: string - description: For redaction events, the ID of the event being redacted + 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`` + description: Additional data added by the origin server but not covered by the ``signatures``. example: {"key": "value"} required: - room_id diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index 055883c2..08498c35 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -33,37 +33,37 @@ paths: - in: path name: roomId type: string - description: The room ID to get state for + description: The room ID to get state for. required: true x-example: "!abc123:matrix.org" responses: 200: - description: The room state for the room (kept under ``pdus``) + description: The room state for the room (kept under ``pdus``). schema: $ref: "definitions/transaction.yaml" "/event/{eventId}": get: summary: Get a single event description: |- - Retrieves a single event + Retrieves a single event. operationId: getEvent parameters: - in: path name: eventId type: string - description: The event ID to get + description: The event ID to get. required: true x-example: "$abc123:matrix.org" responses: 200: - description: A transaction containing a single PDU which is the event requested + description: A transaction containing a single PDU which is the event requested. schema: $ref: "definitions/transaction.yaml" "/backfill/{roomId}": get: summary: Retrieves the events which precede the given event description: |- - Retreives a sliding-window history of previous PDUs that occurred on the given room. + Retreives a sliding-window history of previous PDUs that occurred in the given room. Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it are retrived, up to the total number given by the ``limit``. operationId: backfillRoom @@ -71,19 +71,19 @@ paths: - in: path name: roomId type: string - description: The room ID to backfill + description: The room ID to backfill. required: true x-example: "!abc123:matrix.org" - in: query name: v type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it - description: The event ID to backfill from + description: The event ID to backfill from. required: true x-example: "$abc123:matrix.org" - in: query name: limit type: integer - description: The maximum number of events to retrieve + description: The maximum number of events to retrieve. required: true # TODO: Verify x-example: 10 responses: @@ -91,6 +91,7 @@ paths: description: A transaction containing the PDUs that preceded the given event(s). schema: $ref: "definitions/transaction.yaml" + # TODO: It's possible that this endpoint doesn't exist anymore - verify "/pull": get: summary: Stream events later than a given point in history @@ -101,7 +102,7 @@ paths: - in: query name: v type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it - description: The event ID to backfill from + description: The event ID to backfill from. required: true x-example: "$abc123:matrix.org" - in: query From 21c4af70a95b3bb7d7f8767e91487a5df5475a17 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 09:13:15 -0600 Subject: [PATCH 04/10] Fix schema definitions (spelling, attributes) --- api/server-server/definitions/edu.yaml | 5 ++++- api/server-server/definitions/transaction.yaml | 2 +- api/server-server/definitions/unsigned_pdu.yaml | 1 - api/server-server/events.yaml | 4 ++-- 4 files changed, 7 insertions(+), 5 deletions(-) diff --git a/api/server-server/definitions/edu.yaml b/api/server-server/definitions/edu.yaml index af12752c..c89573fe 100644 --- a/api/server-server/definitions/edu.yaml +++ b/api/server-server/definitions/edu.yaml @@ -24,14 +24,17 @@ properties: type: string description: The type of ephemeral message. example: "m.presence" + required: true origin: type: string description: The server name sending the ephemeral message. - example: "matrix.org" + example: "matrix.org" + required: true destination: type: string description: The server name receiving the ephemeral message. example: "elsewhere.com" + required: true content: type: object description: The content of the ephemeral message. diff --git a/api/server-server/definitions/transaction.yaml b/api/server-server/definitions/transaction.yaml index e4c1f559..930ddec1 100644 --- a/api/server-server/definitions/transaction.yaml +++ b/api/server-server/definitions/transaction.yaml @@ -20,7 +20,7 @@ properties: origin: type: string description: |- - The ``server_name`` of the hoemserver sending this transaction. + The ``server_name`` of the homeserver sending this transaction. example: "example.org" origin_server_ts: type: integer diff --git a/api/server-server/definitions/unsigned_pdu.yaml b/api/server-server/definitions/unsigned_pdu.yaml index ca0a1183..011b2736 100644 --- a/api/server-server/definitions/unsigned_pdu.yaml +++ b/api/server-server/definitions/unsigned_pdu.yaml @@ -37,7 +37,6 @@ properties: type: type: string description: Event type - required: true example: "m.room.message" state_key: type: string diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index 08498c35..96b2a825 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -65,7 +65,7 @@ paths: description: |- Retreives a sliding-window history of previous PDUs that occurred in the given room. Starting from the PDU ID(s) given in the ``v`` argument, the PDUs that preceded it - are retrived, up to the total number given by the ``limit``. + are retrieved, up to the total number given by the ``limit``. operationId: backfillRoom parameters: - in: path @@ -84,7 +84,7 @@ paths: name: limit type: integer description: The maximum number of events to retrieve. - required: true # TODO: Verify + required: true x-example: 10 responses: 200: From 88beaf4ad8f5a27bbdd5a3c30d0fd002ab431954 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 09:13:46 -0600 Subject: [PATCH 05/10] Completely remove /pull It's not been in use for years - we can safely let it disappear --- api/server-server/events.yaml | 26 -------------------------- 1 file changed, 26 deletions(-) diff --git a/api/server-server/events.yaml b/api/server-server/events.yaml index 96b2a825..d540085d 100644 --- a/api/server-server/events.yaml +++ b/api/server-server/events.yaml @@ -91,29 +91,3 @@ paths: description: A transaction containing the PDUs that preceded the given event(s). schema: $ref: "definitions/transaction.yaml" - # TODO: It's possible that this endpoint doesn't exist anymore - verify - "/pull": - get: - summary: Stream events later than a given point in history - description: |- - Retrieves all of the transactions later than any version given by the ``v`` arguments. - operationId: pull - parameters: - - in: query - name: v - type: string # TODO: The description says this is plural - figure out how to specify multiple, and spec it - description: The event ID to backfill from. - required: true - x-example: "$abc123:matrix.org" - - in: query - name: origin - type: string - description: The origin # TODO: What is this actually? - required: true # TODO: Verify - x-example: "matrix.org" - responses: - 200: - # TODO: This could do with a better description - description: A transaction containing multiple PDUs - schema: - $ref: "definitions/transaction.yaml" \ No newline at end of file From a4e5a461f9b5886b5183f28072916c0a0cbba3c1 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 09:14:31 -0600 Subject: [PATCH 06/10] Improve handing of lists appearing in items --- scripts/templating/matrix_templates/units.py | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index fc2b9181..c99b7c38 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -140,9 +140,6 @@ def inherit_parents(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", []) if not parents: return obj @@ -298,6 +295,8 @@ def process_data_type(prop, required=False, enforce_title=True): elif prop_type == "array": items = prop["items"] + # Items can be a list of schemas or a schema itself + # http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4 if isinstance(items, list): prop_title = "[" for i in items: @@ -385,9 +384,6 @@ def get_example_for_schema(schema): """Returns a python object representing a suitable example for this object""" schema = inherit_parents(schema) - if isinstance(schema, list): - return [get_example_for_schema(v) for v in schema] - if 'example' in schema: example = schema['example'] return example @@ -407,10 +403,13 @@ def get_example_for_schema(schema): if proptype == 'array': if 'items' not in schema: raise Exception('"array" property has neither items nor example') - result = get_example_for_schema(schema['items']) + items = schema['items'] + if isinstance(items, list): + return [get_example_for_schema(i) for i in items] + result = get_example_for_schema(items) if isinstance(result, list): - return result - return [result] + return [result] + return result if proptype == 'integer': return 0 From 042772aaf58141c9b5a433134c88b0817e8af648 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 10:13:23 -0600 Subject: [PATCH 07/10] Make nested titles better --- scripts/templating/matrix_templates/units.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index c99b7c38..e6493f2e 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -298,12 +298,12 @@ def process_data_type(prop, required=False, enforce_title=True): # Items can be a list of schemas or a schema itself # http://json-schema.org/latest/json-schema-validation.html#rfc.section.6.4 if isinstance(items, list): - prop_title = "[" + nested_titles = [] for i in items: nested = process_data_type(i) tables.extend(nested['tables']) - prop_title = "%s%s, " % (prop_title, nested['title']) - prop_title = prop_title[:-2] + "]" + nested_titles.extend([nested['title']]) + prop_title = "[%s]" % (", ".join(nested_titles), ) else: nested = process_data_type(prop["items"]) prop_title = "[%s]" % nested["title"] From 5ade15534d128519a6af77777e76aa79e466fa56 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 10:17:39 -0600 Subject: [PATCH 08/10] Remove extra branch in example generation --- scripts/templating/matrix_templates/units.py | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index e6493f2e..15c987fd 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -406,10 +406,7 @@ def get_example_for_schema(schema): items = schema['items'] if isinstance(items, list): return [get_example_for_schema(i) for i in items] - result = get_example_for_schema(items) - if isinstance(result, list): - return [result] - return result + return get_example_for_schema(items) if proptype == 'integer': return 0 From 9fa838d3e8d51103ac990ed4808274441149e00f Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 10:17:57 -0600 Subject: [PATCH 09/10] Improve type naming --- scripts/templating/matrix_templates/units.py | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index 15c987fd..a4f682bb 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -302,7 +302,7 @@ def process_data_type(prop, required=False, enforce_title=True): for i in items: nested = process_data_type(i) tables.extend(nested['tables']) - nested_titles.extend([nested['title']]) + nested_titles.append(nested['title']) prop_title = "[%s]" % (", ".join(nested_titles), ) else: nested = process_data_type(prop["items"]) @@ -523,10 +523,8 @@ class MatrixUnits(Units): items = param.get("items") if items: if isinstance(items, list): - val_type = "[" - for i in items: - val_type += "%s, " % items.get("type") - val_type = val_type[:-2] + "]" + types = ", ".join(i.get("type") for i in items) + val_type = "[%s]" % (types,) else: val_type = "[%s]" % items.get("type") From acf9632afcd0fb3861c203a1fb346ffaaffa98d8 Mon Sep 17 00:00:00 2001 From: Travis Ralston Date: Tue, 24 Jul 2018 10:25:24 -0600 Subject: [PATCH 10/10] Enlist the examples --- scripts/templating/matrix_templates/units.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/templating/matrix_templates/units.py b/scripts/templating/matrix_templates/units.py index a4f682bb..5b39a2b3 100644 --- a/scripts/templating/matrix_templates/units.py +++ b/scripts/templating/matrix_templates/units.py @@ -406,7 +406,7 @@ def get_example_for_schema(schema): items = schema['items'] if isinstance(items, list): return [get_example_for_schema(i) for i in items] - return get_example_for_schema(items) + return [get_example_for_schema(items)] if proptype == 'integer': return 0