Unlike IS-04, IS-05, IS-06 and IS-08, schemas in this repo have "$id" values.
These values may be useful, but I wonder why the particular URL has been used?

While there is no requirement that the URI given as a "$id" is resolvable, the URLs used, like
https://www.amwa.tv/event_and_tally/base.json might be expected to be resolvable, but result in 404 Not Found.

It seems strange to have used a non-resolvable URL rather than either a URN (e.g. urn:nmos:... as in several other NMOS specs) or a nice resolvable URL (such as https://github.com/AMWA-TV/nmos-event-tally/raw/v1.0/APIs/schemas/base.json).

The current non-resolvable URL, rendering 'NMOS Event & Tally' as event_and_tally fails to follow the naming used elsewhere like nmos-event-tally and are unversioned, which must be an oversight?

I must be missing it somehow, but I cannot find the definition or schema for the "subscription command" referred to in 5.2. Transport - Websocket - 4. Subscriptions strategy. Please would you point me in the right direction?

In my understanding MQTT brokers may support several protocols - the 'MQTT' protocol over TCP, a TLS protocol for secure comms, or variants on top of (Secure) WebSocket.

We have "destination_host" and "destination_port" (or the source variants for a Receiver) in the IS-05 MQTT transport params, but that doesn't indicate the protocol.

Similarly, Transport - MQTT - Broker discovery mentions the broker will be advertised via DNS-SD, but there's no indication of any TXT records that might allow the protocol to be discovered.

I'm also not sure whether the MQTT version needs to be specified, e.g. Version 3.1.1 vs. Version 5.0?

If a client sends a WebSocket command which is not even syntactically valid JSON, is there any means for the server to indicate this:

• i.e. send an error message back,
• or close the WebSocket connection from the server side,
• or can it only just ignore the command?

How about if the command message is valid JSON, and also validates against one of the command schemas (or better, the top-level one proposed in #35 (comment)), but is semantically invalid - e.g. one of the specified "sources" in a subscription command doesn't exist?

I am imagining it might be worth defining an error message type in Message types, with a payload of the NMOS core error type? (I see no harm in reusing HTTP status codes here.)

Some clarification of command error handling would be good in v1.0.x documentation, but adding an error response has to wait for v1.1, I guess!

The examples of event types in the documentation for measurements and enum include "number/temperature/C", "boolean/enum/OnOff" and "string/enum/DeviceStatus".

None of these event types validate against the regexes in the respective schemas which are all like:

        "event_type": {
          "description": "Event type",
          "type": "string",
          "pattern": "^number(?:\\/[a-zA-Z_\\-])*$"
        },

I assume the regex is missing a + and the intention is actually "^number(?:\/[a-zA-Z_\-]+)*$" (which with backslashes escaped for json becomes "^number(?:\\/[a-zA-Z_\\-]+)*$").

I can also imagine people wanting to refer to specifications, especially in the naming of enumerated types, as things like "string/enum/st-9999-19/meow" so I'm surprised by the omission of numerical digits from the allowed character ranges?

I'm also not sure whether it is intended to allow type name elements like a single - or __meow__?

(Finally, I'm not sure that indicating a non-capturing group with ?: is necessary or useful since this is a spec rather than an implementation.)

Follow up to #32 and #33.

According to Core models, each Sender is uniquely associated with a Source and a Flow (as per the NMOS Content Model). But according to Transport - Websocket - connection_uri, multiple Senders will share the same "connection_uri", and the subscription command allows multiple Sources to be requested. The WebSocket connection thus actually combines multiple Flows.

How then are the "source_id" and "flow_id" meant to be set in the "identity" in the WebSocket message?

The IS-07 specification for the IS-05 "externally defined transport parameters", ext_is_07_rest_api_url and ext_is_07_source_id in Transport - Websocket - Connection management and Transport - MQTT - Connection management needs to indicate whether or not "auto" is permitted in a PATCH /staged request.

It would also be nice to have an example of the "enum" constraint that should be included in the /constraints endpoint for each of these, e.g. to show that the ext_is_07_source_id is a fixed value (or "auto" if that is to be permitted).

See also AMWA-TV/is-05#71.

The EventsAPI.raml explicitly defines 404 as a possible response status code for

/sources/{sourceId}

It should also do so for

/sources/{sourceId}/type
/sources/{sourceId}/state

Compare e.g. IS-05 Connection API

/single/senders/{senderId}/constraints

I'm copying a few comments here that I originally sent via e-mail, just so they're a bit easier to track and resolve. Responses from @cristian-recoseanu are noted underneath in italics.

1. connection_lost - I didn't understand this at first. I’d suggest adding a brief description and/or link to MQTT WILL. My interpretation (having read other docs) is that the connection_lost is sent on startup to tell the broker what to send out to clients if an ungraceful disconnect is detected. This intentionally has no timing data as it isn't known when it will get sent out (I wondered why this was missing at first). Do you also need to specify the topic this will be sent to? This may be the same topic as used for normal messages.

• Your assumption is correct. Should we link to a more detailed explanation of MQTT WILL messages? The topic used is the same across all messages and is defined in the IS-05 parameter “broker_topic”

2. I’d suggest being clear that for WebSocket comms, even though there is one URL, each client gets its own communication channel with unique data. This is probably the standard expectation for a WebSocket, but it threw me slightly at first and I suspect it would throw others too.

• Ok so basically clarify that each connection is independent and considered its own unique sessions with unique subscriptions and events sent?

3. The example event type bool/enum/OnOff seems inconsistent, should it be boolean/enum/OnOff?

• Well spotted. That is indeed a mistake.

4. I’d appreciate recommendations for frequency of access to the API to get bounds of a numeric event type for example. Is this allowed to change over its lifetime without disconnecting all clients - it may be easier if not, then a client knows to re-query this upon reconnection?

• I’m not sure I fully understand this one. Could you give an example?

5. Be clear with wildcards that you can't do stuff like number/Tempera* or number/*/C. I assume the * should replace whole fields only and always goes at the end?

• Understood. The documentation does mention the wildcard always goes at the end.

6. I’d suggest re-wording the core models section slightly to assume that those changes are already part of IS-04/05 and specify the version of 04 and 05 required (v1.3 and v1.1 respectively).

• Would that require we have the feature requests logged on Github for both IS-04 and IS-05? Is your suggestion to still keep the section to highlight the changes but write it as if it had already happened?

7. Remove AMQP from core models diagram

• Again well spotted

8. 'channels' needs removing from the core models Source example as this relates to the 'audio' schema

• Understood

9. Is _nmos-mqtt TCP or UDP? Guessing it should be '_nmos-mqtt._tcp'? Others seem to use _mqtt._tcp, should we be using that too, or is there a reason you'd want a specific NMOS MQTT server?

• It is indeed TCP. I think we wanted to be clear that it is the MQTT broker which is involved in NMOS. I don’t know what the odds are of a customer already having an MQTT broker or not.
  I don’t have a strong opinion on this and we just made a decision so we could move on with the work. Would you recommend using the simple _mqtt._tcp instead?

Related to #36. Like #37, possibly this is a question for IS-04.

The example in Core models - IS-04 highlights - Senders shows "manifest_href": "". If JSON schema validation is applied to this example (using IS-04 schemas/sender.json), it should fail validation due to the empty string not being a valid uri.

This is not an issue as much as a couple of questions about how to use the events and tallys described in IS-07. In particular, how to associate an event or tally with a specific Audio/Video sender and/or receiver. I am trying to figure out how to adapt IS-07 to an existing system. There are a couple of issues which I would like some input on.

In our existing system, we have what we call LIOs. They are just binary signals so they are not as rich as what is in IS-07. We have what are called Input LIOs which correspond to something like pushing a button. We also have Output LIOs which correspond to lighting a light or doing some other action. Each LIO has a direction (input or output) and a Function. (e.g. On Tally, Off Tally)

Each audio signal (senders and receivers) can have a number of associated LIOs which can be a mixture of Input and Output LIOs and various functions. When an audio sender and receiver are connected, then the LIOs on the two signals are matched so that an Input LIO with a specific function on one signal is matched to one or more Output LIOs of the same function on the other signal.

As an example, a receiver signal on an audio surface corresponding to a fader might have an Input LIO with a function of On Tally. The fader could be connected to a sender signal like a microphone with an Output LIO with the same function. When the On button on the fader is pressed, the Input LIO is set to On and causes an OnAir light associated with the Output LIO of the sender signal to be turned on. In the opposite direction, a Cough button associated with the microphone would be an Input LIO on the microphone signal and would be matched with an Output LIO on the fader signal and the associated fader would essentially mute the audio from the microphone while the cough button is pressed.

My first question is how to associate the events and tallys in IS-07 with specific Audio senders and receivers. This may not be intended to be covered in IS-07 and if this is the case, where is it covered? A facility could have several faders and several microphones and they would all have LIOs so the need to associate each of these LIOs with specific faders and microphones seems important.

My second question is how to determine who has "control" of an output LIO. In the example used above, the microphone signal sending the audio has an Output LIO for turning on an OnAir sign. If the microphone happens to be connected to several faders on different surfaces, the question becomes which of those surfaces controls the OnAir sign? We have taken the approach that the fader receiver on the surface can be "locked" or "unlocked" and only "locked" signals can have exclusive control of the output LIOs on the microphone. If there are more than one "locked" signals that the microphone is connected to, then the first connected "locked" signal has LIO control. A queue of locked receivers is kept so that as receivers become disconnected or unlocked, then the next receiver in the queue has LIO control. If all connected receivers are unlocked, then no receiver has exclusive LIO control and behavior may be hard to predict. So the question is whether there is any facility in IS-07 or elsewhere for arbitrating which event source an event receiver should listen to?

My apologies if these questions are not appropriate here.

Thanks.

This may be more of a question for IS-04.

The example in Core models - IS-04 highlights - Senders shows "interface_bindings": [ "eth0" ].

Does it make sense for Senders with transports like WebSocket or MQTT to be bound to a particular interface?

If so, in an out-of-band configuration (separate media and control networks) which network would WebSocket/MQTT flows be likely to use?

This is upsetting the jsonref package that I'm using to resolve $ref for the documentation build.

Compare: WebSocket Transport - Heartbeats

With: Writing WebSocket servers - Pings and Pongs: The Heartbeat of WebSockets

Spec: RFC 6455 Section 5.5.2-3

Since "event_type" is only available via the Sender's IS-07 Events API /type endpoint or a request for the IS-04 Source/Flow, or once the first event message is received, a Receiver cannot easily reject a Sender of the wrong event type during a Connection API request to PATCH /staged.

The current design therefore puts the onus firmly on the controller/client to ensure it does not connect incompatible senders and receivers. I think using the "transport_file" has been discussed but rejected.

This issue is just added to confirm my understanding is correct, and note this area for possible enhancement in the future.

The schemas/type_number.json schema has an optional "scale" field. However, each of the "min", "max", and "step" fields is a number, i.e. as defined by the schemas/number.json schema, which itself has an optional "scale" field.

The examples, eventsapi-v1.0-type-number-get-200.json and eventsapi-v1.0-type-number-measurement-get-200.json, and the similar ones in the docs at Event types - Base types - number, either do not use "scale" at all, or use three identical values in the "min", "max", and "step" fields rather than the top-level "scale".

Questions:

• Is the spec intended to allow "min", "max", and "step" fields each with different "scale"?
• If a top-level "scale" is specified in the type definition, can it be overridden by the values on the "min", "max", and "step" fields?
• If a top-level "scale" is specified, does that have any effect on the payload values in the source's events/state, or only the "min", "max", and "step" fields?
• Do all events for a source have to have the same "scale"? E.g. is it OK to send { "value": 200, "scale": 10 } one time, and { "value": 20 } another time?

Thanks!

On the final line of the RAML, '/state' has a type of 'type: Event'. Unfortunately this type is not defined at the top of the RAML file under 'types', so the test suite is unable to find the correct schema to test against.

This could be an https://github.com/AMWA-TV/nmos-device-connection-management issue, but IS-07 is the only WebSocket transport user so far...

Should the /transportfile endpoint on the Connection API for IS-07 Events WebSocket Senders always return 404?

Transport - Websocket - Connection logic flow Step 1 refers to websocket_href. That name isn't used anywhere else in the repo, so I assume it's a typo for connection_uri (and a little funny that I already (#33) suggested ws_href might have been less confusing name).

(Originally #40 (comment)...)

There's a little typo in event-types-capability-management.png of 'Celcius' instead of 'Celsius' repeated a few times. We've also now settled on number/temperature in the examples rather than number/Temperature so I'd like to change that, and number/Pressure similarly.

@cristian-recoseanu Were the images produced with something like https://www.draw.io/ so they can easily be regenerated by anyone? (Draw.io embeds the editable graphic objects/text/etc. into a PNG extension, so the PNG can be edited again without having to store a separate file.)

Number state payloads in IS-07 have a value which may be integer or floating point, and a scale which is a positive integer (or 1 if omitted).

The number type defines 'min', 'max' and 'step'.

Are the specified 'min' and 'max' values inclusive or exclusive? I'm assuming both inclusive?

The 'step' value is optional. The schema doesn't define a default but the documentation at Event types - number says the default is 1.

That seems awkward with floating point values?

I.e. is the following example valid, or would I need to add e.g. "step": { "value": 0.5 }?

/type

{
  "type": "number",
  "min": { "value": 4.2 },
  "max": { "value": 5.7 }
}

/state

{
    "event_type": "number",
    "payload": { "value": 4.7 }
}

The documentation uses both "number/temperature/C" and "number/Temperature/C" as examples (differing just in the case of the initial letter of the measurement name element).

The regex for event type allows mixed case, but I haven't found any guidance in the specification as to whether event type names should be compared case-sensitive or not? Measurement units guidelines - Case sensitive behaviour only covers the units.

https://github.com/AMWA-TV/nmos-event-tally/blob/v1.0/docs/6.0.%20Event%20and%20tally%20rest%20api.md#2-nmos-resource

For consistency the href url offered will always end with a trailing slash.

is in direct contradiction with

https://github.com/AMWA-TV/nmos-discovery-registration/blob/v1.2.1/docs/2.0.%20APIs.md#urls-approach-to-trailing-slashes

For consistency and in order to adhere to how these APIs are specified in RAML, the 'primary' path for every resource has the trailing slash omitted.

(See also AMWA-TV/is-04#87, and AMWA-TV/is-05#65.)

(Somewhat related to #32...)

This could be just me, but I find the naming of the "connection_uri" transport parameter a bit confusing. In my understanding, this is nothing to do with the URL of the IS-05 Connection API, but is rather a WebSocket-scheme URL for the IS-07 Events WebSocket API?

I wonder if a name like "ws_href", as also used in the IS-04 Query API to refer to the Query WebSocket API, would have been more appropriate (possibly with a longer prefix)?

Secondly, would it be possible to relax and/or document the rationale for the constraint that "all of the senders on the same device will host the same uri" (and use conformance language to clearly indicate whether this is required or recommended)?

One quite minor point: the use of the paths .../device_id/... in the example "connection_uri" values is unusual with respect to other NMOS specs - .../devices/... might have been more consistent.

It would probably also be a good idea to include a sentence or two similar to the following paragraph from Creating a Websocket subscription in the IS-04 documentation:

"There is no mandated URL base path for servers to use when creating websocket connections. Instead clients should observe the value of 'ws_href' which is returned by their subscription request in order to identify what to connect to."