Clean up Comment vs UserComments vs CommentAction

[vholland]

http://schema.org/Comment
http://schema.org/CommentAction
http://schema.org/UserComments

Schema.org currently has three overlapping types:

Comment: A subtype of CreativeWork described as "A comment on an item". Oddly enough, it does not allow for including the body of the comment. One can only describe the comment (e.g. author, date published, etc.)

CommentAction: "The act of generating a comment about a subject." It also does not include the body of the comment.

UserComments: A subtype of UserInteraction. It is the "event" of commenting. The only way to include the comment body.

The only place where Comment and UserComments are used as an expected type is on the "comment" property of CreativeWork.

This is all very confusing and should be cleaned up.

Status (May 1) for sdo-gozer

TODOs before closing this issue

• first phase implemented, see http://sdo-gozer.appspot.com/docs/releases.html#sdo-gozer
• update the text of UserComment + markup with deprecated:True or whatever #465 resolves
• deprecate UserInteraction and all of its children; also interactionCount (cf replace interactionCount with interaction #137)
• final check that /docs/releases.html represents these changes clearly.

[samuelgoto]

Here is a generalization of this issue: #172

[elf-pavlik]

Comment: A subtype of CreativeWork described as "A comment on an item". Oddly enough, it does not allow for including the body of the comment. One can only describe the comment (e.g. author, date published, etc.)

I think for body of the comment one can use: http://schema.org/text "The textual content of this CreativeWork."

[vholland]

Good point, re: schema.org/text. We need better examples so authors know to use that property.

[elf-pavlik]

👍 writing more examples!

To get started I'll prepare another PR with example I send out to mailing list. It uses Comment as result of CommentAction: http://lists.w3.org/Archives/Public/public-vocabs/2014Nov/0101.html

[samuelgoto]

SGTM

On Wed, Nov 19, 2014 at 8:10 AM, ☮ elf Pavlik ☮ notifications@github.com
wrote:

[image: 👍] writing more examples!

To get started I'll prepare another PR with example I send out to mailing
list. It uses Comment as result of CommentAction:
http://lists.w3.org/Archives/Public/public-vocabs/2014Nov/0101.html

—
Reply to this email directly or view it on GitHub
#170 (comment).

f u cn rd ths u cn b a gd prgmr !

[danbri]

Noting discussion in #137 and expectation that interactionCount will go away. Shall we monitor that departure here?

[vholland]

SGTM. I would like to take this up again once sdo-gozer is complete.

[danbri]

Oh, I was talking about closing #137 since it is somewhat covered by this issue #170, which I thought we would try to address during gozer.

Do we have rough consensus that

• UserComments (as a weird kind of action) is supercededBy http://schema.org/CommentAction
• Its functionality is also somewhat replaced by existence of http://schema.org/Comment - this should be mentioned
• We need to confirm that we are ok with keeping the relation http://schema.org/comment and type http://schema.org/Comment (the former is listed in Consider renaming generic types and properties #417 ).
  • We need new text for UserComments explaining this.
  • We need to remove or rework any examples using UserComments.
  • The general result of an Action is indicated with the 'result' property. We have the convention of defining sub-properties of these generic relations to make type-specific vocabulary more usable. However that doesn't work when the property also has a non-Action usage too, i.e. we wouldn't want to declare 'comment' a subPropertyOf 'result'.
  • This leaves us with a gaping hole: how do we point from a CommentAction to the resulting Comment? either 'result', or 'comment'? The former works today, the latter would need an extension to domain of comment.
  • If UserComment is marked somehow as superseded or deprecated, we should avoid advertising it on the per-property page like http://schema.org/comment ( -> file a new python/site impl issue)

I believe this issue tracks the "what to do about Comment vs CommentAction's relationship", and #138 tracks everything else relating to removal of the UserInteraction terms.

[vholland]

I'm trying to make progress on this. I created pull request #466, which:

1. Removed http://schema.org/UserComments from the range for http://schema.org/comment.
2. Updated the description of http://schema.org/creator to no longer mention UserComments.
3. http://schema.org/language supersededby http://schema.org/inLanguage.
4. Added http://schema.org/resultComment to http://schema.org/CommentAction.
5. Cleaned up the CommentAction example.

@danbri Once we have decided on how to deprecate without replacement, I would like to deprecate UserInteraction and its children, including UserComments as mentioned in issue #138.

/cc @elf-pavlik who I don't see on this thread, but has expressed interest in other, overlapping threads.

[elf-pavlik]

Do you plan to create for each FooAction type a matching resultFoo property? ATM I really don't understand why not simply use generic result.
https://lists.w3.org/Archives/Public/public-vocabs/2014Nov/0101.html

[vholland]

@elf-pavlik It's not my intention to create a resultFoo for every FooAction, but I think it is useful to have subproperties where people will almost certainly want a result of a specific type. The Action model can be confusing for authors, so handholding on common use cases can be helpful.

[danbri]

Thanks @vholland. I've merged this initial step, and updated docs/releases.html to remember what we did. The language/inLanguage one might be a good nudge for us to document how to use controlled strings vs Language and properties (which?) of that type. I'll leave this issue open as we have a bit more yet to do on deprecation via #465.

[danbri]

http://sdo-gozer.appspot.com/docs/releases.html#sdo-gozer

I've updated the issue description above with some final TODOs

[danbri]

I'm going to close this. For now the deprecation is handled in human-facing text. We have other bugs tracking deprecation-related infrastructure so I'll close this. Thanks all!

[GaryJones]

Please forgive me if this isn't the right place for this question, but do the changes enacted here basically result in this change of markup?

[vholland]

Yes. Thanks for the example!