W3C home > Mailing lists > Public > public-dxwg-wg@w3.org > October 2019

Wording for Functional Profiles in Conneg

From: Karen Coyle <kcoyle@kcoyle.net>
Date: Tue, 8 Oct 2019 17:53:55 -0700
To: "public-dxwg-wg@w3.org" <public-dxwg-wg@w3.org>, Annette Greiner <amgreiner@lbl.gov>
Message-ID: <82d2a1a4-5d1c-02b7-8ed3-c54e87b5fe4f@kcoyle.net>
All,

At the meeting today we resolved to finalize the wording for functional
profiles in Conneg, with the goal of making clear the status of the
profiles described in the document. I took an action to note the current
wording, which will be reviewed by the group (in particular by Annette
who had questions in this area).

The Functional Profiles are described in section 7 of the document. [1]
The opening paragraph of section 7.1 [2] states:

"This section describes functional profiles of this specification's
Abstract Model which are implementations of it in different
environments. These functional profiles are formally identified in § 7.2
Conformance to Functional Profiles and are to be used as conformance
targets for specific implementations of systems within different
environments wishing to conform to this specification."

kc: I think that the phrase "are to be used" implies that these profiles
are required. Perhaps changing this to "may be used" would be more
accurate. In fact, the whole could be edited as:

"This section illustrates a few conformant functional profiles of this
specification's Abstract Model for different system environments. These
functional profiles are formally described in § 7.2 Conformance to
Functional Profiles and may be used within different environments
wishing to conform to this specification. Implementation of the profiles
illustrated here is not mandatory; any profile that conforms to the
Abstract Model fulfills conformance to this document."

There is a note in section 7.1 that reads:

"Implementers of Content Negotiation by Profile need not ensure systems
conform to multiple functional profiles of this specification. They need
only conform to the functional profile(s) relevant to their environment.
In some cases, for example the Query String Argument-relevant human
browser environment, there is a choice of more than one functional
profile. Since all functional profiles of this specification themselves
must conform to this specification, by design, conformance to any
functional profile guarantees conformance to the specification."

kc: Again, the third sentence here makes it sound like these are THE
functional profiles that one must implement. I suggest using this note
to clarify that these are only a sample of possible profiles:

"The functional profiles provided here are conformant with the abstract
model. Systems may implement one or more of the profiles provided in
this document or may develop other functional profiles that conform to
the abstract model. Conformance to one of the profiles provided here
guarantees conformance to the abstract model, but conformance can be
achieved with other functional profiles. Implementers of Content
Negotiation by Profile need not ensure systems conform to multiple
functional profiles of this specification, they need only conform to the
functional profile(s) relevant to their environment."

The second paragraph of section 7.2 [3] reads:

"Figure 2 is not an exhaustive list of functional profiles of this
specification and users MAY make additional functional profiles for
different environments, as described in the previous section."

kc: The use of "additional" here sounds like one must implement THESE
profiles PLUS others. Changing from "additional" to "other" removes that
ambiguity.

Is this sufficient to clarify the optional nature of the functional
profiles? It would be great if some of you would read through the
remainder of section 7 and see if you find other areas that could use
editing. Also, I realize that there is redundancy in the edits I have
made; if it seems to be too much we can try to reduce that.

Thank you,

kc
[1] https://w3c.github.io/dxwg/conneg-by-ap/
[2] https://w3c.github.io/dxwg/conneg-by-ap/#functional-profiles
[3] https://w3c.github.io/dxwg/conneg-by-ap/#conformance-profiles
-- 
Karen Coyle
kcoyle@kcoyle.net http://kcoyle.net
skype: kcoylenet
Received on Wednesday, 9 October 2019 00:54:02 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 30 October 2019 00:15:58 UTC