schema_dot_org 2.3.3 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 736ca556e9da839382ce55910f9729313cbd37bee13df252fdff1606af240650
-  data.tar.gz: '08fa546126f7f829e1ee6af9358566e69fef5181afeaacb83c781741353f08af'
+  metadata.gz: eba4af5a8f17ea83c93f00956aeb53733a629a2a7dff60a20774f52b4682c5a2
+  data.tar.gz: a7f134544c69e830613e9004ac8bee7e8944637270f0f39c569d91cbd2fe1cef
 SHA512:
-  metadata.gz: 91dda5511231e77bddf3a15eb5c73c41cbf36a4eef69cf20be03b6b803c156555aeac751bc9d0d0112316a4dec0b8faf472479b0325f69253afb6c868860ec6e
-  data.tar.gz: cc529cd3d76bf23fb01b8273b6675c063c98b082122fcec9327fd26f428d98e35f158499fcbb20b0513fc67f2c962ccd07483e54040bf44f37f63bd2b6a6779e
+  metadata.gz: f840e728482eca79bca2035002fb6f1cd47fb5b41e54ec823ea17dfd6ad2988f9c51d7b82414004a39d3637ae56c80509bf2425cf4373854d00a469e35daa284
+  data.tar.gz: a06b1d8b8da895c7713ded7a913d6ee069ff7205ae3f4f3fe13b25bf6f6c7ee2af98fac885d761889b1a09a136f31e37c68bd4295c8ee324917558c6a6c40cca

data/.gitignore

@@ -9,3 +9,5 @@
 
 # rspec failure tracking
 .rspec_status
+
+*.gem

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    schema_dot_org (2.3.3)
+    schema_dot_org (2.5.0)
       validated_object (~> 2.3)
 
 GEM
@@ -21,15 +21,24 @@ GEM
       tzinfo (~> 2.0)
     base64 (0.1.1)
     bigdecimal (3.1.4)
+    coderay (1.1.3)
     concurrent-ruby (1.2.2)
     connection_pool (2.4.1)
     diff-lcs (1.5.0)
+    doctest2-core (0.9.3)
+    doctest2-rspec (0.9.2)
+      doctest2-core (~> 0.9.0)
+      rspec (~> 3.0)
     drb (2.1.1)
       ruby2_keywords
     i18n (1.14.1)
       concurrent-ruby (~> 1.0)
+    method_source (1.1.0)
     minitest (5.20.0)
     mutex_m (0.1.2)
+    pry (0.15.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
     rake (13.0.6)
     rspec (3.12.0)
       rspec-core (~> 3.12.0)
@@ -57,6 +66,8 @@ PLATFORMS
 
 DEPENDENCIES
   bundler (~> 2.4)
+  doctest2-rspec (~> 0.9.2)
+  pry (> 0.0.0)
   rake (~> 13.0)
   rspec (~> 3.12)
   schema_dot_org!

data/README.md

@@ -1,19 +1,18 @@
-[![Gem Version](https://badge.fury.io/rb/schema_dot_org.svg)](https://badge.fury.io/rb/schema_dot_org)
-
 ## Table of Contents
 
 - [SchemaDotOrg](#schemadotorg)
-- [Usage](#usage)
-  - [Principle: No silent failures](#principle-no-silent-failures)
-  - [You are prevented from creating invalid markup](#you-are-prevented-from-creating-invalid-markup)
-- [Supported Schema.org Types](#supported-schemaorg-types)
-- [Examples](#examples)
-  - [WebSite](#website)
-  - [Organization](#organization)
-- [Installation](#installation)
-- [Development](#development)
-- [Contributing](#contributing)
-- [License](#license)
+  - [Usage](#usage)
+    - [Principle: No silent failures](#principle-no-silent-failures)
+    - [You are prevented from creating invalid markup](#you-are-prevented-from-creating-invalid-markup)
+  - [Supported Schema.org Types](#supported-schemaorg-types)
+  - [Examples](#examples)
+    - [BreadcrumbList](#breadcrumblist)
+    - [WebSite](#website)
+    - [Organization](#organization)
+  - [Installation](#installation)
+  - [Development](#development)
+  - [Contributing](#contributing)
+  - [License](#license)
 
 # SchemaDotOrg
 
@@ -24,7 +23,9 @@ Good structured data [helps enhance a website's search result appearance](https:
 
 ## Usage
 
-Let's say you have a Rails app. First write plain-ruby code in a helper or controller. Just instantiate
+Let's say you have a Rails app. First write plain-ruby code in a helper or controller. 
+
+Here's what that'd look like in a controller. Instantiate
 the structured data object you want in your web page:
 
 ```ruby
@@ -96,7 +97,7 @@ Etc., etc.
 
 ### You are prevented from creating invalid markup
 
-I make mistakes. So I wanted to know that if my page loads, the markup is good.
+I make mistakes. So I wanted to know that if my page loads, the markup is good. I hate "silent failures".
 
 If you use the wrong type or try to set an unknown attribute, SchemaDotOrg will
 refuse to create the incorrect JSON-LD. Instead, you'll get a message explaining
@@ -117,7 +118,7 @@ In my experience, I never get errors from the lib. I code it once, it works, and
 I move on to other things.
 
 > [!NOTE]
-> This automatic validation comes from my [ValidatedObject gem](https://github.com/dogweather/validated_object), which in turn,
+> This automatic validation comes from my [ValidatedObject gem](https://github.com/public-law/validated_object), which in turn,
 > is a thin wrapper around ActiveRecord::Validations. So there's nothing magical going on here.
 
 ## Supported Schema.org Types
@@ -127,6 +128,7 @@ See each type's RSpec for an example of how to use it.
 | Name                   | Schema.org Page                                         | RSpec Spec                                                                                                             | Source Code                                                                                                       |
 | ---------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
 | AggregateOffer         | [Schema.org](https://schema.org/AggregateOffer)         |                                                                                                                        | [Source](https://github.com/public-law/schema-dot-org/blob/master/lib/schema_dot_org/aggregate_offer.rb)          |
+| BreadcrumbList         | [Schema.org](https://schema.org/BreadcrumbList)         | [RSpec](https://github.com/public-law/schema-dot-org/blob/master/spec/schema_dot_org/breadcrumb_list_spec.rb)          | [Source](https://github.com/public-law/schema-dot-org/blob/master/lib/schema_dot_org/breadcrumb_list.rb)          |
 | CollegeOrUniversity    | [Schema.org](https://schema.org/CollegeOrUniversity)    | [RSpec](https://github.com/public-law/schema-dot-org/blob/master/spec/schema_dot_org/college_or_university_spec.rb)    | [Source](https://github.com/public-law/schema-dot-org/blob/master/lib/schema_dot_org/college_or_university.rb)    |
 | Comment                | [Schema.org](https://schema.org/Comment)                | [RSpec](https://github.com/public-law/schema-dot-org/blob/master/spec/schema_dot_org/comment_spec.rb)                  | [Source](https://github.com/public-law/schema-dot-org/blob/master/lib/schema_dot_org/comment.rb)                  |
 | ContactPoint           | [Schema.org](https://schema.org/ContactPoint)           |                                                                                                                        | [Source](https://github.com/public-law/schema-dot-org/blob/master/lib/schema_dot_org/contact_point.rb)            |
@@ -145,7 +147,60 @@ See each type's RSpec for an example of how to use it.
 
 ## Examples
 
-Here are a few examples. [The source code for these is extremely easy to read.](https://github.com/public-law/schema-dot-org/tree/master/lib/schema_dot_org)  Check them out to see all the available attributes.
+### BreadcrumbList
+
+The `make_breadcrumbs` convenience method creates a BreadcrumbList from a simple array of hashes:
+
+```ruby
+links = [
+  { name: 'Home',            url: 'https://example.com' },
+  { name: 'Books',           url: 'https://example.com/books' },
+  { name: 'Science Fiction', url: 'https://example.com/books/sci-fi' },
+  { name: 'Award Winners' }  # Last item typically has no URL
+]
+
+SchemaDotOrg
+  .make_breadcrumbs(links)
+  .to_s
+```
+
+produces:
+
+```html
+<script type="application/ld+json">
+{
+  "@context": "https://schema.org",
+  "@type": "BreadcrumbList",
+  "itemListElement": [
+    {
+      "@type": "ListItem",
+      "position": 1,
+      "name": "Home",
+      "item": "https://example.com"
+    },
+    {
+      "@type": "ListItem", 
+      "position": 2,
+      "name": "Books",
+      "item": "https://example.com/books"
+    },
+    {
+      "@type": "ListItem",
+      "position": 3,
+      "name": "Science Fiction",
+      "item": "https://example.com/books/sci-fi"
+    },
+    {
+      "@type": "ListItem",
+      "position": 4,
+      "name": "Award Winners"
+    }
+  ]
+}
+</script>
+```
+
+URLs are automatically validated - invalid URLs will raise an `ArgumentError` with a descriptive message.
 
 ### WebSite
 

data/lib/schema_dot_org/breadcrumb_list.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+
+#
+# Model the Google / Schema.org `BreadcrumbList`.
+#
+# The intent is to primarily support Google's BreadcrumbList. Properties
+# from Schema.org are welcome if desired.
+#
+# See https://developers.google.com/search/docs/appearance/structured-data/breadcrumb
+# and https://schema.org/BreadcrumbList
+#
+module SchemaDotOrg
+  class BreadcrumbList < SchemaType
+    validated_attr :itemListElement, type: Array, presence: true
+  end
+end

data/lib/schema_dot_org/list_item.rb

@@ -9,9 +9,22 @@ require_relative 'product'
 module SchemaDotOrg
   class ListItem < SchemaType
     validated_attr :image,     type: String,                allow_nil: true
-    validated_attr :item,      type: SchemaDotOrg::Product, allow_nil: true
+    validated_attr :item,      type: Object,                allow_nil: true  # Allow String or SchemaType
     validated_attr :name,      type: String,                allow_nil: true
     validated_attr :position,  type: Integer,               presence:  true
     validated_attr :url,       type: String,                allow_nil: true
+
+    validate :item_must_be_valid_type
+
+
+    private
+
+    def item_must_be_valid_type
+      return if item.nil?
+      return if item.is_a?(String)  # URL
+      return if item.is_a?(SchemaDotOrg::SchemaType)  # Any Schema.org type
+
+      errors.add(:item, 'must be a URL string or Schema.org object, but was: ' + item.class.name + ' (' + item.inspect + ')')
+    end
   end
 end

data/lib/schema_dot_org/url_validator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+module SchemaDotOrg
+  # Utility module for URL validation
+  module UrlValidator
+    # Validates that a string is a proper web URL (HTTP/HTTPS with a host)
+    #
+    # @param url [String]  The URL string to validate
+    # @return    [Boolean] true if the URL is valid, false otherwise
+    #
+    # Doc Tests:
+    #   >> SchemaDotOrg::UrlValidator.valid_web_url?('https://example.com')     #=> true
+    #   >> SchemaDotOrg::UrlValidator.valid_web_url?('http://example.com/path') #=> true
+    #   >> SchemaDotOrg::UrlValidator.valid_web_url?('ftp://example.com')       #=> false
+    #   >> SchemaDotOrg::UrlValidator.valid_web_url?('not-a-url')               #=> false
+    #   >> SchemaDotOrg::UrlValidator.valid_web_url?('')                        #=> false
+    #   >> SchemaDotOrg::UrlValidator.valid_web_url?(nil)                       #=> false
+    #
+    def self.valid_web_url?(url)
+      return false if url.nil? || url.to_s.strip.empty?
+
+      uri = URI.parse(url.to_s)
+
+      # Check for valid HTTP/HTTPS scheme
+      return false unless %w[http https].include?(uri.scheme)
+
+      # Check for a host
+      return false if uri.host.nil? || uri.host.strip.empty?
+
+      true
+    rescue URI::InvalidURIError
+      false
+    end
+  end
+end

data/lib/schema_dot_org.rb

@@ -2,11 +2,42 @@
 require 'json'
 require 'validated_object'
 
+
+module SchemaDotOrg
+  ##
+  # Make a BreadcrumbList from an array of links. This is a convenience
+  # method for creating a BreadcrumbList and its ListItems.
+  #
+  # @example
+  #   SchemaDotOrg.make_breadcrumbs([
+  #     { name: 'Home', url: 'https://example.com' },
+  #     { name: 'Books', url: 'https://example.com/books' },
+  #     { name: 'Science Fiction' },
+  #   ])
+  #
+  # @param links [Array<Hash>] An array of links. Each link is a hash with
+  #        a `:url` and `:name` key. The `:url` is optional.
+  # @return [BreadcrumbList] A BreadcrumbList object.
+  # @raise [ArgumentError] If any URL is invalid.
+  #
+  def self.make_breadcrumbs(links)
+    BreadcrumbList.new(itemListElement: links.map.with_index(1) do |link, index|
+      url  = link[:url]
+      name = link[:name]
+
+      if !url.nil? && !UrlValidator.valid_web_url?(url)
+        raise ArgumentError, "URL is not a valid web URL: #{url}"
+      end
+
+      ListItem.new(position: index, item: url, name: name)
+    end)
+  end
+
+
 #
 # Abstract base class for all the Schema.org types.
 #
-module SchemaDotOrg
-  class SchemaType < ValidatedObject::Base
+class SchemaType < ValidatedObject::Base
     EXCLUDED_INSTANCE_VARIABLES = %i[@context_for_validation @validation_context @errors].freeze
     ROOT_ATTR = { "@context" => "https://schema.org" }.freeze
     UNQUALIFIED_CLASS_NAME_REGEX = /([^:]+)$/
@@ -116,6 +147,7 @@ end
 
 
 require 'schema_dot_org/aggregate_offer'
+require 'schema_dot_org/breadcrumb_list'
 require 'schema_dot_org/college_or_university'
 require 'schema_dot_org/comment'
 require 'schema_dot_org/contact_point'
@@ -130,4 +162,5 @@ require 'schema_dot_org/place'
 require 'schema_dot_org/product'
 require 'schema_dot_org/offer'
 require 'schema_dot_org/search_action'
+require 'schema_dot_org/url_validator'
 require 'schema_dot_org/web_site'

data/schema_dot_org.gemspec

@@ -7,9 +7,9 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 3.0'
   spec.name          = 'schema_dot_org'
-  spec.version       = '2.3.3'
-  spec.authors       = ['Robb Shecter']
-  spec.email         = ['robb@public.law']
+  spec.version       = '2.5.0'
+  spec.authors       = ['Robert Shecter']
+  spec.email         = ['robert@public.law']
 
   spec.summary       = 'JSON-LD generator for Schema.org vocabulary'
   spec.description   = 'Creates well-formed website metadata with ' \
@@ -30,4 +30,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 2.4"
   spec.add_development_dependency "rake", "~> 13.0"
   spec.add_development_dependency "rspec", "~> 3.12"
+  spec.add_development_dependency "doctest2-rspec", "~> 0.9.2"
+  spec.add_development_dependency "pry", "> 0.0.0"
 end

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: schema_dot_org
 version: !ruby/object:Gem::Version
-  version: 2.3.3
+  version: 2.5.0
 platform: ruby
 authors:
-- Robb Shecter
+- Robert Shecter
 bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -65,9 +65,37 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: doctest2-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.9.2
+- !ruby/object:Gem::Dependency
+  name: pry
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 0.0.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 0.0.0
 description: Creates well-formed website metadata with strongly typed Ruby.
 email:
-- robb@public.law
+- robert@public.law
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -85,6 +113,7 @@ files:
 - bin/tapioca
 - lib/schema_dot_org.rb
 - lib/schema_dot_org/aggregate_offer.rb
+- lib/schema_dot_org/breadcrumb_list.rb
 - lib/schema_dot_org/college_or_university.rb
 - lib/schema_dot_org/comment.rb
 - lib/schema_dot_org/contact_point.rb
@@ -99,6 +128,7 @@ files:
 - lib/schema_dot_org/place.rb
 - lib/schema_dot_org/product.rb
 - lib/schema_dot_org/search_action.rb
+- lib/schema_dot_org/url_validator.rb
 - lib/schema_dot_org/web_site.rb
 - schema_dot_org.gemspec
 - test-script.rb