From W3C Wiki

This is an archived WebSchemas proposal Comment type for schema.org. See Proposals listing for more. Note: active schema.org development is now based at github


We have an issue tracking problems with UserComments, specifically that ""Comment is under UserInteractions not CreativeWork; the former focus on aggregation"."

  • Schema.org has a UserComments class, which defines properties commentText, commentTime, creator, discusses ('Specifies the CreativeWork associated with the UserComment.'), replyToUrl
  • It's a UserInteraction, which is a kind of event. Many have asked for a simple 'Comment' class that describes the result of that event.
  • This topic is somewhat complicated since other UserInteraction subclasses are aggregates.
  • The schema.org team agreed to move ahead with this proposal on 2012-03-09, details to be worked out here (see action in tracker)

Core Proposal

Proposal finalised in thread leading to march 8th agreement:

  • Add a 'Comment' type, a subclass (e.g. like Review) of CreativeWork.
    • A comment on an item - for example, a comment on a blog post.
  • Clarify that the existing UserComments class represents the UserInteraction event that creates it.
  • Add a 'text' property to the CreativeWork class, whose value is the Text of the work (and hence of the comment); loosely analogous to the 'audio' and 'video' properties of CreativeWork.
  • Note that this (to some extent) this generalises the articleBody property from Article and the reviewBody property from Review, rather than adding another class-specific property for Comment.
  • Note that the 'text' property's value is plain text rather than markup, due to Microdata's datamodel restrictions; defer any attempt at markup-valued properties for later work.


  • Do we have a property linking a UserComments instance (ie. some UserInteraction) to its resulting Comment?
    • not directly proposed at this time
    • note that each UserComments interaction event can have a 'discusses' link to the CreativeWork being commented upon.
    • note that the resulting Comment (itself also a CreativeWork) will typically be 'about' that same CreativeWork
    • it seems plausible to expect the dateCreated of the Comment to usually match the commentTime of the UserComments event; however, perhaps spam filtering processes might mean this differ?
  • Do we have any comment-specific properties, or CreativeWork gives us all we need.
    • "author," "headline," and (proposed addition) "text" are inherited from CreativeWork (amongst other useful properties); also "about": for a Comment, if it points to an item, the comment is about that item.
  • Address here also other confusions around the UserComments class, such as that its siblings are aggregates and the example goofy?
    • can be dealt with separately.
  • Recursion; how useful is existing "discusses" for linking comments in a thread, since a Comment is a legitimate CreativeWork now?
    • "discusses" retains its original purpose (links event of a comment to the thing commented on); 'about' links a Comment CreativeWork to the other Work it comments upon. The latter is more applicable to threaded chains of Comments.
  • Alginment with other current work

See also examples from Drupal/SIOC for potential vocabulary around Comment.


This came up previously, but most recent discussion:

  • Comment versus UserComments, from Daniel Dulitz:
    • "I wanted to raise an issue about how to represent comments (e.g. on blog posts).
    • There are many subtypes of CreativeWork, but Comment is not one of them. Perhaps it should be?
    • Instead, it seems like comments are to be represented by UserComments, which is a subtype of UserInteractions. But apart from UserComments those types appear to be for aggregates, not for an individual comment/tweet/like/etc. The type names are plural and don't really fit for non-aggregates.
    • I think the aggregate types are useful, but for each aggregate type I'd like to have a clearly defined type for the individual thing. What's the right way to achieve that?"
  • Stéphane Corlosquet
    • I agree that Comment would be a relevant type to be added to schema.org. There was a similar discussion on the previous mailing list where this topic was discussed, in particular the confusion around markup of the aggregates. I'm pasting some of the conversation below. See also the whole http://schema.org/UserInteraction inconsistency problems thread.
    • Note that since its launch in January 2011, Drupal 7 exposes each individual comment and the aggregate number of comments in RDFa using the SIOC vocabulary, so I'd love to see a schema.org equivalent for both individual comments and the aggregate number of comments for a given (blog) post.
  • Dan Brickley
    • mentioned (but won't advocate for, and nobody supported) an alternate design: "Even though we don't assert that Comment is subclass of CreativeWork, we also don't anywhere assert that no comments are CreativeWorks. It might be there are some idioms where treating some comments as creative works in this way is useful.
  • Adrian Giurca

... indicates a general consensus towards the design documented here: a new class. How much can we agree about what to add alongside it? properties?

Example sites

These example sites show the kind of markup we hope will adopt this vocabulary.