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

Comments

Projects
None yet
5 participants
@vholland
Contributor

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

This comment has been minimized.

Show comment
Hide comment
@samuelgoto

samuelgoto Nov 18, 2014

Here is a generalization of this issue: #172

samuelgoto commented Nov 18, 2014

Here is a generalization of this issue: #172

@elf-pavlik

This comment has been minimized.

Show comment
Hide comment
@elf-pavlik

elf-pavlik Nov 18, 2014

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."

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@vholland

vholland Nov 19, 2014

Contributor

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@elf-pavlik

elf-pavlik Nov 19, 2014

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@samuelgoto

samuelgoto 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 !

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

This comment has been minimized.

Show comment
Hide comment
@danbri

danbri Apr 29, 2015

Contributor

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

Contributor

danbri commented Apr 29, 2015

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

@vholland

This comment has been minimized.

Show comment
Hide comment
@vholland

vholland Apr 30, 2015

Contributor

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

Contributor

vholland commented Apr 30, 2015

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

@danbri

This comment has been minimized.

Show comment
Hide comment
@danbri

danbri Apr 30, 2015

Contributor

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.

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

This comment has been minimized.

Show comment
Hide comment
@vholland

vholland May 1, 2015

Contributor

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.

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

This comment has been minimized.

Show comment
Hide comment
@elf-pavlik

elf-pavlik May 1, 2015

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

Contributor

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

This comment has been minimized.

Show comment
Hide comment
@vholland

vholland May 1, 2015

Contributor

@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.

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 added a commit that referenced this issue May 1, 2015

Merge pull request #466 from vholland/comment-cleanup
Issue #170: Removed UserComments as an expected type for http://schema.o...
@danbri

This comment has been minimized.

Show comment
Hide comment
@danbri

danbri May 1, 2015

Contributor

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.

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

This comment has been minimized.

Show comment
Hide comment
@danbri

danbri May 1, 2015

Contributor

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

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

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

This comment has been minimized.

Show comment
Hide comment
@danbri

danbri May 12, 2015

Contributor

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!

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

This comment has been minimized.

Show comment
Hide comment
@GaryJones

GaryJones 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?

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

This comment has been minimized.

Show comment
Hide comment
@vholland

vholland May 14, 2015

Contributor

Yes. Thanks for the example!

Contributor

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