search

AMWA-TV / is-07

AMWA IS-07 NMOS Event & Tally Specification
https://specs.amwa.tv/is-07
Apache License 2.0
8 stars 6 forks source link

Rationale for schema "$id" URI values? #26

Open garethsb opened 5 years ago

garethsb commented 5 years ago

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?

mjeras commented 5 years ago

The only idea behind the URI was uniqueness within a single version, but I am happy to start the discussion to change to something resolvable. That particular URI was chosen mostly for readability, but an URN you suggest might be even better for this (I personally like the idea of URNs here). Could you please point us to the other NMOS specs where that has been used as an $id?

garethsb commented 5 years ago

Personally I don't see the need for the $id at the moment, since relative resolution via the filenames works OK in all the other specs?

Could you please point us to the other NMOS specs where that has been used as an $id?

Sorry, that's not what I meant. None of IS-04, IS-05, IS-06 and IS-08, use "$id" values. What I meant was that the specs use URNs like urn:x-nmos:... where a unique but non-resolvable identifier are required.

mjeras commented 5 years ago

I found it impossible to validate referenced schemas (in a folder) without the $id, at least with the tool I was using (Ajv: Another JSON Schema Validator) - without the ids the tool is not able to distinguish between the schemas. Again, I like the idea of using the URNs if possible so we might refactor this. The good thing is that it isn't a breaking change so should be doable easily...

garethsb commented 5 years ago

In my experience, not all implementations fully support the specification for structuring a complex JSON schema into multiple files using "$ref" and "$id". We ended up using one which now supports them properly, pboettch/json-schema-validator, and after that did not have any problems with the IS-04 or IS-05 schemas.

The Understanding JSON Schema 'book' guide to Structuring a complex schema - The $id property suggests that "it is best practice that every top-level schema should set $id to an absolute URI, with a domain that you control."

However, I think we should be consistent between all AMWA IS of NMOS, shouldn't we? So this is probably another 'NMOS Core' issue for the incubator.

mjeras commented 5 years ago

I would agree that is something to bring up at the NMOS Core. I don't think this is an urgent matter (to be done in the next week or so) as it works for now...

mjeras commented 5 years ago

Needs clarification on the NMOS level, perhaps under NMOS Core

garethsb commented 1 year ago

Discussed in ARG call, 7 July 2023, because schema $id, $ref came up while looking at AMWA-TV/is-11#129. We are thinking that canonical ids could be like https://specs.amwa.tv/<spec>/releases/v<major.minor.patch>/APIs/schemas/<schema.json> and the schema files be copied there as part of the render so that such identifiers are also locators. At this time, no other NMOS specification has explicit $id and we still need to decide policy on that.