Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Differentiating Functional & Data Profiling in Conneg #1022

Open
nicholascar opened this issue Jul 31, 2019 · 53 comments
Open

Differentiating Functional & Data Profiling in Conneg #1022

nicholascar opened this issue Jul 31, 2019 · 53 comments

Comments

@nicholascar
Copy link
Contributor

@nicholascar nicholascar commented Jul 31, 2019

Is the use of term "Functional Profile" confusing when the document describes options for functionality related to Data Profiles ?

@nicholascar nicholascar added this to the Conneg 3PWD milestone Jul 31, 2019
@nicholascar nicholascar self-assigned this Jul 31, 2019
@nicholascar

This comment has been minimized.

Copy link
Contributor Author

@nicholascar nicholascar commented Jul 31, 2019

Hi @aisaac, I totally agree with point 1 (more wording in the Note) so will work on that.

For point 2 (suggest that RRD and the abstract model are also a kind of "realization"): I'll chat to @rob-metalinkage & @larsgsvensson about this but see my proposal next.

For 3 (avoid term collisions by using "compliance" instead of "conformance") and part of 2 above: I suggest the opposite. We should consider reducing the number of terms here from Realizations to Profiles and deliberately use "conformance" (of system behaviour to a functional specification) in line with "conformance" (of data to a data specification). So the Abstract Spec & the 4/5 Realizations (depending on whether you count QSA twice) all just become Profiles of the Spec which systems (behaviour) can conform to. This is simplified and makes intuitive sense to me. As soon as we termed "things" (Realizations & Abstract Model) that someone might like to show conformance to Profiles, description of what's going on becomes easier. See the QSA part of the doc I'm now rewriting using Profile terminology in branch conneg-ACTION-343 (https://raw.githack.com/w3c/dxwg/conneg-ACTION-343/conneg-by-ap/index.html#qsa-key-naming).

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Jul 31, 2019

+1 @nicholascar

the whole exercise in trying to define "data profiles" without actually understanding what any form of profiles mean in practice has sucked so much time and energy out of the system - but it does at least give us a term to distinguish what is being negotiated about. The fact that we need a broader definition that includes functional behaviour to also explain conformance shows that we attacked the problem from the wrong end - in my experience data modelling is best done by understanding what things need unique identifiers and why, and then what distinguished them. Anyway - that horse has bolted and been eaten by wolves down the track..

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Aug 6, 2019

@rob-metalinkage where do you see that we "need" the more general definition? It's not in our charter, it's not in our use cases and requirements: we are not chartered to develop a framework that covers both data conformance and conformance of systems behaviours / functions. Of course we can do this, and I see some elegance if we manage to do it. And probably I can be open enough to even accept how the section is written. But I'm sure that a majority of the WG is going to not buy that and require new definitions to be approved etc... For example they could ask what's the connection between your (generalized) conformance "profiles" and conformance "levels" such as defined e.g. here https://www.w3.org/TR/WCAG21/#conformance-reqs . Not impossible, but it's going to require time.

If we don't need a unified theory, then going first for the safe way, not cross the streams, and just leave open the door to the unified theory in a note and to later times, seems more efficient for getting a new version of Conneg published fast.

In fact the time needed to work out the unified theory already shows in the editorial work needed, just within the Conneg document. At the time I'm writing this, the Conneg draft has an intro that is completely decent. But it's written in terms of conformance of "information" and "content" wrt to "information models". All this is at odds with that comes later in section 2.1, which is about compliance of systems functions. So you'd have to rewrite the intro, while this was not needed. And put the definitions for the unified theory first! In fact Section 2.1 itself makes a reference for "profile" which points to the "data specification" definition.
I understand you're maybe working on fixing all this as we speak, but I don't see the need for such a pain at this stage.

@nicholascar

This comment has been minimized.

Copy link
Contributor Author

@nicholascar nicholascar commented Aug 12, 2019

@aisaac we've put through a series of wording changes now so that what we previously called Realizations we now call Functional Profiles of the Conneg by P Specification. This both allows us to better indicate functional/data profile differences - and we have an improved note about the differences too - and also allows us to remove the term realization which we introduced in this document for no real benefit (when we could have just used functional profile).

Basically we just found that we were defining realization as functional profile anyway so why not just use the later term and save extra new terms?

The changes will be apparent shortly - when my W3C membership is renewed in a day or so to allow me to merge the now approved (by the other editors) but still unmerged PRs).

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Aug 12, 2019

@isaac - as evidenced by conneg, there are Use Cases that require this. Its true we didn't collect other Use Cases specifically for profiles of things like services, licencing conditions, service level agreements etc..

But its also good modelling - not to use general words to describe specific things which then means we force the world into one of three anti-patterns - confusing proliferation of similar terms with unguessable scopes, reuse of the same term with different meaning or overloading a model for a specific purpose by smuggling in microformats or violating declared semantics.

Given OGC has lots of service profiles and data profiles, and DCAT itself models DataServices, with allowed use of dct:conformsTo, the need for a general term is pretty clear - so if you think that more UC write up is needed to justify then that would the way to go.

This is the reason PROF is separate from both DCAT and Conneg-by-ap - so we can use sensible words without being bound to over-specific cases. Its actually a lot more work to justify a idiosyncratic scope. The equivalent is the (now deprecated) practice of using narrow owl:domain declarations for properties, which stop them being used in places they may have exactly the same semantics except applying to a different object type that the original designer thought about.

I think our conneg-by-ap edits navigate this issue - and we can introduce a DataProfile sub-class into PROF to help align scopes without crippling the model's ability to support DCAT and other use cases.

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Aug 13, 2019

Also note in the DCAT spec:

Each service is characterized by its general type using dct:type (here using values from the INSPIRE spatial data service type vocabulary), its specific API definition using dct:conformsTo

...which clearly indicates that specifications (target of dct:conformsTo) may be functional (API) in this case...

@agreiner

This comment has been minimized.

Copy link
Contributor

@agreiner agreiner commented Aug 15, 2019

I think introducing yet another use of the term "profile" is going to make this even more difficult for users to understand. It's both the anti-patterns of similar terms proliferating and reuse of the same term with different meaning.

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Aug 15, 2019

introducing the narrower concept of a "data profile" is the "yet another" case - however since people have such difficulty understanding the wider context of profiles it could help to identify data profiles as a sub-class of profiles. (All community usages of the term are within the narrow context of the community - we just need to get over ourselves if we think we can take over meaning of a word by adopting an idiosyncratically narrow definition.)

@nicholascar

This comment has been minimized.

Copy link
Contributor Author

@nicholascar nicholascar commented Aug 16, 2019

Addressed at length in the document, PR 1037 and others with inclusion of extended explanatory not in Section 2.1 Profiles for Conformance and re-naming of Realization to Functional Profile.

@nicholascar nicholascar added this to To do in Content Negotiation by Profile via automation Aug 16, 2019
@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Aug 27, 2019

@nicholascar how is that addressed at length by PR #1037 ? I'm looking at https://raw.githack.com/w3c/dxwg/conneg-ACTION-356/conneg-by-ap/index.html#conformance-profiles but section 2.1 is still called "Profiles for conformance" (while it could be called "functional profiles" to clarify) and the first occurrence of "profiles" in that section has an hyperlink to https://raw.githack.com/w3c/dxwg/conneg-ACTION-356/conneg-by-ap/index.html#dfn-profile which is our regular "data profile"!

In addition, now that I'm looking to this preview of the document, I am getting more in line with @agreiner 's earlier comment. It is really, confusing to have a document called "Content Negotiation by Profile" and have this document start by discussing profiles that are not the ones that are being negotiated!

This is in fact reflected in the current note, which I think is rather correct but ends up saying that the specification is only about functional profiles:
This specification describes how a system should behave and this section indicates different profiles of that behaviour, rather than content (data).
while the key motivation for Conneg is data profiles!

By the way the note also hyperlinks "profiles" to the definition of "data profiles", which is wrong and "specification" to our definition of spec (basis for comparison etc.), which is not wrong but unnecessarily recursive (what does the reader gain from being refered to this definition, while it's mostly useful for defining the data profiles and their 'profiling' behaviour?)

Content Negotiation by Profile automation moved this from To do to Done Aug 27, 2019
@aisaac aisaac reopened this Aug 27, 2019
Content Negotiation by Profile automation moved this from Done to In progress Aug 27, 2019
@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Aug 27, 2019

I'm re-opening because I think that the current text (especially the hyperlinks) do blur the differentiation between functional and data profiles.
And in fact now I realize that as long as the title of the document is "content negotiation by profile" it is going to be very difficult to do a differentiation between the profiles of the "by profile" and other types of profiles. Sorry I should have spotted this in the first place, as an essential showstopper.

For the record (because I also raised this other point in the original comment) I can live with how the document currently talks about conformance/compliance.

@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Aug 28, 2019

Since we've re-opened, I remove due-for-closing. (Obviously there isn't consensus on that...)

@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Sep 12, 2019

@aisaac scripsit:

And in fact now I realize that as long as the title of the document is "content negotiation by profile" it is going to be very difficult to do a differentiation between the profiles of the "by profile" and other types of profiles. Sorry I should have spotted this in the first place, as an essential showstopper.

Does that mean that it would be resolved if we called the document "Content Negotiation by Data Profile"?
Although as @rob-metalinkage says: "Content Negotiation implies data"

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 13, 2019

@larsgsvensson yes this would be the clean way to name the spec, if we would want to avoid the ambiguity with the functional profiles.
And I'm not sure what to do with "Content Negotiation implies data" yes in a way it's true that one would expect data rather than functional profiles. But on the other hand one could also expect "Content Negotiation by Profile" to be about some kind of "Content Profiles". Our "Data Profiles" are not "Content Profiles", though. So the reader will need a clear rendition of what "Profiles" are. And if one of the first parts she sees in the document is about profiles that are really not the ones being negotiated, this is not super helpful.

NB: I shall re-iterate the problem with the editorial issues (esp. the hyperlinks) I've spotted earlier. The problem between functional profiles and the title is big, but if the hyperlinks were not in, it would already be smaller!

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Sep 20, 2019

I cant see why "data profiles" and "content profiles" (an undefined concept) would not be exactly the same thing? the content of a data transfer is data....

An insistence that in the general world "profiles" only applies to data is not correct, nor helpful, nor relevant to the specification - but we should explore editorial changes to help people understand that it is necessary to use the concept of profiles in terms of conformance to options in the specification and this is not the same scope as profiles of data being negotiated over. On the other hand - thats really not that complex a concept to grasp - and some degree of understanding that data and services are different things can surely be assumed?

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Sep 20, 2019

the hyperlink goes to a definition which does not say "data" - so its not broken - except that it does not include "functional profiles" in the list - but we could improve the text there IMHO - to make it clear that the context will make it clear what type of profile is being considered.

something like this would be better IMHO:

This definition includes both "data profiles" (when applied to data specifications) and "functional profiles" (when applied to behaviours of services). "Data profiles" are sometimes called "application profiles", "metadata application profiles", or "metadata profiles". This document describes functional profiles of service behaviour with respect to negotiation about choice of data profiles. The context determines how "profiles" should be interpreted in each case.

@nicholascar

This comment has been minimized.

Copy link
Contributor Author

@nicholascar nicholascar commented Sep 20, 2019

"Content Negotiation by Data Profile"

Please no! We have the HTTP Headers using just Accept-Profile and the QSA FP using _profile not Accept-Data-Profile or _dataProfile and so on. In the same way, even if the sense for the whole doc is about data profiles, I'd prefer to stick to just "Profile". I already fought this battle once before for "Application Profiles"...

@kcoyle

This comment has been minimized.

Copy link
Contributor

@kcoyle kcoyle commented Sep 20, 2019

I think it's too late to add a new concept (functional profiles). I'll read the draft, though, for clarity around the word "profile".

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Sep 20, 2019

no its too late to try to make an arbitrary change of scope

@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Sep 20, 2019

Trying to summarise the discussion and the contentious points:

@aisaac thinks the current text (§2.1) blurs the line between data profiles and functional profiles, particularly since the text in the note in §2.1 (that is about functional profiles) has a hyperlink to the general definition of "profile" and not to a specific definition of "functional profile". He goes on to say:

And I'm not sure what to do with "Content Negotiation implies data" yes in a way it's true that one would expect data rather than functional profiles. But on the other hand one could also expect "Content Negotiation by Profile" to be about some kind of "Content Profiles". Our "Data Profiles" are not "Content Profiles", though. So the reader will need a clear rendition of what "Profiles" are. And if one of the first parts she sees in the document is about profiles that are really not the ones being negotiated, this is not super helpful.

and

NB: I shall re-iterate the problem with the editorial issues (esp. the hyperlinks) I've spotted earlier. The problem between functional profiles and the title is big, but if the hyperlinks were not in, it would already be smaller!

@agreiner agrees with Antoine

I think introducing yet another use of the term "profile" is going to make this even more difficult for users to understand. It's both the anti-patterns of similar terms proliferating and reuse of the same term with different meaning.

@rob-metalinkage suggests to fix this by adding the following text to the definition of profile:

This definition includes both "data profiles" (when applied to data specifications) and "functional profiles" (when applied to behaviours of services). "Data profiles" are sometimes called "application profiles", "metadata application profiles", or "metadata profiles". This document describes functional profiles of service behaviour with respect to negotiation about choice of data profiles. The context determines how "profiles" should be interpreted in each case.

@larsgsvensson suggests to clarify this by re-naming the document to "Content Negotiation by Data Profile". @nicholascar and @rob-metalinkage oppose to that.

And thinking about it again (and reading the document) my new take would be that the best way to solve this might be to move what is now §2.1 into its own section further down. This would solve two problems:

  1. Readers are not immediately confronted with the concept of functional profiles. If we add that further down, they will have a chance to understand the general concepts first.
  2. As it is now, §2.1 is not normative content. In §2 it says "For the purpose of compliance, the normative sections of this document are Section 3, Section 6, Section 7 and Section 8."

I also +1 @rob-metalinkage's suggestion for the text change to the definition of profile.
And in addition to that, I suggest that we mark everything connected to functional profiles as feature-at-risk. Then it will be easier to remove that if we cannot agree.

What do you think?

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 22, 2019

The reason the group also ended up defining only data profiles was that the majority didn't believe in a more general notion of profile. It is quite telling that the issue #963 opened to revise the definition of "profile" ended up only with a definition of "data profile". If there was agreement on focusing on a general "profile", then the end result of the discussion would have been a definition of "profile".

About points re. "syllogistic", "Realisation is ugly and crosses into other uses of the word realisation", I really don't understand the logic. The definition of data profile is not a syllogism. Especially, if there's a syllogism in there, then the offered definition of the more general notion of profile should have one, considering how they are close to each other. And using "profile" for realization does cross into other uses of the word "profile", which are actually right in the document where the use of "profile" for "realization" is proposed, which is way worse.

This being said, and trying to follow up on the proposal to accommodate the definition of "data profile", there might be a way keep functional profiles while minimizing the confusion:

  1. keep our notion of data profile and clearly presenting that as the profiles that are the object of content negotiation
  2. make sure that every reference to functional profiles is spelled out "functional profile" and not "profile", leaving the shorter form free to be used for the references to "data profile".
  3. no try to present a unifying framework, which again is not needed for the document to work. Or if it's done it should be only in the lightest manner, in the "definitions" section, by having next to a definition of "data profile" the generalized definition for "profile" (the one that is currently in the editor's draft, which is close enough to the one of "data profile" that it won't be objected to, hopefully). And if you want you may have one for "functional profile" (and I think this could be a job for a PR, i.e. after CR).

In fact wrt 2 it may be better if we would never used the shortened form, making sure each notion is properly spelled out each time is mentioned. This would also make it easier for a future WG to systematically change the spec to accommodate a different (wider?) notion of profile if they've got the use cases for it.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 22, 2019

Sorry I forgot to say that my proposal would come in addition to putting the section on functional profiles further down in the document as discussed above (e.g. here).
I still think it would read much better in the opening of the current section 7.
And section 2 on conformance can still work well if the section 2.1 on functional profiles is replaced by one sentence that would refer to the new subsection of section 7. This by the way would tackle a basic editorial flaw of section 2. It is always odd to have a section with only one subsection (what's the purpose of making it a subsection then?).

@kcoyle

This comment has been minimized.

Copy link
Contributor

@kcoyle kcoyle commented Sep 23, 2019

@aisaac said: "And if you want you may have one for "functional profile" (and I think this could be a job for a PR, i.e. after CR)"

We will need to confirm with Philippe, but my feeling is that modifying the examples (not just moving the text in the document) goes beyond the allowed "editorial changes" that would be allowed on a CR. Instead, the document as it is today is the document that would be published as a recommendation. If more changes are needed that calls into question the readiness for CR.

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Sep 23, 2019

The syllogism is not within the definition of data profile - its trying to make it apply to all the other notions of profile in the world that are not covered by its scope. What this WG was able to come to grips with doesnt actually change the world outside its experience.

anyway I agree with @aisaac's proposal - this doesnt require "modifying" anything normative or anything substantial in any examples - looks like it may be necessary to explicitly disambiguate terminology usage and not rely on the reader understanding the context to interpret it. +1 also to move section 2.1 into into to 7 and then drop a pointer to it in a cleaner section 2 - agree again that probably flows a bit better and doesnt change or invalidate the sense of anything.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 23, 2019

@rob-metalinkage great. So you'd agree as well that we can have every occurrence of the notion of "functional profile" spelled out as such? So we could have a way out our issue, if others would be ok with that approach.

@kcoyle my "one" in "may have one for 'functional profile'" was refering to a definition, not an example. Considering that we would add a definition, not change an agreed definition, I believe it would be ok for Philippe. Unless you really meant to type "definition" and you think we couldn't add a new definition? Well, anyway I believe that a definition for "functional profiles" is not necessary to the spec. Having the explanations of section 2.1 given in a new sub-section of section 7 would probably be enough, and not confusing because of the well-bounded context of section 7. It's just that I wanted to tell editors that I wouldn't object to them adding a definition for "functional profile" if they strongly want to do it. (and again, I believe this could be done between CR and PR)

@rob-metalinkage thank for the explanation on syllogism. I am still very puzzled hoewever. The act of consensus in #963 was not "trying to make it apply to all the other notions of profile in the world that are not covered by its scope". On the contrary, we chose to restrict the scope by focusing on data profiles, not trying to address other kind of profiles. It was rather like creating a firebreak and focus on our key stuff. Quite unlike the "world-dominating" approach you saw in it, apparently.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 24, 2019

@agreiner @kcoyle @rob-metalinkage @nicholascar @andrea-perego let me try to recap the current proposal for keeping functional profiles in a way that would minimize confusion (copying and slight re-wording material from previous comments):

  1. keep our notion of "data profile" in the definitions and clearly present data profiles as the profiles that are the object of content negotiation
  2. make sure that every reference to functional profiles in the document is spelled out as "functional profile" and not "profile", leaving the shorter form usable for the references to "data profile".
  3. not try to present a complete, unifying framework, which again is not needed for the document to work. If a generalization is offered to readers it should be done only in the lightest manner: i.e. in the "definitions" section, there could be a generalized definition for "profile" (the one currently in the editor's draft is close enough to the one of "data profile" that it won't be objected to, hopefully) and maybe a definition for "functional profile" (which I think could be a job for a PR, i.e. after CR). These would sit next to a definition of "data profile", not replacing it.
  4. putting the section on functional profiles (currently 2.1) further down in the document, i.e. in the opening of the current section 7. And section 2 on conformance would refer to the new subsection of section 7 instead of presenting functional profiles itself.

I am aware that form of support for some of these elements has already been voiced, and reluctance to some of them has been voiced too. But this has happened in different comments or even outside of github. Hopefully putting everything here will help make all that visible and progress towards a solution.

@agreiner

This comment has been minimized.

Copy link
Contributor

@agreiner agreiner commented Sep 24, 2019

If you would leave references to functional profiles in the body of the document (they are currently all over the place), then moving the explanation of what that means to later in the document leaves a lot of unexplained references. I don't think that quick fix works.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 24, 2019

Good point @agreiner . But I am less worried about this. Most of the references to functional profiles between section 2 and 7 seem to be about specific functional profiles (e.g. "QSA functional profile"). And honestly for these references, whether they were using "realization" or functional profile, as a reader I was always forward-looking into the proper sub-section to understand what it was about anyway.
My point is that at least when reading these references I didn't remember scratching my head, wondering what editors might have said. I just went to the specific section. What really puzzled me was the generic introduction in 2.1, as in this position it was much less clear whether the profiles mentioned there were about what's conneg'ed or not.
I hope I'm making some sense. It's getting late...

@kcoyle

This comment has been minimized.

Copy link
Contributor

@kcoyle kcoyle commented Sep 24, 2019

Was a clear definition of "functional profile" developed? That's my big problem - I don't see it defined, and I honestly cannot understand what is meant by the term. If the definition results in something that is not directly related to our definition of "profile" then I am concerned that the use of "profile" will cause confusion.

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Sep 24, 2019

@kcoyle you may have created any confusion with a definition of data profile if you think that the nature of profiling only applies to data just because you have used it in that context in such a definition. Functional profiling has exactly the same definition except it applies to functional behaviour. We just repeat the words without the stipulation it applies to data. Messy but consistent. We now need to spell out the difference every time rather than leave it to the reader to understand the subject of each referencing to profiling, but thats just an ugliness we can live with.

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Sep 24, 2019

Anyway - we cant really leave out references to functions in a specification about functionality...

@kcoyle

This comment has been minimized.

Copy link
Contributor

@kcoyle kcoyle commented Sep 24, 2019

Not asking to remove functions, just asking for a clear definition for the reader. We defined data profile; now we need a definition of functional profile. That shouldn't be controversial, since W3C documents generally provide definitions of key terminology used in the document. If there is no difference in the definitions, then it isn't clear to me why "functional" profiles are singled out in the text, and not just called profiles. There is either one meaning or two, and if two, a second definition is needed.

@kcoyle

This comment has been minimized.

Copy link
Contributor

@kcoyle kcoyle commented Sep 25, 2019

My main problem is that there seem to be two different uses of profile being discussed in the document, and it would be much less confusing if these were not both called profile. The document is content negotiation by profile, and in that sense it refers to the requested resource that is a profile (not just a specification, but a profile). So that's the target of the content negotiation. Then it refers to " profiles of this specification's Abstract Model which are implementations of it in different environments" which are functions of the content negotiation implementation, NOT the resources that are the target of the content negotiation. Even worse is that within that there is reference to the first type of profiles. I have not generally heard of functions like the ones described here referred to as "profiles." I think it is a stretch to call these "A specification that constrains, extends, combines, or provides guidance or explanation about the usage of other specifications." They are specifications, but I unless EVERY specification meets that definition, then I don't think that these do.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 25, 2019

I also would prefer if functional profiles would be called differently, but I can live with having them named like this if the document handles it well.

As for definitions, I can quite comfortably live with a definition section that would include something like this:

data profile
A data specification that constrains, extends, combines, or provides guidance or explanation about the usage of other data specifications.
profile
A specification that constrains, extends, combines, or provides guidance or explanation about the usage of other specifications.
This "Content Negotiation by Profile" specification concerns negotiation for data profiles, and specifies functional profiles for different ways of achieving this.

where "functional profiles" in the above would point (directly or via a pointer added to definition in the same section for functional profiles) to section 7 where they are explained. Indeed as a reader I would actually not care much about how/whether a definition is given for functional profiles. I would just want to see what they are.

@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Sep 25, 2019

There are updated definitions for functional profile etc. available that should solve this issue. In the current ED, the definition for "functional specification" is missing; that has been addressed in #1097 but that one cannot be merged until they wake up again in Australia... There is a preview available.

Further, the section on functional profiles has been moved from §2.1 (conformance...) to §7.1 Functional Profiles of this specification and §7.2 Conformance to Functional Profiles, addressing @aisaac's comments.

PROPOSED: Accept the definitions in the current ED amended by the one added in #1097 as a solution for the definitions.
Accept the relocation of the section on conformance to functional profiles from §2.1 to new sections §7.1 Functional Profiles of this specification and §7.2 Conformance to Functional Profiles as a solution to the question of where to put functional profiles.

Please vote thumbs-up or thumbs-down.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 25, 2019

Sorry I don't have time to review tonight anymore. But if the current ED addresses all the proposals at #1022 (comment) (including the spelling out of all mentions of functional profiles as "functional profiles" in the text) then I'm happy with closing this issue!

@kcoyle

This comment has been minimized.

Copy link
Contributor

@kcoyle kcoyle commented Sep 25, 2019

@larsgsvensson I took a quick read of it and I'm much happier now that there is a definition there. It all makes it much clearer. Thank you.

@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Sep 26, 2019

@aisaac scripsit:

Sorry I don't have time to review tonight anymore.

Given the outcome of the vote, you can take your time... It would feel good to close this issue, though.

@aisaac

This comment has been minimized.

Copy link
Contributor

@aisaac aisaac commented Sep 26, 2019

Thanks a lot, @larsgsvensson ! I am happy with the changes but would still suggest some minor editorial changes to make the definitions (and the document) work even better:

  • "This Content Negotiation by Profile specification concerns negotiation for data profiles, and specifies functional profiles for different ways of achieving this." could be complemented by "In this document, most occurrences of the term "profile" refer to "data profile"." (as this is just what happens: my previous idea to use "data profile" for every occurrence of that notion would cause the document to be very tedious to read!)
  • "Source: deliberations of the DXWG." could be removed from the definitions of functional specification and functional profile
  • I would recommend to hyperlink from "specifies functional profiles" in the definition of "profiles" to section 7.1 "#functional-profiles-definition" #functional-profiles-definition. Or to hyperlink to the definition of "functional profiles" in the same definition section, and ensure that there is an hyperlink from that definition to 7.1 (but it would be a bit trickier, i.e. adding a couple extra words to work as anchor, while the previous solution uses an anchor that already exists).

Then there are plenty small glitches and not-ideal hyperlinks, which could be fixed (sorry I'm not giving the section numbers. I guess a search for the sentences will work just as well...):

  • "DTDs, XML Schema, vocabularies or other standards, specifications or profiles" should hyperlink to the definition of "data profiles" not profile.
  • "What these tools call a view is analogous to a profile", ditto
  • "(analogous profiles, as described in this document)" would work better as "(analogous to data profiles, as described in this document)", maybe with an hyperlink to the right definition.
  • "Implementations of this Abstract Model for different environments are called Functional Profiles and to be a valid functional profile" would work better with the hyperlink to the definition put on the first occurrence of "functional profile"
  • "A data model for describing the representations of a resource that conform to different profiles" would be clearer as "A data model for describing the representations of a resource that conform to different (data) profiles"
  • "A client requesting the representation of a resource conforming to a profile MUST identify the resource by a Uniform Resource Identifier (URI) [RFC3986] and MUST identify the profile either by a URI or a token." should have the hyperlink to the definition of "data profile" not "profile"
  • "it MUST unambiguously identify the profile" same remark. Or just remove the hyperlink, as there are already 2 in the same (short) subsection.
  • "a client requests the list of URIs of profiles", "a server responds to a client with the list of URIs of the profiles", "a server responds with either a specific profile for a resource conforming to a requested profile identified by the client or it responds with a default profile", "A client wishes to know for which profiles a server", "The list profiles request MAY result in a response in one of a number of formats, provided that the profiles", "A server MUST NOT list profiles", "a resource that is claimed to conform to a profile", "one of any number of profiles" : ditto
  • "Order of Precedence for Implementation Profiles" should probably be "Order of Precedence for Functional Profiles" and be moved to section 7 (at the end of it probably)?
  • "if other profiles of the abstract model" should be "If other functional profiles of the abstract model"

I've stopped at the beginning of section 7. I could continue but I guess you get the idea :-)

@larsgsvensson

This comment has been minimized.

Copy link
Contributor

@larsgsvensson larsgsvensson commented Sep 30, 2019

@aisaac Your proposed changes have been merged in #1101, except for the following:

What I haven't addressed is his suggestion to remove "Source: deliberations of the DXWG" from the definitions of functional specification and functional profile (I think we need to discuss sources anyway...), and also I haven't moved "Order of precedence for Implentation Profiles" to 7.1 since @nicholascar will probably touch that section anyway given the discussion in #544 (comment)

Can you please review that and see if you're happy with the outcome?

@agreiner

This comment has been minimized.

Copy link
Contributor

@agreiner agreiner commented Oct 24, 2019

Sorry, but I still think it is a mistake to introduce a new usage of the term "profile" in this specification. Realization was a fine term, as far as I'm concerned. I understand that the word profile can be used to refer to different styles of implementing content negotiation by profile, but it is still a poor choice in a document in which users have struggled to understand the concept of a profile. I've not yet heard any argument why using the term profile in both senses in the same document is a good idea, just defense of it as not being a fallacy.

@rob-metalinkage

This comment has been minimized.

Copy link
Contributor

@rob-metalinkage rob-metalinkage commented Oct 24, 2019

This is not a "new usage" at all - OGC publishes profiles - and they are usually functional profiles of services bound to data profiles of standard data schema. We cant just keep inventing or narrowing scope of terms because we dont understand some wider context. Explicitly clarifying scope each time we use a term (which is IMHO unnecessary because a reader really ought to be able to understand when data is being talked about) is an acceptable compromise to remind people with a narrow experience base that other senses for such terms exist.

@agreiner

This comment has been minimized.

Copy link
Contributor

@agreiner agreiner commented Oct 24, 2019

By "new usage" I mean usage of the phrase "functional profile" to identify what you used to call a "realization" of conneg. But that's really beside the point. Your only argument here is clear, that profiles can have a meaning beyond data profiles. We all understand that. What I'm arguing for is thinking about what will help readers who are less familiar with profiles than we are to understand the specification. The goal of the document is not to teach them the possible uses of the term "profile"; it's to explain conneg by data profile specifically. A well crafted document anticipates potential points of confusion for readers. We should strive not to be dismissive of their needs.

@kcoyle

This comment has been minimized.

Copy link
Contributor

@kcoyle kcoyle commented Oct 24, 2019

I agree with @agreiner about confusion for the reader. I have a vague memory that this is also discussed elsewhere but can't find it at the moment. I think the question, as Annette puts it, is whether the use of functional profile is absolutely necessary given the potential for confusion. I don't understand the insistence on this term when at least three of us (Annette, Antoine, and myself) have argued against it. The OGC practice is not enough to prove a general case. Can we cast our net wider to attempt to determine how this term might be read by an audience? Perhaps in our call for review of the next WD we could ask specifically for readers to look at this and say whether they found it confusing. This kind of question is in part what outside review is good for.

@nicholascar

This comment has been minimized.

Copy link
Contributor Author

@nicholascar nicholascar commented Nov 6, 2019

Original descirption for this issue was:

From @aisaac in PR #1018:

what I'd like to see is more wording like the one in the Note, which says this is about "functional" profiles and not "data" profiles. If this is about profiles for content negotiation, couldn't we directly call them "negotiation profiles"? Or "realization profiles", as these things are called "realizations"

(and yes, I'd be even ready to suggest that RRD and the abstract model are also a kind of "realization" to make this happen, and also to have you use the infamous recursive trick again ;-) )

Similarly we could also try to avoid term collisions by using "compliance" instead of "conformance", with the understanding that "compliance" would be used to express how a system (not data) adheres to some specification. Or perhaps even better, as this part is about systems implementing realizations of the models, the term 'implementation' could be used. I know this is in a section about conformance (to CONNEG) but I don't see much harm in claiming that conformance to CONNEG can be obtained by having systems "implement" (or comply with) one of the realizations of the abstract model (or the abstract model itself).

I'm removing that to trim the body size down in the 3PWD and phrasing the body as a question for 3PWD review.

@nicholascar

This comment has been minimized.

Copy link
Contributor Author

@nicholascar nicholascar commented Nov 19, 2019

This Issue added to ED in PR #1165 for 3PWD.

@nicholascar nicholascar modified the milestones: Conneg 3PWD, 4PWD Nov 27, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
6 participants
You can’t perform that action at this time.