amwa-tv / is-04 Goto Github PK

Consider a raw audio flow:

{
        "type": "flow",
        "data": {
            "id": "aa993cd9-d811-4191-91d1-2ef72575cbda",
            "version": "1:2",
            "label": "my flow",
            "description": "",
            "tags": {},
            "source_id": "c9d11fb8-e220-4b63-86e0-8b11a3d60de1",
            "device_id": "7a05e81a-69be-4e30-b24a-e23004ca8f65",
            "parents": [],
            "format": "urn:x-nmos:format:audio",
            "sample_rate": {
                "numerator": 48000
            },
            "media_type": "audio/L24",
            "bit_depth": 24
        }
}

This will pass schema validation. Now let's make a slight change:

"media_type": "audio/L32",

This will fail, even though the new media_type passes its regex constraint. It fails because it now also passes the coded audio flow schema, but the flow root schema (the one in flow.json) mandates a oneOf constraint for all flow types.

@andrewbonney said that AMWA-TV/is-07#38 adds "further weight to a feeling I've had that we ought to be removing the automatic Query API key stripping functionality and depending upon the query downgrade mechanism for multi-version support instead, but that's very much an IS-04 discussion point."

@garethsb-sony "So v1.3 resources would never appear in a response to a v1.2 API?"

@andrewbonney "Yes, that's the thinking. You could as a result only cause mixed version responses by using /v1.3/resources/?query.downgrade=v1.2 etc, ensuring that only clients which are explicitly written to support multiple versions are exposed to it."

@garethsb-sony "That makes sense but loses us some of the flexibility discussed in IS-04 Upgrade Path - Performing Upgrades."

The health resource POST is specified as follows:

/health/nodes/{nodeId}:
  displayName: Node health
  post:
    description: Update Node health
    responses:
      200:
        body:
          example: !include ../examples/registrationapi-v1.0-health-post-200.json
      404:
        description: Returned when the requested Node does not exist or has been garbage collected`

However, the VM provided on box to incubator members behaves differently, responding with a 204 No Content with no body. I think the RAML specification should be:

/health/nodes/{nodeId}:
  displayName: Node health
  post:
    description: Update Node health
    body:
      example: !include ../examples/registrationapi-v1.0-health-post-200.json
    responses:
      204:
        description: No content successful response.
      404:
        description: Returned when the requested Node does not exist or has been garbage collected`

This was discovered during a side-by-side comparison of ledger's registration service with the bbcrd VM (bbcrd_ipstudio_exportable_headless_discovery_amd64_master_2016-02-06.ova).

It isn't completely clear how a Sender/Receiver's subscribed ID should be set when the Sender or Receiver is in a 'parked' or unsubscribed state. Whilst the 'active' flag is the authoritative reference for this in v1.2+, in order to maintain backwards compatibility for v1.1/v1.0 the Receiver's subscription sender_id needs to be set to 'null' when it is not subscribed to anything. This docs omission was noted having implemented checks in the test suite.

When testing a JSON validator for v1.2 schema, the nodeapi self example does not validate against node.json.

The interfaces.port_id property has regex ^([0-9a-f]{2}[-]){5}([0-9a-f]{2})$ but the example value is 74:26:96:db:87:32.

I also note that the interfaces.chassis_id is validating against the ^.+$ rule and not the MAC address rule, which is not what is intended.

Did you mean the regex to be ^([0-9a-f]{2}[:]){5}([0-9a-f]{2})$?

3.0 Discovery says

Advertisements of the above types may be accompanied by DNS TXT records as specified within the API RAML documentation.

2.0 APIs - API Paths says

API clients using DNS-SD for API discovery SHOULD construct these paths by making use of the TXT records 'api_proto' and 'api_ver', along with addresses and ports resolved via DNS-SD.
[...]
Where protocol and versioning data is not available, clients MAY assume a v1.0 API, which operates via the 'http' protocol only.

On the other hand, e.g. the RegistrationAPI.raml says:

The DNS-SD advertisement MUST be accompanied by a TXT record of name 'api_proto' [etc.]

In each case the bold is mine, but capitalization from the source, presumably RFC2119 terms where capitalized, but there seems to be some difference of opinion as to whether the TXT records are required, or whether "api_proto" = "http", "api_ver" = "v1.0" (and "pri" = max_int?) is assumed if the TXT records are not present.

A request has been received to permit multiple values of 'manifest_href' for a given Sender. These files would have identical contents, but would permit the file to be made available via multiple network interfaces (in the same way that a Node's 'endpoints' allows over the deprecated 'href').

In systems which implement the IS-05 specification this wouldn't be required, but for systems which implement IS-04 in isolation the 'manifest_href' may still be a requirement.

Minor issue noted in comments on 8f8718f. There are two example Location response header values in RegistrationAPI.raml which probably ought to reflect the version at the top of the file, but they were last updated for v1.1. Another option would be to use "{version}" or something?

There are other places in the v1.2 documentation that still use v1.1 endpoints as examples, e.g. 2.5. APIs - Query Parameters - Examples.

The example JSON responses/request files are still named for (and compatible with) v1.1 as well, though their content is also valid according to the v1.2 schemas I believe.

In Node Encounters HTTP 500 (or other 5xx), Inability To Connect, Or A Timeout On Heartbeat, it states (emphasis mine):

As this issue may affect just one Registration API in a cluster, it is recommended that clients identify another Registration API to use from their discovered list. The first interaction with a new Registration API in this case should be a heartbeat to confirm whether the Node is still present in the registry.

What should I do with the result? Presumably if it's a 404 I'll have to do a full re-register. But what if it's a 200? For the first registration we have to do this:

If a Node receives a 200 code in this case, a previous record of the Node can be assumed to still exist within the network registry. In order to avoid the registry-held representation of the Node's resources from being out of sync with the Node's view, an HTTP DELETE should be performed in this situation to explicitly clear the registry of the Node and any sub-resources.

Surely the same reasoning applies to all initial connections to a Registration API?

RegistrationAPI.raml specifies an mDNS service type of "_nmos-registration".

According to RFC6763 Section 7.2, the maximum service name length for an mDNS advertisement is 16 characters when including the leading underscore, but "_nmos_registration" is 18 characters.

The schema correctly uses dashes as separators for MAC addresses, but the examples are using colons which were used in an earlier development version of the spec.

See https://github.com/AMWA-TV/nmos-discovery-registration/blob/master/examples/nodeapi-v1.1-self-get-200.json for example.

A request was made via the AMWA Basecamp to add support to signal digital cinema colorspaces (ACES) in https://github.com/AMWA-TV/nmos-discovery-registration/blob/master/APIs/schemas/flow_video.json. At present only ITU colorspaces (starting BT...) are included.

The likely additions would be:
ST2065-1, ST2065-3, DCI-D65, DCI-D60

This was originally requested via AMWA Basecamp (text below). Additions should be made to https://github.com/AMWA-TV/nmos-discovery-registration/blob/master/docs/2.5.%20APIs%20-%20Query%20Parameters.md#pagination

• What should the X-Paging-Since value be when a client specifies only a paging.until value, and it is before the oldest resource's timestamp?
  The X-Paging-Until value should be the requested value, and the body should be an empty JSON array, but what about the X-Paging-Since value? Should it be the epoch (i.e. "0:0"), or one nanosecond before X-Paging-Since, or simply omitted?

• Conversely, what should the X-Paging-Until value be when a client specifies only a paging.since value, and it is after the newest resource's timestamp?

• The client specifies a filter query that results in a single value, but no paging query parameters - what should the X-Paging-Since and X-Paging-Until values be?
  Presumably the X-Paging-Until value is the timestamp of the returned resource, but what of X-Paging-Since?

• As above, but the filter query returns no results?

The Node API /receivers/{receiverId}/target PUT resource requires an object of type 'Sender'. This doesn't account for the 'unsubscribe' case documented at the top of the same RAML file which specifies:

In order to 'unsubscribe' a Receiver from a Sender, an empty object '{}' should be used in this PUT request.

Whilst this method is deprecated now that the IS-05 specification exists, this is clearly an error which should be resolved for the existing spec versions.

Query API subscriptions have caused minor confusion as some have used the response of a GET to /subscriptions in order to connect to an existing websocket. The correct procedure it to always use a POST when connecting to a websocket, however you MAY be returned the URL of an existing websocket if the Query API deems there to be a suitable one available. The GET response should be used only for debug.

Currently, Query API pagination "SHOULD" be supported by implementations but MUST be detected by clients.

There's nothing in the RAML specification of the Query API to indicate that pagination is not required (see definition of the paged trait. The APIs - Query Parameters - Pagination documentation does begin "Query APIs SHOULD support pagination..." however.

From the client's point of view this means that a simple Query API request to e.g. /x-nmos/query/v1.2/nodes (with no query parameters) can have two different meanings.

1. For a Query API which doesn't implement pagination, all nodes are returned in a single response
2. For a Query API which does implement pagination, only the first page of results is returned

This problem arises because pagination isn't 'opt in' from the client's point of view. This is quite different than the other optional API features, where the client has to make a different request to opt into the feature, e.g. query.downgrade, query.rql, query.ancestry_id.

In the case of pagination, it is currently therefore critical that the client distinguish between these two cases by examining the response headers that are (I believe) required if pagination is implemented, e.g. X-Paging-Limit.

Suggestions:

• Clarify in the RAML that the Query API traits are all currently optional (SHOULD or MAY)
• Clarify in the RAML, and the Query Parameters documentation, that clients currently MUST check the pagination response headers to distinguish a paginated response
• Add more tests for pagination in https://github.com/AMWA-TV/nmos-testing
• Think about how to automate tests for clients
• Think about whether to 'fix' this in some way in IS-04 v1.3+

I've started looking at how to speed up JSON Schema validation. One of the things that looks like it could help is taking advantage of the facilities in 'draft07' and beyond to short-circuit the evaluation of discriminated anyOf and oneOf logical combination sub-schemas, via the new if-then-else keywords. E.g. Registration API /resource POST can be discriminated via the type property.

How do we feel about updating the official schemas to draft07 or draft08? Or maintaining both draft04 schemas and more modern ones?

The trailing slash policy for the APIs is described here: https://github.com/AMWA-TV/nmos-discovery-registration/blob/master/docs/2.0.%20APIs.md#urls-approach-to-trailing-slashes. This describes client behaviour but fails to make important observations about server implementations as they have been tested at workshops.

A server implementing the APIs MUST support GET/HEAD (ie. read related) operations to both the trailing slash and non-trailing slash version of each resource. One of these MAY produce a 301 response causing a redirect to the other if preferred.

A server implementing the APIs MUST support PUT/PATCH/POST/DELETE/OPTIONS (ie. write related) operations on the non-trailing slash version of each resource. The implementation MAY additionally support the same methods on the trailing slash version but this is not strictly required.

The latter of these cases is particularly important as clients which receive a 301 type response when performing a PUT/POST etc will trigger a GET once redirected rather than the originally intended method. As such we have standardised on using the non-trailing slash version for all 'write' requests to avoid ambiguity between implementations.

The documentation should be enhanced to reflect the above.

When performing write requests (PUT/POST/DELETE etc) from a web browser a CORS pre-flight check will be performed to ensure that the client is permitted to make the request. This involves an OPTIONS request with headers similar to those described here: https://github.com/AMWA-TV/nmos-discovery-registration/blob/master/docs/2.3.%20APIs%20-%20Server%20Side%20Implementation%20Notes.md#cross-origin-resource-sharing-cors

At present the requirement to support OPTIONS is only called out here and whilst it has been tested at workshops it is a common stumbling block as it isn't explicitly in the RAML. OPTIONS support should be explicitly called out in all RAML which uses these sorts of methods.

BCP-003-02 adds a requirement to pass Authorization headers in requests. These could be required to read/write IS-04 resources on Nodes/Registries, or could be required to interact with services/controls which are advertised from IS-04. The requirement to include an Authorization token may be deployment specific, and may only be required for certain aspects of a deployment.

We should consider whether this should be flagged via DNS-SD TXT records prior to interacting with the APIs (may not be possible for the Node API directly), and whether an attribute should be added to service/control advertisements to indicate any Authorization requirements. The alternative is that this is pre-configured across a deployment in a static fashion, but this may limit flexibility.

Noted by Gareth Sylvester-Bradley:

The 'EmptySchema' used in the APIs is intended to indicate that the request body can be empty, but in reality if you run it through a validator it requires an empty object to be present '{}'.

This should be replaced with one of the following in the RAML to fix this. It doesn't appear to be possible to fix this correctly using JSON schema directly:

1. Currently preferred: Body parameter removed for requests with no request payload

get:
  description: List of paths available from this API
  responses:
    200:

2. Body set explicitly to null. Note that when rendered as HTML this indicates that the request body must still have a content type of application/json which isn't mandatory without a request body present.

get:
  description: List of paths available from this API
  body: null
  responses:
    200:

3. Similar to 2, but using !! to avoid 'null' being interpreted as a literal. This usage isn't 100% clear from the RAML 0.8 spec, but does still appear to validate.

get:
  description: List of paths available from this API
  body: !!null
  responses:
    200:

Originally posted by @garethsb-sony in #79 (comment)

I.e.

/nodes?foo=bar with no paging parameters must return all matching resources (even from a Query API that implements pagination), which may be unordered, but a response of (probably) 501 is permitted if that operation would be too intensive.

/nodes?foo=bar&paging.limit=100 would opt into the 'paging' trait specification and return the first 100 matching resources (or fewer, including if the server's maximum limit is less), ordered as specified.

The problem with this is that for clients that support pagination but don't know whether a Query API supports pagination, either have to try without paging parameters, and then retry with if they get a 501, or try first with paging parameters, and then retry without if they got a 501 from that (because v1.3+ implementations should return 501 if they don't support them...).

I can't immediately see how to fix that.

This would bring IS-04 into line with the version of RAML used by IS-05 and other work in progress specifications.

https://github.com/raml-org/raml-spec/blob/master/versions/raml-10/raml-10.md

As part of this update, consider removing versions which are baked into the filenames of the example JSON files. These could be confusing where they don't reference the API version they are released as part of (e.g. example files currently include 'v1.1' but are part of the v1.2 spec).

Following on from an e-mail discussion with @garethsb-sony

• Document reasoning behind the referential integrity requirements and in particular the change between v1.0 and v1.1 relating to content transformers.
• Update the Data Model diagram to reflect the association between a Flow and Device for referential integrity purposes (note that this is scoped within IS-04, there is no requirement for a Flow to be attached to a single Device outside of an IS-04 registration)
• Indicate in the schema descriptions which attributes serve as super-resources with regard to referential integrity.

In v1.1.x and v1.2.x the flow_id of a sender can be null regarding the sender.json-schema. However, in v1.0.x only a valid uuid is allowed.

How to deal with this regarding the output of the Query API?

E.g. registering a v1.2 sender with flow_id: null, what should be the QueryAPI output if I GET <...>/query/v1.0/senders?

Should this resource be ignored for the output or should the resource be displayed even if the output of the API is not perfectly valid regarding the current active schema?

Both alternatives look a bit inconsistent in their own way..

The default requirements for heartbeats to a Registration API are covered here: https://github.com/AMWA-TV/nmos-discovery-registration/blob/master/docs/4.1.%20Behaviour%20-%20Registration.md#heartbeating

It has been requested that an explicit note is added to identify that garbage collection timeouts on a Registration API may be increased without any adverse effect on the system (other than stale resources remaining in the system for longer).

For example: "The RDS could have its limit increased without any adverse effects on the Nodes. Decreasing this interval, or increasing the heartbeat interval, should be a system-wide configuration."

Most of the regex begin with ^ and finish with $ to ensure they only match the entire string, but not all. E.g. clock_internal.json has "pattern": "clk[0-9]+" where "pattern": "^clk[0-9]+$" is presumably intended. In the v1.2.x branch, the ^...$ are missing in patterns in clock_internal.json, clock_ptp.json, node.json and source_audio.json.

API versions in node.json are currently specified with "pattern": "v[0-9]+.[0-9]+". In addition to the above fix, the . is presumably supposed to match a literal . so this regex should be "pattern": "^v[0-9]+\\.[0-9]+$".

Additionally in the node schema, the patterns for "chassis_id" and "port_id" use [-]; I think this is valid because - doesn't have its special meaning in a character-range when it's the first or last character in it, but it's unusual. Certainly in other places, like all the UUID patterns we use bare -.

ws_href property in this example and similar should include the API namespace. In this example it should read ws://172.29.80.52:8870/x-nmos/query/v1.2/ws/?uid=7c903667-7113-4a8f-8865-1c63f9070a9e instead of ws://172.29.80.52:8870/ws/?uid=7c903667-7113-4a8f-8865-1c63f9070a9e.

As far as I can see this affects the following examples:
https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.2-dev/examples/queryapi-v1.1-subscriptionid-get-200.json
https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.2-dev/examples/queryapi-v1.1-subscriptions-get-200.json
https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.2-dev/examples/queryapi-v1.1-subscriptions-post-200.json

Minor documentation nit...

It would seem to be reasonable for an implementation to have the 'manifest_href' of a Sender refer to the relevant IS-05 Connection API endpoint?

However, APIs: Server Side Implementation Notes > Node API Senders: Use with RTP says:

When using RTP for a sender, the 'manifest_href' must be an HTTP-accessible reference to an SDP file. As-per RFC 4566, SDP files advertised via web services should use a MIME type of 'application/sdp' and a file extension of '.sdp'. [my emphasis]

On the other hand, the IS-05 Connection API /transportfile endpoint is understandably extension-less (to leave the door open for other transport file formats).

RFC 4566 actually seems to only have a single mention of a file extension, Section 8.1 The "application/sdp" Media Type, which says:

File extension(s): The extension ".sdp" is commonly used.

Since the Media Type in a web services context is more relevant than the file extension, I suggest dropping the reference to file extension in the IS-04 documentation, or explicitly allowing the extension-less case.

The 'senders' and 'receivers' arrays in a Device have been deprecated, but will continue to be present until v2.0.

Whilst clients' use of these fields is discouraged as a result, implementations have been seen which exhibit two behaviours. First first involves registering the Device with no Senders/Receivers in the arrays, then registering the Senders and Receivers before issuing a re-registration (update) of the Device with the arrays changed to reflect this. The second involves registering the Device with the arrays pre-populated before the Senders and Receivers are registered into the system.

The following text has been suggested as an addition to avoid clients attempting to request Senders/Receivers which do not yet exist in the system:

1. Devices MAY be registered with UUIDs of the Senders and Receivers attached to the Device, in the (deprecated) "senders" and "receivers" array properties, even if those Senders/Receivers have not yet been registered themselves.
2. Senders and Receivers attached to Devices MAY be omitted from the Device's (deprecated) "senders" and "receivers" array properties. Consumers of the Node/Query APIs SHOULD instead discover attached Senders/Receivers by filtering Senders and Receivers on "device_id".

flow_sdianc_data.json has the regex pattern for both DID and SDID as ^0x[0-9a-fA-F]{2}$. There are no examples in the spec repo, but it is clear this requires exactly two hex digits but accepts upper- and lower-case.

On the other hand, the representation in SDP files is governed by RFC 8331 which uses the ABNF:

TwoHex = "0x" 1*2(HEXDIG)
DidSdid = "DID_SDID={" TwoHex "," TwoHex "}"

Where HEXDIG is defined in RFC 2234 by:

DIGIT          =  %x30-39
                       ; 0-9
HEXDIG         =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"

Therefore, though the examples given in RFC 8331 are like "DID_SDID={0x61,0x02};DID_SDID={0x41,0x05}" which suggests two hex digits is good form, the TwoHex production allows a single hex digit, but requires uppercase for A-F.

This makes the values "0x41", "0x0c" valid in IS-04 but "{0x41,0x0c}" not valid in SDP, while "{0x41,0xC}" is valid in SDP but "0x41", "0xC" is not valid in IS-04.

This is probably worth at least a little note somewhere.

4.3 Behaviour: Nodes (in v1.3 and in v1.2) twice uses the phrase "current state". For clarity, this should be "current configuration", as per the change made in IS-05 by AMWA-TV/is-05#97.

Will make a PR.

The need to register each Node/Device/Sender/Receiver etc sequentially via the Registration API creates a bottleneck and delay when large devices first start up. A bulk method has been requested as an addition to the Registration API which would allow more resources to be registered in a single request payload.

When developing such an addition, it is suggested that the bulk API in IS-05 is used as a point of reference in order to keep behaviour as common as possible between the APIs.

Care must also be taken when registering resources which relate directly to each other. For example, via the 'single' API a 'Device' cannot be registered until its corresponding 'Node' has been registered. Consideration should be given to whether a bulk API should be restricted to registering a single type of resource at any one time (Node/Device etc), or if multiple types are permitted in a single request how the server should handle this to ensure referential integrity.

In order to reduce duplication (and potentially incorrect) pattern specifications for UUIDs, EUI64s etc these should be factored out of the JSON schema definitions into their own file or files.

These would then be referenced as follows for example:

"node_id": {
  "description": "ID of the Node",
  "$ref": "uuid.json"
}

If a single file is preferred for these definitions then the following approach could be used:

"$ref": "core.json#/definitions/uuid"

As noted in https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.3-dev/docs/2.0.%20APIs.md#urls-approach-to-trailing-slashes, URLs without trailing slashes are preferred. In many cases in the documentation, examples include a trailing slash when they should not. These ought to be addressed, and the expectations placed upon clients in processing them clarified.

Note that cases of this within the API responses are defined by schemas and must not be changed without a major version increment.

At present the Query API spec provides a recommended set of operators to implement when using the optional RQL support in the spec. It has been suggested that this is strengthened to be a mandatory set of operators which must be present if RQL support is implemented.

This is being tracked on the AMWA Basecamp but is being recorded here for completeness.

From the NMOS Content Model Specification:

NMOS specifications constrain a Grain used for interchange /to have exactly two TimeStamps (Origin and Sync).

However, the queryapi-subscriptions-websocket.json schema additionally has "creation_timestamp".

Discuss.
;-)

In order to allow a registry to clear out 'stale' resources when a Node goes offline in an uncontrolled fashion (ie. without issuing DELETEs), referential integrity between resources must be maintained. In order to do this a Device cannot be registered before its corresponding Node has been registered (for example), and if that Node disappears without first DELETEing the Device it registered the registry is responsible for clearing this up.

At present the documentation around this isn't clear enough. Explicit documentation for clients (ie. which order to register each resource in), and for servers (ie. when to clear up something if a parent resource has disappeared) should be added. It should be clear for each resource which attribute is responsible for this (for example the 'node_id' in a Device must match a Node in the registry).

Suggest adding a note that peer-to-peer mode is deprecated.

In the figure https://raw.githubusercontent.com/AMWA-TV/nmos/master/images/connection-sequence.png,
the destination node fetches SDP file, which, contains multicast streaming details of the sender. What should be the procedure for connection establishment, in the case of unicast media streaming?

At present Receiver capabilities are defined to differentiate between the different media_types which Flows may use. In order for control systems to make informed routing decisions these need to cover a greater spectrum of Source/Flow attributes. Some initial prototyping in this area has been carried out in bbc#6, but is incomplete.

IS-07 uses the "pattern": "^[^\\s\\/]+(\\/[^\\s\\/]+)*$" for its "event_type".

Should this be applied to IS-04 v1.3 Source/Flow "event_type" in IS-04 and Receiver caps "event_types"?

Link:

https://amwa-tv.github.io/nmos-discovery-registration/tags/v1.2_spec/html-APIs/QueryAPI.html

This section here I think is where the problem is:

For a full description of the expected querying behaviour along with examples, please see the [Query Parameters Documentation](../docs/2.5. APIs - Query Parameters.md).

From Discovery: Registered Operation:

If no Registration APIs are advertised on a network, the Node should assume peer to peer operation unless configured otherwise. The required TXT record advertisements for this mode are described in the Node API.

On the other hand, the Node API says:

When a Node is unable to locate or successfully register with a Registration API it MUST additionally advertise the following mDNS TXT records

Since the former sentence allows for nodes to not assume peer-to-peer operation, the extra TXT records should not be required.

From API we read :
baseUri: http://example.api.com/x-nmos/**{version}/node**

But from example https://github.com/AMWA-TV/nmos-discovery-registration/blob/master/examples/nodeapi-v1.0-receivertarget-put-request.json we see :

"manifest_href": "http://172.29.176.142:12345/x-nmos/**node/v1.0**/self/pipelinemanager/run/pipeline/1/pipel/ipp_rtptx0c6d/misc/sdp/", 

So, which one is correct ?
nmos-ledger follows the example.

Thanks.

Gilles.

Query API Behaviour is quite clear about HTTP DELETE of non-persistent subscriptions. How about the case of attempting HTTP DELETE of a persistent subscription which has open WebSocket connections? Should this forcibly close the WebSockets? Or is HTTP DELETE forbidden until all connections are closed?

Hello,

I don't get the point where an audio channel is described with only a free text label (which could be "").
So, shouldn't the property "symbol" be required?

As described in https://github.com/AMWA-TV/nmos-event-tally/blob/v1.0.x/docs/4.0.%20Core%20models.md#2-is-04-highlights IS-07 requires an additional Source attribute. In order to add this we need to ensure that the 'urn:x-nmos:format:data' URN is accompanied by a defined way to differentiate between different types of 'data' (including but not limited to IS-07 and SDI ancillary). Consideration should be given to this mechanism's extensibility in order to avoid unnecessary future version increments.

I need some clarification regarding secured websocket subscriptions.

Since version IS04-v1.1 a secure flag exists in the schema of the POST request to create such a subscription:

    "secure": {
      "description": "Whether to produce a secure websocket connection (wss://). NB: Default should be 'false' if the API is being presented via HTTP, and 'true' for HTTPS",
      "type": "boolean"
    },

From: queryapi-subscriptions-post-request.json

If I run a secured registry, the normal case would be that I don't want to allow unsecured subscriptions. I assume that I should respond with a 400, but this case is not that clear as for example in IS05 where we have constraints which I can check in advance as a controller. If that is correct, maybe the docs can be updated to explicitly mention this. Current text only says that a 400 must be returned when the POST request is incorrectly formatted or missing mandatory attributes.

In general: the flag secure is meant to be used for registries with interfaces in different subnets (e.g. one local which can be unsecured, and one external which has to be secured)? I currently cannot make up any other scenario where running an unsecured registry and allowing secured websocket connections or running a secured registry and allowing unsecured websocket connections would be required.

The doc for Query API query params has lots of examples, at https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.2.x/docs/2.5.%20APIs%20-%20Query%20Parameters.md#basic-queries.

The doc for Query WebSocket API explains parameters can be set up for the subscription using the "params", but has no examples, at https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.2.x/docs/4.2.%20Behaviour%20-%20Querying.md#handling-query-parameters.

It would be nice to include some/all of the same examples to show how URL query parameters are mapped to "params".

It would also be good to have the special query. params listed/linked from here as well - query.rql, query.downgrade, ...