page_structured_data 1.0.11 → 1.0.13

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9ffd04020a9a4ba900bb7d4bbdac9dd827d48535073a30c657865469df9e1988
-  data.tar.gz: 4b560fee8a434599acd2ae619fdc7e4a0973f29aa77f8b95191a270047767931
+  metadata.gz: 8e263a2b3ad541c2b5e72aa79e71d47d72803ddb8a4ac286898e6c6f35105394
+  data.tar.gz: 96f01f8fc820456eb69ba5a351f8971022758088d0a5633240c38c7831df43f9
 SHA512:
-  metadata.gz: '08329eddfdf9f7e3682a6016ca84d25b1867e4ce8ebca4c4e7654536b4dff59b8d825351b4489b69342c42d2cc52ab41d96bba1f3cc8adf5a1f8180330d660ba'
-  data.tar.gz: 270c98e7c0071b9e09e75482a5d766ec685f8a7da103c3ddb15f4df03e895b98fcc52d57e50b93cbfddd992de7d0fbdf6d5de9542b07fec52d0eab977da2903f
+  metadata.gz: 802b70166a18b5475e702822cfb7b0c565c7fc59d8dd5059831261676831e1150c95b8f0e1e11b0de493aa120f3e23f2ddd9a619238ebcdd5f25c8f3920d3d6e
+  data.tar.gz: bc818be71ea5d603ac3fb6b84e99dcf79fd76607f3272039cde49d65c772f365d812c0f7d260cdf7beda88762012994ae207b309e7a5dc21b94ab129608e0c9e

data/CHANGELOG.md

@@ -4,6 +4,20 @@ All notable changes to this project are documented here.
 
 ## Unreleased
 
+## 1.0.13 - 2026-05-06
+
+- Add `PageStructuredData::PageTypes::Person` for reusable schema.org person values.
+- Accept richer article author values and omit blank nested schema fields.
+- Add page-level `base_app_name` and `render_breadcrumb_json_ld` options.
+- Omit blank description and image meta tags.
+
+## 1.0.12 - 2026-05-06
+
+- Add reusable interaction statistics for article-like page types.
+- Add `PageStructuredData::PageTypes::DiscussionForumPosting` for forum-style posts.
+- Render Twitter Card meta tags with `name` attributes.
+- Update gem metadata to mention Organization and WebSite JSON-LD support.
+
 ## 1.0.11 - 2026-05-06
 
 - Add optional `description` and `founder` support to organization page types.

data/README.md

@@ -14,6 +14,9 @@ It helps Rails applications render:
 - Google-compatible JSON-LD structured data
 - Breadcrumb structured data
 - Article structured data for `BlogPosting` and `NewsArticle`
+- Discussion forum post structured data
+- Interaction statistics for public engagement counts
+- Reusable Person structured data
 - Organization and WebSite structured data
 
 ## Requirements
@@ -141,6 +144,8 @@ PageStructuredData includes page types for:
 
 - [`BlogPosting`](https://schema.org/BlogPosting)
 - [`NewsArticle`](https://schema.org/NewsArticle)
+- [`DiscussionForumPosting`](https://schema.org/DiscussionForumPosting)
+- [`Person`](https://schema.org/Person)
 - [`Organization`](https://schema.org/Organization)
 - [`WebSite`](https://schema.org/WebSite)
 
@@ -173,6 +178,42 @@ article_page_type = PageStructuredData::PageTypes::BlogPosting.new(
 
 For news pages, use `PageStructuredData::PageTypes::NewsArticle` with the same arguments.
 
+Article-like page types can include public engagement counts as interaction statistics:
+
+```ruby
+article_page_type = PageStructuredData::PageTypes::BlogPosting.new(
+  headline: @article.title,
+  published_at: @article.published_at,
+  updated_at: @article.updated_at,
+  likes_count: @article.likes_count,
+  comments_count: @article.comments_count,
+  shares_count: @article.shares_count
+)
+```
+
+Only include engagement counts that are public and visible on the rendered page.
+
+Use `DiscussionForumPosting` when the current page represents a public user-authored forum or community post:
+
+```ruby
+forum_post_page_type = PageStructuredData::PageTypes::DiscussionForumPosting.new(
+  headline: @post.title,
+  text: @post.content_plaintext,
+  url: post_url(@post),
+  published_at: @post.created_at,
+  updated_at: @post.updated_at,
+  authors: [
+    {
+      name: @post.user.name,
+      url: user_url(@post.user)
+    }
+  ],
+  interaction_statistics: [
+    PageStructuredData::PageTypes::InteractionStatistic.comment(@post.comments_count)
+  ]
+)
+```
+
 Use `Organization` when the current page represents an organization:
 
 ```ruby
@@ -238,10 +279,15 @@ PageStructuredData::Page.new(
   page_type: nil,
   page_types: nil,
   canonical_url: nil,
-  fallback_image: nil
+  fallback_image: nil,
+  base_app_name: nil,
+  render_breadcrumb_json_ld: nil
 )
 ```
 
+`base_app_name` overrides `PageStructuredData.base_app_name` for one page. Pass an empty string to suppress the global app name for a specific page.
+`render_breadcrumb_json_ld` can be set to `true` or `false` for one page. Leave it as `nil` to use the global `PageStructuredData.render_default_breadcrumb_json_ld` behavior for generated default breadcrumbs. Explicit breadcrumb objects still render when the global default is disabled unless the page sets `render_breadcrumb_json_ld: false`.
+
 Important methods:
 
 - `page_title`: returns the composed page title.
@@ -272,7 +318,15 @@ PageStructuredData::PageTypes::BlogPosting.new(
   published_at:,
   updated_at:,
   images: [],
-  authors: []
+  authors: [],
+  image: nil,
+  article_body: nil,
+  text: nil,
+  url: nil,
+  interaction_statistics: [],
+  likes_count: nil,
+  comments_count: nil,
+  shares_count: nil
 )
 ```
 
@@ -282,17 +336,94 @@ PageStructuredData::PageTypes::NewsArticle.new(
   published_at:,
   updated_at:,
   images: [],
-  authors: []
+  authors: [],
+  image: nil,
+  article_body: nil,
+  text: nil,
+  url: nil,
+  interaction_statistics: [],
+  likes_count: nil,
+  comments_count: nil,
+  shares_count: nil
 )
 ```
 
-`authors` should be an array of hashes with `:name` and `:url` keys.
+`authors` can be an array of hashes, `PageStructuredData::PageTypes::Person` objects, or other objects that respond to `to_h`.
+`image` is a convenience option for one image URL. Use `images` when passing multiple image URLs.
+`text` is an alias for `article_body`.
+`interaction_statistics` should be an array of `PageStructuredData::PageTypes::InteractionStatistic` objects or schema-compatible hashes.
 
 Important methods:
 
 - `to_h`: returns a structured hash for article JSON-LD.
 - `json_ld`: returns an article JSON-LD script tag.
 
+```ruby
+PageStructuredData::PageTypes::DiscussionForumPosting.new(
+  headline:,
+  published_at:,
+  updated_at:,
+  images: [],
+  authors: [],
+  image: nil,
+  article_body: nil,
+  text: nil,
+  url: nil,
+  interaction_statistics: [],
+  likes_count: nil,
+  comments_count: nil,
+  shares_count: nil
+)
+```
+
+### Interaction Statistics
+
+```ruby
+PageStructuredData::PageTypes::InteractionStatistic.new(
+  interaction_type: :like,
+  user_interaction_count: 42,
+  interaction_service: nil
+)
+```
+
+Convenience constructors are also available:
+
+```ruby
+PageStructuredData::PageTypes::InteractionStatistic.like(42)
+PageStructuredData::PageTypes::InteractionStatistic.comment(12)
+PageStructuredData::PageTypes::InteractionStatistic.share(7)
+```
+
+Supported shorthand interaction types are `:like`, `:comment`, and `:share`. Custom schema.org action types can be passed as strings or hashes.
+
+Important methods:
+
+- `to_h`: returns a structured hash for `InteractionCounter` JSON-LD.
+
+### Person
+
+```ruby
+PageStructuredData::PageTypes::Person.new(
+  name:,
+  url: nil,
+  image: nil,
+  same_as: []
+)
+```
+
+Use `Person` for article authors, organization founders, and other schema.org person values:
+
+```ruby
+author = PageStructuredData::PageTypes::Person.new(
+  name: "Jane Doe",
+  url: "https://example.com/jane"
+)
+```
+
+Important methods:
+
+- `to_h`: returns a compact structured hash for `Person` JSON-LD.
+
 ### Organization Page Type
 
 ```ruby

data/app/src/page_structured_data/page.rb

@@ -4,11 +4,11 @@ module PageStructuredData
   # Basic page metadata for any page
   class Page
     attr_reader :title, :description, :image, :extra_title, :breadcrumb, :page_type, :page_types, :canonical_url,
-                :fallback_image
+                :fallback_image, :base_app_name, :render_breadcrumb_json_ld
 
     def initialize(title:, description: nil, image: nil, # rubocop:disable Metrics/ParameterLists
                    extra_title: '', breadcrumb: nil, page_type: nil, page_types: nil, canonical_url: nil,
-                   fallback_image: nil)
+                   fallback_image: nil, base_app_name: nil, render_breadcrumb_json_ld: nil)
       @title = title
       @description = description
       @image = image
@@ -18,6 +18,8 @@ module PageStructuredData
       @page_types = page_types
       @canonical_url = canonical_url
       @fallback_image = fallback_image
+      @base_app_name = base_app_name
+      @render_breadcrumb_json_ld = render_breadcrumb_json_ld
     end
 
     def title_with_hierarchies
@@ -28,8 +30,8 @@ module PageStructuredData
 
     def page_title
       result = title_with_hierarchies.join(separator)
-      if base_app_name.present?
-        result += separator + base_app_name
+      if resolved_base_app_name.present?
+        result += separator + resolved_base_app_name
       end
       result
     end
@@ -52,13 +54,22 @@ module PageStructuredData
     end
 
     def breadcrumb_json_ld
+      return if render_breadcrumb_json_ld == false
       return breadcrumb.json_ld(current_page_title: title) if breadcrumb.present?
-      return unless PageStructuredData.render_default_breadcrumb_json_ld
+      return unless render_breadcrumb_json_ld?
 
       Breadcrumbs.new.json_ld(current_page_title: title)
     end
 
-    def base_app_name
+    def render_breadcrumb_json_ld?
+      return render_breadcrumb_json_ld unless render_breadcrumb_json_ld.nil?
+
+      PageStructuredData.render_default_breadcrumb_json_ld
+    end
+
+    def resolved_base_app_name
+      return base_app_name unless base_app_name.nil?
+
       PageStructuredData.base_app_name
     end
 

data/app/src/page_structured_data/page_types/article.rb

@@ -4,32 +4,42 @@ module PageStructuredData
   module PageTypes
     # Shared structured data for schema.org article-like page types.
     class Article
-      attr_reader :headline, :images, :published_at, :updated_at, :authors
+      include SchemaNode
 
-      def initialize(headline:, published_at:, updated_at:, images: [], authors: [])
+      attr_reader :headline, :images, :published_at, :updated_at, :authors, :article_body, :url,
+                  :interaction_statistics, :likes_count, :comments_count, :shares_count
+
+      def initialize(headline:, published_at:, updated_at:, images: [], authors: [], image: nil, article_body: nil, text: nil,
+                     url: nil, interaction_statistics: [], likes_count: nil, comments_count: nil, shares_count: nil)
         @headline = headline
-        @images = images
+        @images = image.present? ? Array(image) : Array(images)
         @published_at = published_at
         @updated_at = updated_at
-        @authors = authors
+        @authors = Array(authors)
+        @article_body = article_body || text
+        @url = url
+        @interaction_statistics = Array(interaction_statistics)
+        @likes_count = likes_count
+        @comments_count = comments_count
+        @shares_count = shares_count
       end
 
       def to_h
-        {
+        node = {
           '@context': 'https://schema.org',
           '@type': schema_type,
           headline: headline,
           image: images,
           datePublished: published_at,
           dateModified: updated_at,
-          author: authors.map do |author|
-            {
-              '@type': 'Person',
-              name: author[:name],
-              url: author[:url],
-            }
-          end,
+          author: authors.map { |author| author_to_h(author) },
         }
+
+        node[:articleBody] = article_body if article_body.present?
+        node[:url] = url if url.present?
+        node[:interactionStatistic] = interaction_statistics_to_h if interaction_statistics_to_h.any?
+
+        node
       end
 
       def json_ld
@@ -45,6 +55,46 @@ module PageStructuredData
       def schema_type
         raise NotImplementedError, "#{self.class.name} must define #schema_type"
       end
+
+      def author_to_h(author)
+        return object_to_h(author) if author.respond_to?(:to_h) && !author.is_a?(Hash)
+
+        compact_node(
+          '@type': 'Person',
+          name: author[:name] || author['name'],
+          url: author[:url] || author['url'],
+          image: author[:image] || author['image'],
+          sameAs: author[:same_as] || author[:sameAs] || author['same_as'] || author['sameAs']
+        )
+      end
+
+      def interaction_statistics_to_h
+        @interaction_statistics_to_h ||= all_interaction_statistics.map do |interaction_statistic|
+          if interaction_statistic.respond_to?(:to_h)
+            interaction_statistic.to_h
+          else
+            interaction_statistic
+          end
+        end
+      end
+
+      def all_interaction_statistics
+        interaction_statistics + count_interaction_statistics
+      end
+
+      def count_interaction_statistics
+        [
+          count_interaction_statistic(:like, likes_count),
+          count_interaction_statistic(:comment, comments_count),
+          count_interaction_statistic(:share, shares_count),
+        ].compact
+      end
+
+      def count_interaction_statistic(interaction_type, count)
+        return if count.nil?
+
+        InteractionStatistic.new(interaction_type: interaction_type, user_interaction_count: count)
+      end
     end
   end
 end

data/app/src/page_structured_data/page_types/discussion_forum_posting.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PageStructuredData
+  module PageTypes
+    # schema.org structured data for discussion forum posts.
+    class DiscussionForumPosting < Article
+      private
+
+      def schema_type
+        'DiscussionForumPosting'
+      end
+    end
+  end
+end

data/app/src/page_structured_data/page_types/interaction_statistic.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module PageStructuredData
+  module PageTypes
+    # schema.org InteractionCounter structured data.
+    class InteractionStatistic
+      include SchemaNode
+
+      ACTION_TYPES = {
+        like: 'LikeAction',
+        likes: 'LikeAction',
+        comment: 'CommentAction',
+        comments: 'CommentAction',
+        share: 'ShareAction',
+        shares: 'ShareAction',
+      }.freeze
+
+      attr_reader :interaction_type, :user_interaction_count, :interaction_service
+
+      def self.like(user_interaction_count)
+        new(interaction_type: :like, user_interaction_count: user_interaction_count)
+      end
+
+      def self.comment(user_interaction_count)
+        new(interaction_type: :comment, user_interaction_count: user_interaction_count)
+      end
+
+      def self.share(user_interaction_count)
+        new(interaction_type: :share, user_interaction_count: user_interaction_count)
+      end
+
+      def initialize(interaction_type:, user_interaction_count:, interaction_service: nil)
+        @interaction_type = interaction_type
+        @user_interaction_count = user_interaction_count
+        @interaction_service = interaction_service
+      end
+
+      def to_h
+        compact_node(
+          '@type': 'InteractionCounter',
+          interactionType: interaction_type_to_h,
+          userInteractionCount: user_interaction_count,
+          interactionService: object_to_h(interaction_service)
+        )
+      end
+
+      private
+
+      def interaction_type_to_h
+        return object_to_h(interaction_type) if interaction_type.respond_to?(:to_h)
+
+        type = ACTION_TYPES.fetch(interaction_type.to_s.to_sym, interaction_type.to_s)
+
+        { '@type': type }
+      end
+    end
+  end
+end

data/app/src/page_structured_data/page_types/organization.rb

@@ -4,6 +4,8 @@ module PageStructuredData
   module PageTypes
     # Organization structured data for a page
     class Organization
+      include SchemaNode
+
       attr_reader :name, :url, :description, :logo, :same_as, :parent_organization, :founder
 
       def initialize(name:, url:, description: nil, logo: nil, same_as: [], parent_organization: nil, founder: nil)
@@ -11,33 +13,23 @@ module PageStructuredData
         @url = url
         @description = description
         @logo = logo
-        @same_as = same_as
+        @same_as = Array(same_as)
         @parent_organization = parent_organization
         @founder = founder
       end
 
       def to_h # rubocop:disable Metrics/MethodLength
-        node = {
+        compact_node(
           '@context': 'https://schema.org',
           '@type': 'Organization',
-        }
-
-        node[:name] = name
-        node[:url] = url
-        node[:description] = description if description.present?
-        node[:logo] = logo if logo.present?
-        node[:sameAs] = same_as if same_as.present?
-        node[:founder] = founder_to_h if founder.present?
-
-        if parent_organization.present?
-          node[:parentOrganization] = {
-            '@type': 'Organization',
-            name: parent_organization[:name],
-            url: parent_organization[:url],
-          }
-        end
-
-        node
+          name: name,
+          url: url,
+          description: description,
+          logo: logo,
+          sameAs: same_as,
+          founder: object_to_h(founder),
+          parentOrganization: parent_organization_to_h
+        )
       end
 
       def json_ld
@@ -50,10 +42,15 @@ module PageStructuredData
 
       private
 
-      def founder_to_h
-        return founder.to_h if founder.respond_to?(:to_h)
+      def parent_organization_to_h
+        return object_to_h(parent_organization) if parent_organization.respond_to?(:to_h) && !parent_organization.is_a?(Hash)
+        return unless parent_organization.present?
 
-        founder
+        compact_node(
+          '@type': 'Organization',
+          name: parent_organization[:name] || parent_organization['name'],
+          url: parent_organization[:url] || parent_organization['url']
+        )
       end
     end
   end

data/app/src/page_structured_data/page_types/person.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PageStructuredData
+  module PageTypes
+    # schema.org Person structured data.
+    class Person
+      include SchemaNode
+
+      attr_reader :name, :url, :image, :same_as
+
+      def initialize(name:, url: nil, image: nil, same_as: [])
+        @name = name
+        @url = url
+        @image = image
+        @same_as = Array(same_as)
+      end
+
+      def to_h
+        compact_node(
+          '@type': 'Person',
+          name: name,
+          url: url,
+          image: image,
+          sameAs: same_as
+        )
+      end
+    end
+  end
+end

data/app/src/page_structured_data/page_types/schema_node.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PageStructuredData
+  module PageTypes
+    # Shared helpers for schema.org hash values.
+    module SchemaNode
+      private
+
+      def compact_node(node)
+        node.each_with_object({}) do |(key, value), compacted|
+          next if blank_schema_value?(value)
+
+          compacted[key] = value
+        end
+      end
+
+      def object_to_h(object)
+        return object.to_h if object.respond_to?(:to_h)
+
+        object
+      end
+
+      def blank_schema_value?(value)
+        value.nil? || (value.respond_to?(:empty?) && value.empty?)
+      end
+    end
+  end
+end

data/app/src/page_structured_data/page_types/web_site.rb

@@ -4,6 +4,8 @@ module PageStructuredData
   module PageTypes
     # WebSite structured data for a page
     class WebSite
+      include SchemaNode
+
       attr_reader :name, :url, :description, :publisher, :potential_action
 
       def initialize(name:, url:, description: nil, publisher: nil, potential_action: nil)
@@ -15,18 +17,15 @@ module PageStructuredData
       end
 
       def to_h
-        node = {
+        compact_node(
           '@context': 'https://schema.org',
           '@type': 'WebSite',
           name: name,
           url: url,
-        }
-
-        node[:description] = description if description.present?
-        node[:publisher] = publisher_to_h if publisher.present?
-        node[:potentialAction] = potential_action if potential_action.present?
-
-        node
+          description: description,
+          publisher: object_to_h(publisher),
+          potentialAction: object_to_h(potential_action)
+        )
       end
 
       def json_ld
@@ -37,13 +36,6 @@ module PageStructuredData
         )
       end
 
-      private
-
-      def publisher_to_h
-        return publisher.to_h if publisher.respond_to?(:to_h)
-
-        publisher
-      end
     end
   end
 end

data/app/views/page_structured_data/_meta_tags.html.erb

@@ -11,16 +11,28 @@
 <% end %>
 
 <meta name="title" content="<%= title %>">
+<% if description.present? %>
 <meta name="description" content="<%= description %>">
+<% end %>
+<% if image.present? %>
 <meta name="image" content="<%= image %>">
+<% end %>
 
 <meta property="og:title" content="<%= title %>">
+<% if description.present? %>
 <meta property="og:description" content="<%= description %>">
+<% end %>
+<% if image.present? %>
 <meta property="og:image" content="<%= image %>">
+<% end %>
 
-<meta property="twitter:card" content="summary_large_image">
-<meta property="twitter:title" content="<%= title %>">
-<meta property="twitter:description" content="<%= description %>">
-<meta property="twitter:image" content="<%= image %>">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="<%= title %>">
+<% if description.present? %>
+<meta name="twitter:description" content="<%= description %>">
+<% end %>
+<% if image.present? %>
+<meta name="twitter:image" content="<%= image %>">
+<% end %>
 
 <%= page&.json_lds&.html_safe %>

data/lib/page_structured_data/version.rb

@@ -1,3 +1,3 @@
 module PageStructuredData
-  VERSION = "1.0.11"
+  VERSION = "1.0.13"
 end

data/lib/page_structured_data.rb

@@ -2,9 +2,13 @@ require "page_structured_data/version"
 require "page_structured_data/engine"
 require_relative "../app/src/page_structured_data/anchors"
 require_relative "../app/src/page_structured_data/breadcrumbs"
+require_relative "../app/src/page_structured_data/page_types/schema_node"
+require_relative "../app/src/page_structured_data/page_types/person"
+require_relative "../app/src/page_structured_data/page_types/interaction_statistic"
 require_relative "../app/src/page_structured_data/page_types/article"
 require_relative "../app/src/page_structured_data/page_types/blog_posting"
 require_relative "../app/src/page_structured_data/page_types/news_article"
+require_relative "../app/src/page_structured_data/page_types/discussion_forum_posting"
 require_relative "../app/src/page_structured_data/page_types/organization"
 require_relative "../app/src/page_structured_data/page_types/web_site"
 require_relative "../app/src/page_structured_data/page"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: page_structured_data
 version: !ruby/object:Gem::Version
-  version: 1.0.11
+  version: 1.0.13
 platform: ruby
 authors:
 - Jey Geethan
@@ -32,7 +32,8 @@ dependencies:
         version: '9.0'
 description: PageStructuredData gives Rails applications a small page object and view
   partial for rendering page titles, basic meta tags, Open Graph tags, Twitter card
-  tags, breadcrumb JSON-LD, and article JSON-LD.
+  tags, breadcrumb JSON-LD, article and forum post JSON-LD, Person, Organization,
+  and WebSite JSON-LD, and public interaction statistics.
 email:
 - opensource@rocketapex.com
 executables: []
@@ -48,8 +49,12 @@ files:
 - app/src/page_structured_data/page.rb
 - app/src/page_structured_data/page_types/article.rb
 - app/src/page_structured_data/page_types/blog_posting.rb
+- app/src/page_structured_data/page_types/discussion_forum_posting.rb
+- app/src/page_structured_data/page_types/interaction_statistic.rb
 - app/src/page_structured_data/page_types/news_article.rb
 - app/src/page_structured_data/page_types/organization.rb
+- app/src/page_structured_data/page_types/person.rb
+- app/src/page_structured_data/page_types/schema_node.rb
 - app/src/page_structured_data/page_types/web_site.rb
 - app/views/page_structured_data/_meta_tags.html.erb
 - config/routes.rb