Usage of Key words and Intro

[haudiobe]

2.3.1. Background DASH-IF generally provides interoperability guidelines for implementers. In doing so, DASH-IF agreed to use key words in order to support readers of the DASH-IF documents to understand better how to interpret the language. The usage of key words in this document is provided below.

2.3.2. Key Words The key word usage is aligned with the definitions in RFC 2119 [44], namely:

• SHALL: This word means that the definition is an absolute requirement of the specification.
• SHALL NOT: This phrase means that the definition is an absolute prohibition of the specification.
• SHOULD: This word means that there may exist valid reasons in particular circumstances to ignore a particular item, but the full implications must be understood and carefully weighed before choosing a different course.
• SHOULD NOT: This phrase means that there may exist valid reasons in particular cir-cumstances when the particular behavior is acceptable or even useful, but the full implica-tions should be understood and the case carefully weighed before implementing any be-havior described with this label.
• MAY: This word means that an item is truly optional. One vendor may choose to in-clude the item because a particular marketplace requires it or because the vendor feels that it enhances the product while another vendor may omit the same item. These key words are attempted to be used consistently in this document, but only in small letters.

2.3.3. Mapping to DASH-IF Assets If an IOP document associates such a key word from above to a content authoring statement then the following applies:

• SHALL: The conformance software provides a conformance check for this and issues an error if the conformance is not fulfilled.
• SHALL NOT: The conformance software provides a conformance check for this and issues an error if the conformance is not fulfilled.
• SHOULD: The conformance software provides a conformance check for this and issues a warning if the conformance is not fulfilled.
• SHOULD NOT: The conformance software provides a conformance check for this and issues a warning if the conformance is not fulfilled.
• SHOULD and MAY: If present, the feature check of the conformance software documents a feature of the content.

If an IOP document associates such a key word from above to a DASH Client then the following applies:

• SHALL/SHALL NOT: Test content is necessarily provided with this rule and the reference client implements the feature.
• SHOULD/SHOULD NOT: Test content is provided with this rule and the reference client implements the feature unless there is a justification for not implementing this.
• MAY: Test content is provided and the reference client implements the feature if there is a justification this.

Note that several requirements and recommendations are conditioned to a feature, and only if a whole feature is is in use, then the conditions apply.

This specification has a set of core features which are expected to provide full interoperability. If a DASH content author chooses to follow using the core features requirements in a published DASH service, that service is likely to experience successful playback on a wide variety of clients. A DASH client claiming conformance to the DASH-IF IOP guidelines are expected to implement all requirements and recommendations (unless justified why not) of core features.

In addition, the specification defines a set of optional features. Optional features may be implemented by clients, but if implemented, then all of the requirements are expected to be implemented. Optional features require clear capability signaling.

Each version of these guidelines may define a new set of core and optional features. There is no strict backward compatibility with previous versions - best practices change over time and what was once considered sensible may be replaced by a superior approach later on. Therefore, clients and services that were conforming to version N of this document are not guaranteed to conform to version N+1.

All DASH presentations are assumed to be conforming to IOP. A service MAY explicitly signal itself as conforming by including the string https://dashif.org/guidelines/ in MPD@profiles. If signaled, it is expected that the DASH presentation passes the conformance requirements of the DASH-IF conformance validator.

Note that conformance to multiple versions and profiles may be signaled. Conformance to all of the signaled profiles is required.

[sandersaares]

I don't see the need for all this text about assets and clients and the duplication of RFC2119 text. Everyone knows what SHALL/SHOULD mean, we should just refer to 2119 as is currently done, and add extra clarifications, as is currently done.

I am not saying any of the added text is invalid, just that it makes this chapter harder to read. Nobody is going to decipher a page of logic to find out how to interpret "SHALL" statements.

The text about conformance validation, if useful, should be in a separate conformance validator chapter or even in the documentation of the validation tool and not in IOP at all.

The text about clients is not useful to readers - this is more of an internal policy that DASH-IF might prefer to use and does not belong in IOP.

We have now moved past the core/optional features with the updated structure in #346 and just have normative interoperability requirements and (hopefully) informative descriptions, so I expect all the words about core/optional features are now obsolete.

I would also add a paragraph stating the principles we agreed in the July 24 call:

This document uses statements of fact (e.g. "is" and "can") when describing normative requirements defined in referenced specifications such as [[!MPEGDASH]] and [[!MPEGCMAF]]. [[!RFC2119]] statements (e.g. "SHALL" and "MAY") are used when this document defines a new requirement or further constrains a requirement from a referenced document.

[haudiobe]

Qualify the chapter for contributors or authors.

[sandersaares]

I believe this was addressed in August, with the "statements of fact" language. It has also been further iterated upon recently to annotate with specific examples, for hopefully even more clear readability.

I close the issue as I believe it is addressed. If something remains, please reopen or otherwise raise a comment.