Clean up Comment vs UserComments vs CommentAction #170

Closed
vholland opened this Issue Nov 18, 2014 · 16 comments

Projects

None yet

5 participants

@vholland
Contributor

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 #137)
  • final check that /docs/releases.html represents these changes clearly.
@samuelgoto

Here is a generalization of this issue: #172

@elf-pavlik
Contributor

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
Contributor

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

@vholland vholland closed this Nov 19, 2014
@vholland vholland reopened this Nov 19, 2014
@elf-pavlik
Contributor

👍 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 danbri self-assigned this Jan 21, 2015
@danbri danbri added this to the sdo-gozer release milestone Jan 21, 2015
@vholland vholland assigned vholland and unassigned danbri Apr 9, 2015
@danbri
Contributor
danbri commented Apr 29, 2015

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

@vholland
Contributor

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

@danbri
Contributor
danbri commented Apr 30, 2015

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 #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 vholland added a commit to vholland/schemaorg that referenced this issue May 1, 2015
@vholland vholland Issue #170: Removed UserComments as an expected type for http://schem…
…a.org/comment, added http://schema.org/resultComment, and deprecated http://schema.org/language.

Remaining work is to deprecate UserInteraction and all of its children and http://schema.org/interactionCount.
d6f3c22
@vholland
Contributor
vholland commented May 1, 2015

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
Contributor

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
Contributor
vholland commented May 1, 2015

@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
Contributor
danbri commented May 1, 2015

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
Contributor
danbri commented May 1, 2015

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

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

@danbri
Contributor
danbri commented May 12, 2015

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!

@danbri danbri closed this May 12, 2015
@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
Contributor

Yes. Thanks for the example!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment