I am hoping to close several tickets, including #2062 very soon. This one “needs discussion”, IMHO, only on the issue of whether or not deprecation is required. Could folks weigh in on the ticket, please?

Issue: the @key attribute of <specDesc> is optional in the schema, but required by the Stylesheets. The request is to require it in the schema, too.

Decision (unilateral, by me): yes, we should make @key of <specDesc> required by the schema.

Question: Do we have to provide deprecation for this change?

Discussion 1: The <specDesc> element “indicates that a description of the specified element or class should be included at this point within a document”. The @key attribute is the only mechanism by which the element or class you want to be included can be indicated. Therefore a <specDesc> without a @key is not doing what it is supposed to do. Currently, a <specDesc> without a @key passes validation, but then when processed by the Stylesheets the message “ERROR: no key attribute on specDesc” is generated (by Stylesheets/common/common_tagdocs.xsl); processing continues, and the spot where the @keyless <specDesc> occurred is simply blank in the output HTML.

Discussion 2: We have decided in the past that, in general, changes that break backward compatibility should be deprecated. (I.e., users should get a warning, not an error, for 6 months to 2 years before the feature is changed to an error.)

My opinion (on the question “Do we have to provide deprecation for this change?”): Emphatically not, this is a corrigible error. The change only effects when the user gets an error message, not if. One of the main reasons to have schema validation is to catch errors before you get to the processing stage.