Skip to content

Commit 229e6bd

Browse files
cristian-recoseanugarethsb
cristian-recoseanu
and
garethsb
authored
The smallest number of schema changes required to support transports extensibility (#177)
* The smallest number of schema changes required to support transports extensibility * Update APIs/schemas/transporttype-response-schema.json Co-authored-by: Gareth Sylvester-Bradley <[email protected]> * Update APIs/schemas/transporttype-response-schema.json Co-authored-by: Gareth Sylvester-Bradley <[email protected]> * Update APIs/schemas/sender_transport_params.json Co-authored-by: Gareth Sylvester-Bradley <[email protected]> * Update APIs/schemas/receiver_transport_params.json Co-authored-by: Gareth Sylvester-Bradley <[email protected]> * Update APIs/schemas/constraints-schema.json Co-authored-by: Gareth Sylvester-Bradley <[email protected]> * Allow vendor-specific transport types * Update APIs/schemas/transporttype-response-schema.json Suggested change Co-authored-by: Gareth Sylvester-Bradley <[email protected]> * Simplify the transport params and constraints schemas since an instance that is valid per any of the transport-specific schemas is also valid per the general schema Implementations (devices, clients, test suites) may use the transport-specific schemas as an additional validation step * Simplify the transport type, transport params, and constraints, schemas * An instance that is valid per any of the transport-specific schemas is also valid per the general schema * Implementations (devices, clients, test suites) may use the transport-specific schemas as an additional validation step * Make description of schemas more agnostic of where the transport lives * Add transports parameter register references to relevant sections --------- Co-authored-by: Gareth Sylvester-Bradley <[email protected]> Co-authored-by: Gareth Sylvester-Bradley <[email protected]>
1 parent 2b74cbe commit 229e6bd

8 files changed

+53
-70
lines changed

‎APIs/schemas/constraints-schema.json‎

Lines changed: 8 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -2,23 +2,14 @@
22
"$schema": "http://json-schema.org/draft-04/schema#",
33
"description": "Used to express the dynamic constraints on transport parameters. These constraints may be set and changed at run time. Parameters must also conform with constraints inferred from the specification. Every transport parameter must have an entry, even if it is only an empty object.",
44
"title": "Constraints",
5-
"anyOf": [{
6-
"type": "array",
7-
"items": {
8-
"$ref": "constraints-schema-rtp.json"
9-
}
10-
},
11-
{
12-
"type": "array",
13-
"items": {
14-
"$ref": "constraints-schema-websocket.json"
15-
}
16-
},
17-
{
18-
"type": "array",
19-
"items": {
20-
"$ref": "constraints-schema-mqtt.json"
5+
"type": "array",
6+
"items": {
7+
"description": "Constraints on transport parameters",
8+
"type": "object",
9+
"patternProperties": {
10+
"^[a-zA-Z0-9_]+$": {
11+
"$ref": "constraint-schema.json#/definitions/constraint"
2112
}
2213
}
23-
]
14+
}
2415
}

‎APIs/schemas/receiver_transport_params.json‎

Lines changed: 13 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,19 @@
22
"$schema": "http://json-schema.org/draft-04/schema#",
33
"description": "Transport-specific parameters. If this parameter is included in a client request it must include the same number of array elements (or 'legs') as specified in the constraints. If no changes are required to a specific leg it must be included as an empty object ({}).",
44
"title": "Receiver Transport Parameters",
5-
"anyOf": [{
6-
"type": "array",
7-
"items": {
8-
"$ref": "receiver_transport_params_rtp.json"
9-
}
10-
},
11-
{
12-
"type": "array",
13-
"items": {
14-
"$ref": "receiver_transport_params_dash.json"
15-
}
16-
},
17-
{
18-
"type": "array",
19-
"items": {
20-
"$ref": "receiver_transport_params_websocket.json"
21-
}
22-
},
23-
{
24-
"type": "array",
25-
"items": {
26-
"$ref": "receiver_transport_params_mqtt.json"
5+
"type": "array",
6+
"items": {
7+
"description": "Transport-specific parameters for a transport",
8+
"type": "object",
9+
"patternProperties": {
10+
"^[a-zA-Z0-9_]+$": {
11+
"type": [
12+
"string",
13+
"boolean",
14+
"null",
15+
"number"
16+
]
2717
}
2818
}
29-
]
19+
}
3020
}

‎APIs/schemas/sender_transport_params.json‎

Lines changed: 13 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -2,29 +2,19 @@
22
"$schema": "http://json-schema.org/draft-04/schema#",
33
"description": "Transport-specific parameters. If this parameter is included in a client request it must include the same number of array elements (or 'legs') as specified in the constraints. If no changes are required to a specific leg it must be included as an empty object ({}).",
44
"title": "Sender Transport Parameters",
5-
"anyOf": [{
6-
"type": "array",
7-
"items": {
8-
"$ref": "sender_transport_params_rtp.json"
9-
}
10-
},
11-
{
12-
"type": "array",
13-
"items": {
14-
"$ref": "sender_transport_params_dash.json"
15-
}
16-
},
17-
{
18-
"type": "array",
19-
"items": {
20-
"$ref": "sender_transport_params_websocket.json"
21-
}
22-
},
23-
{
24-
"type": "array",
25-
"items": {
26-
"$ref": "sender_transport_params_mqtt.json"
5+
"type": "array",
6+
"items": {
7+
"description": "Transport-specific parameters for a transport",
8+
"type": "object",
9+
"patternProperties": {
10+
"^[a-zA-Z0-9_]+$": {
11+
"type": [
12+
"string",
13+
"boolean",
14+
"null",
15+
"number"
16+
]
2717
}
2818
}
29-
]
19+
}
3020
}

‎APIs/schemas/transporttype-response-schema.json‎

Lines changed: 10 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,17 @@
33
"title": "Transport Type",
44
"description": "Transport type URN base used by the Sender or Receiver (i.e. with any subclassifications or versions removed)",
55
"type": "string",
6-
"oneOf": [
6+
"anyOf": [
77
{
8-
"enum": [
9-
"urn:x-nmos:transport:rtp",
10-
"urn:x-nmos:transport:dash",
11-
"urn:x-nmos:transport:websocket",
12-
"urn:x-nmos:transport:mqtt"
13-
]
8+
"description": "Any transport type URN base defined in IS-05 or by an AMWA specification in the Transports register of the NMOS Parameter Registers",
9+
"type": "string",
10+
"pattern": "^urn:x-nmos:transport:[^./]+$"
11+
},
12+
{
13+
"description": "Any manufacturer-specific transport type URN base",
14+
"not": {
15+
"pattern": "^urn:x-nmos:"
16+
}
1417
}
1518
],
1619
"format": "uri"

‎docs/APIs - Client Side Implementation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ _(c) AMWA 2017, CC Attribution-NoDerivatives 4.0 International (CC BY-ND 4.0)_
66

77
The Connection API schemas define sets of parameters for each supported transport type; these are also described in pages in the [Behaviour](Behaviour.md) section of these documents. These pages define which parameters are always present (core), and which are feature-dependent; a client can determine what a Device supports by getting its `/constraints` resource, and SHOULD parse this resource in all cases as a Device might have a constrained range or enumeration of supported values, even for core parameters.
88

9+
Note: From v1.2 onwards, additional transport types and associated schemas are defined in the [Transports register](https://specs.amwa.tv/nmos-parameter-registers/branches/main/transports/) of the NMOS Parameter Registers.
10+
911
## RTP Operating Point
1012

1113
When establishing an RTP connection between two Devices that implement NMOS Connection Management, the expectation is that the primary means of connection will be to supply the SDP file from the Sender to the Receiver. This ensures Receivers have the media information in the SDP file. If desired the client can adjust individual transport parameters on the Receiver. For example it could use the `rtcp_enable` parameter to toggle RTCP operation.

‎docs/APIs - Server Side Implementation.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,8 @@ In some cases the behaviour is more complex, and can be determined by the vendor
4646

4747
It is strongly RECOMMENDED that API implementations validate requests received from clients against the JSON schema included in this specification. Where additional constraints are applied by the API using the `/constraints` resource, these restrictions SHOULD be merged with the provided JSON schema in order to provide consistent validation.
4848

49+
Note: From v1.2 onwards, additional transport types and associated schemas are defined in the [Transports register](https://specs.amwa.tv/nmos-parameter-registers/branches/main/transports/) of the NMOS Parameter Registers.
50+
4951
### Constraining Interfaces
5052

5153
The constraints are used to advertise the available network interfaces on the Device. This happens through use of an `enum` constraint, which contains an array of the available interface IP addresses. For interfaces capable of operating with IPv6 and IPv4 each interface SHOULD have two entries containing the interface's IPv4 and IPv6 addresses. Examples are provided in the API documentation.

‎docs/APIs.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,16 @@ The Connection API is specified using:
1010

1111
- The following sub-sections describing common API properties.
1212
- [RAML](http://raml.org/) documents and [JSON schemas](http://tools.ietf.org/html/draft-zyp-json-schema-04) in the [APIs](../APIs/) folder.
13+
- Transport types and associated schemas defined in the [Transports register](https://specs.amwa.tv/nmos-parameter-registers/branches/main/transports/) of the NMOS Parameter Registers (from v1.2 onwards)
1314

1415
Examples of JSON format output are provided in the [examples](../examples/) folder.
1516

1617
## API Validation
1718

1819
JSON schemas are included with the RAML API definitions. These include validation for values used within the APIs. It is RECOMMENDED that implementers of a Connection API use these JSON schemas as part of a validation stage when receiving requests from clients. Invalid requests SHOULD cause a `400` (Bad Request) HTTP error to be returned to the client.
1920

21+
Note: From v1.2 onwards, additional transport types and associated schemas are defined in the [Transports register](https://specs.amwa.tv/nmos-parameter-registers/branches/main/transports/) of the NMOS Parameter Registers.
22+
2023
### Content Types
2124

2225
All APIs MUST provide a JSON representation signalled via `Content-Type: application/json` headers. This SHOULD be the default content type in the absence of any requested alternative by clients. Other content types (such as HTML) are permitted if they are explicitly requested via `Accept` headers.

‎docs/Upgrade Path.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,8 @@ Implementers of the Connection API MUST support at least one API version, and MA
1212

1313
Where a transport type is added in a new version of the Connection API specification, earlier versioned APIs MUST NOT list any Senders or Receivers which make use of this new transport type. In these cases, requests to an inaccessible ID MUST return a `409` (Conflict) HTTP code.
1414

15+
Note: From v1.2 onwards, additional transport types and associated schemas are defined in the [Transports register](https://specs.amwa.tv/nmos-parameter-registers/branches/main/transports/) of the NMOS Parameter Registers.
16+
1517
Where new transport parameters are added to a pre-existing transport type in a new version of the Connection API, earlier versioned APIs MUST NOT list these parameters. New transport parameters SHOULD be defined such that a request which omits them can proceed without error. This ensures that servers implementing multiple versions of the Connection API can continue to process earlier versioned requests successfully.
1618

1719
Connection APIs do not need to provide for forwards compatibility as it might be impossible to generate data for new attributes in schemas.

0 commit comments

Comments
 (0)