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

Clean up Comment vs UserComments vs CommentAction #170

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

Clean up Comment vs UserComments vs CommentAction #170

vholland opened this issue Nov 18, 2014 · 16 comments
Assignees

Comments

@vholland
Copy link
Contributor

@vholland vholland commented Nov 18, 2014

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
Copy link

@samuelgoto samuelgoto commented Nov 18, 2014

Here is a generalization of this issue: #172

@elf-pavlik
Copy link
Contributor

@elf-pavlik elf-pavlik commented Nov 18, 2014

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
Copy link
Contributor Author

@vholland vholland commented Nov 19, 2014

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
Copy link
Contributor

@elf-pavlik elf-pavlik commented Nov 19, 2014

👍 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
Copy link

@samuelgoto samuelgoto commented Nov 19, 2014

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
Copy link
Contributor

@danbri danbri commented Apr 29, 2015

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

@vholland
Copy link
Contributor Author

@vholland vholland commented Apr 30, 2015

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

@danbri
Copy link
Contributor

@danbri 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 added a commit to vholland/schemaorg that referenced this issue May 1, 2015
@vholland
Copy link
Contributor Author

@vholland 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
Copy link
Contributor

@elf-pavlik elf-pavlik commented May 1, 2015

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
Copy link
Contributor Author

@vholland 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 added a commit that referenced this issue May 1, 2015
Issue #170: Removed UserComments as an expected type for http://schema.o...
@danbri
Copy link
Contributor

@danbri 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
Copy link
Contributor

@danbri 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
Copy link
Contributor

@danbri 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
Copy link

@GaryJones GaryJones commented May 14, 2015

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
Copy link
Contributor Author

@vholland vholland commented May 14, 2015

Yes. Thanks for the example!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
6 participants
@GaryJones @danbri @samuelgoto @elf-pavlik @vholland and others
You can’t perform that action at this time.