schema_dot_org 2.2.1 → 2.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e51372213bf0a5e8a9330e21695ef2da7953777627d38df1e5fc3381ea01c446
-  data.tar.gz: 9d8faef75d7ef9461d40af04900cbeed15f9afb3f1eab7278e70b49e775d2228
+  metadata.gz: 5e190c183425efbb7808c9e18f253cd377b91a4ce927d8f401f02158d6d704cf
+  data.tar.gz: 5e01217b962ed0ec450bda73923e2fbdff9ec4baeee2433c96cdc27c53e08bbf
 SHA512:
-  metadata.gz: df934ac4daf68337bed44ff56b99763ea350f0d9a09f476f2bae1a9d7231b7b1583696fe0dd1c6c74786e59d55d39ccec9a51807a89f77ad69e6c70208ad6a72
-  data.tar.gz: 68a81e34cb06baccf9743fe25ac20f674cf9e2c3972b252f4a80b212fb12b232555288c7dd2e3833d4505cefaefde5e2097ce4ba8a4e46cfaf7d3e301dbf69d5
+  metadata.gz: 36a893438da0d2731fba7a14a5d2a04b4a406688b5be906c6080ad30b2bb42865553943451fcb25e22a737e2e5478ac95a72f8fadf6447f28791c8e0ff89d2d9
+  data.tar.gz: 2b1feab097655a4efd511838774f1f4c5224c0767cf78aa970f7feb7b57bd6e7a74bf7327aee2eecd2578d38aee68eb494c5ea5b6ff6131651c82c429f27cb70

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    schema_dot_org (2.2.1)
+    schema_dot_org (2.2.3)
       validated_object (~> 2.3)
 
 GEM

data/README.md

@@ -2,22 +2,23 @@
 
 # SchemaDotOrg
 
-Create [Structured Data](https://developers.google.com/search/docs/guides/intro-structured-data) with correct **syntax** and **semantics**,
-every single time. Good structured data [helps enhance a website's search result appearance](https://developers.google.com/search/docs/guides/enhance-site).
+Easily create [Structured Data](https://developers.google.com/search/docs/guides/intro-structured-data) with **correct syntax and semantics**.
+Good structured data [helps enhance a website's search result appearance](https://developers.google.com/search/docs/guides/enhance-site):
 
 > Google Search works hard to understand the content of a page. You can help us by providing explicit clues about the meaning of a page . . .
 
 ## Usage
 
-Let's say you have a Rails app. If you put this in a controller:
+Let's say you have a Rails app. First write plain-ruby code in a controller. Just instantiate
+the structured data object you want in your web page:
 
 ```ruby
-@public_law = Organization.new(
+@my_org = Organization.new(
   name:             'Public.Law',
   founder:           Person.new(name: 'Robb Shecter'),
   founding_date:     Date.new(2009, 3, 6),
   founding_location: Place.new(address: 'Portland, OR'),
-  email:            'say_hi@public.law',
+  email:            'support@public.law',
   telephone:        '+1 123 456 7890',
   url:              'https://www.public.law',
   logo:             'https://www.public.law/favicon-196x196.png',
@@ -28,13 +29,13 @@ Let's say you have a Rails app. If you put this in a controller:
   )
 ```
 
-...and this in a template:
+...and then output it in a template:
 
 ```html
-<%= @public_law %>
+<%= @my_org %>
 ```
 
-...you'll get this in the HTML:
+...you'll get this perfectly formatted structured data in your HTML:
 
 ```html
 <script type="application/ld+json">
@@ -42,7 +43,7 @@ Let's say you have a Rails app. If you put this in a controller:
   "@context": "http://schema.org",
   "@type": "Organization",
   "name": "Public.Law",
-  "email": "say_hi@public.law",
+  "email": "support@public.law",
   "telephone": "+1 123 456 7890",
   "url": "https://www.public.law",
   "logo": "https://www.public.law/favicon-196x196.png",
@@ -63,14 +64,25 @@ Let's say you have a Rails app. If you put this in a controller:
 </script>
 ```
 
-Strong typing is at work here. `SchemaDotOrg` will validate your code, and if correct, will generate Schema.org JSON-LD markup. If not, you'll get a descriptive error message.
+### Principle: No silent failures
+
+We coded the library this way because the data is embedded in the HTML - and it's a
+pain in the butt to manually check for errors. In my case, I manage 500,000 unique
+pages in my Rails app. There's _no way_ I could place error-free structured data in
+them without automatic validation.
+
+`SchemaDotOrg` will validate your Ruby code, and if it's correct, will generate Schema.org JSON-LD markup when `#to_s`
+is called. If you, e.g., didn't add the correct attributes, you'll get a descriptive error message pointing
+you to the problem.
 
- Notice how the `foundingDate` is in the required ISO-8601 format. [The founding date must be a Ruby
-Date object](https://github.com/dogweather/schema-dot-org/blob/master/lib/schema_dot_org/organization.rb#L11) and so we can ensure correct formatting. In the same way, the `foundingLocation` is a `Place`
-which adds the proper `@type` attribute.
+Notice how the `foundingDate` is in the required ISO-8601 format. In the same way, the `foundingLocation` is a `Place`
+which adds the proper `@type` attribute. All Ruby snake-case names have been converted to the Schema.org standard camel-case.
+Etc., etc.
 
 ### You are prevented from creating invalid markup
 
+If your page loads, you know your markup is good.
+
 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
 the problem:
@@ -86,15 +98,18 @@ Place.new(
 # => NoMethodError: undefined method `author'
 ```
 
-This type safety comes from the [ValidatedObject gem](https://github.com/dogweather/validated_object).
+In my experience, I never get errors from the lib. I code it once, it works, and then
+I move on to other things.
+
+> This automatic validation comes from my [ValidatedObject gem](https://github.com/dogweather/validated_object), which in turn,
+> is a thin wrapper around ActiveRecord::Validations. So there's nothing magical going on here.
 
 ## Supported Schema.org Types
 
 AggregateOffer, ContactPoint, ItemList, ListItem, Offer, Organization, Person, Place,
 Product, SearchAction, and WebSite.
 
-Here are a few example. The source code for these is **extremely easy** to read. Check them out to see
-all the available attributes.
+Here are a few examples. [The source code for these is extremely easy to read.](https://github.com/dogweather/schema-dot-org/tree/master/lib/schema_dot_org)  Check them out to see all the available attributes.
 
 ### WebSite
 
@@ -140,9 +155,6 @@ Organization.new(
 )
 ```
 
-### Person, Place, and SearchAction
-
-These three aren't too useful on their own in web apps. They're used when creating a `WebSite` and `Organization`, as shown above.
 
 ## Installation
 
@@ -154,8 +166,8 @@ gem 'schema_dot_org'
 
 ## Development
 
-The Schema.org classes are as DRY as I could possibly make them. They're really
-easy to create and add to. For example, `Product`:
+The coding is as DRY as I could possibly make it. I think it's really
+easy to create and add to. For example, here's `Product`:
 
 ```ruby
 class Product < SchemaType
@@ -179,4 +191,4 @@ Bug reports and pull requests are welcome on GitHub.
 
 ## License
 
-[The](The) gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/schema_dot_org/aggregate_offer.rb

@@ -1,10 +1,7 @@
 # frozen_string_literal: true
 
-require 'date'
-require 'schema_dot_org'
-require 'schema_dot_org/offer'
-
-# Model the Schema.org `Thing > Place`.  See https://schema.org/Offer
+#
+# Model the Schema.org `Thing > Intangible > Offer > AggregateOffer`.  See https://schema.org/Offer
 #
 module SchemaDotOrg
   class AggregateOffer < SchemaType

data/lib/schema_dot_org/college_or_university.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+
+#
+# https://schema.org/CollegeOrUniversity
+#
+module SchemaDotOrg
+  class CollegeOrUniversity < SchemaType
+    validated_attr :name, type: String, presence: true
+    validated_attr :url,  type: String, allow_nil: true
+  end
+end

data/lib/schema_dot_org/contact_point.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require 'schema_dot_org'
-
 
 #
 # Model the Schema.org `ContactPoint`.  See http://schema.org/ContactPoint

data/lib/schema_dot_org/item_list.rb

@@ -1,6 +1,5 @@
 # frozen_string_literal: true
 
-require 'schema_dot_org'
 
 #
 # Model the Schema.org `ItemList`.  See https://schema.org/ItemList

data/lib/schema_dot_org/list_item.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
-require 'schema_dot_org'
-require 'schema_dot_org/product'
 
+require_relative 'product'
 
+#
+# Model the Schema.org `ItemListElement`.  See https://schema.org/ItemListElement
+#
 module SchemaDotOrg
-  # Model the Schema.org `ItemListElement`.  See https://schema.org/ItemListElement
   class ListItem < SchemaType
-    validated_attr :image,     type: String,  allow_nil: true
-    validated_attr :item,      type: Product, allow_nil: true
-    validated_attr :name,      type: String,  allow_nil: true
-    validated_attr :position,  type: Integer, presence:  true
-    validated_attr :url,       type: String,  allow_nil: true
+    validated_attr :image,     type: String,                allow_nil: true
+    validated_attr :item,      type: SchemaDotOrg::Product, allow_nil: true
+    validated_attr :name,      type: String,                allow_nil: true
+    validated_attr :position,  type: Integer,               presence:  true
+    validated_attr :url,       type: String,                allow_nil: true
   end
 end

data/lib/schema_dot_org/offer.rb

@@ -1,10 +1,8 @@
 # frozen_string_literal: true
 
-require 'date'
-require 'schema_dot_org'
 
 #
-# Model the Schema.org `Thing > Place`.  See https://schema.org/Offer
+# Model the Schema.org `Thing > Intangible > Offer`.  See https://schema.org/Offer
 #
 module SchemaDotOrg
   class Offer < SchemaType

data/lib/schema_dot_org/organization.rb

@@ -1,11 +1,12 @@
 # frozen_string_literal: true
 
 require 'date'
-require 'schema_dot_org'
-require 'schema_dot_org/person'
-require 'schema_dot_org/place'
-require 'schema_dot_org/contact_point'
 
+require_relative 'person'
+require_relative 'place'
+
+# Google allows `url` to be a string:
+# https://developers.google.com/search/docs/appearance/structured-data/logo
 
 module SchemaDotOrg
   class Organization < SchemaType
@@ -14,9 +15,11 @@ module SchemaDotOrg
     validated_attr :founder,           type: SchemaDotOrg::Person, allow_nil: true
     validated_attr :founding_date,     type: Date, allow_nil: true
     validated_attr :founding_location, type: SchemaDotOrg::Place, allow_nil: true
+    validated_attr :legal_name,        type: String, allow_nil: true
     validated_attr :logo,              type: String
     validated_attr :name,              type: String
     validated_attr :same_as,           type: Array, allow_nil: true
+    validated_attr :slogan,            type: String, allow_nil: true
     validated_attr :telephone,         type: String, allow_nil: true
     validated_attr :url,               type: String
   end

data/lib/schema_dot_org/person.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
+
 #
 # Model the Schema.org **Person**.  See http://schema.org/Person
 #
 module SchemaDotOrg
   class Person < SchemaType
-    validated_attr :name,    type: String, presence: true
-    validated_attr :same_as, type: Array,  allow_nil: true
-    validated_attr :url,     type: String, allow_nil: true
+    validated_attr :award,            type: String, allow_nil: true
+    validated_attr :alumni_of,        type: SchemaDotOrg::CollegeOrUniversity, allow_nil: true
+    validated_attr :honorific_suffix, type: String, allow_nil: true
+    validated_attr :name,             type: String, presence: true
+    validated_attr :same_as,          type: Array,  allow_nil: true
+    validated_attr :url,              type: String, allow_nil: true
   end
 end

data/lib/schema_dot_org/place.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+
 #
 # Model the Schema.org `Thing > Place`.  See http://schema.org/Place
 #

data/lib/schema_dot_org/product.rb

@@ -1,11 +1,8 @@
 # frozen_string_literal: true
 
-require 'date'
-require 'schema_dot_org'
-require 'schema_dot_org/aggregate_offer'
 
 #
-# Model the Schema.org `Thing > Place`.  See https://schema.org/Product
+# Model the Schema.org `Thing > Product`.  See https://schema.org/Product
 #
 module SchemaDotOrg
   class Product < SchemaType

data/lib/schema_dot_org/search_action.rb

@@ -5,7 +5,7 @@
 # Model the Schema.org `Thing > SearchAction`.  See http://schema.org/SearchAction
 #
 module SchemaDotOrg
-  class SearchAction < SchemaType
+  class SearchAction < SchemaDotOrg::SchemaType
     validated_attr :query_input, type: String, presence: true
     validated_attr :target,      type: String, presence: true
   end

data/lib/schema_dot_org/web_site.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+
 #
 # Model the Schema.org `Thing > CreativeWork > WebSite`.
 # @See http://schema.org/WebSite

data/lib/schema_dot_org.rb

@@ -1,16 +1,128 @@
 # frozen_string_literal: true
-require 'schema_dot_org/schema_type'
-require 'schema_dot_org/search_action'
-require 'schema_dot_org/web_site'
-require 'schema_dot_org/organization'
-require 'schema_dot_org/product'
+require 'json'
+require 'validated_object'
+
+#
+# Abstract base class for all the Schema.org types.
+#
+module SchemaDotOrg
+  class SchemaType < ValidatedObject::Base
+    ROOT_ATTR = { "@context" => "https://schema.org" }.freeze
+    UNQUALIFIED_CLASS_NAME_REGEX = /([^:]+)$/
+
+
+    def to_s
+      json_string = to_json_ld(pretty: (!rails_production? && !ENV['SCHEMA_DOT_ORG_MINIFIED_JSON']))
+
+      # Mark as safe if we're in Rails
+      if json_string.respond_to?(:html_safe)
+        json_string.html_safe
+      else
+        json_string
+      end
+    end
+
+
+    def to_json_ld(pretty: false)
+      "<script type=\"application/ld+json\">\n" + to_json(pretty: pretty, as_root: true) + "\n</script>"
+    end
+
+
+    def to_json(pretty: false, as_root: false)
+      structure = as_root ? ROOT_ATTR.merge(to_json_struct) : to_json_struct
+
+      if pretty
+        JSON.pretty_generate(structure)
+      else
+        structure.to_json
+      end
+    end
+
+
+    # Use the class name to create the "@type" attribute.
+    # @return a hash structure representing json.
+    def to_json_struct
+      { "@type" => un_namespaced_classname }.merge(_to_json_struct.reject { |_, v| v.blank? })
+    end
+
+
+    def _to_json_struct
+      attrs_and_values
+    end
+
+
+    # @return the classname without the module namespace.
+    def un_namespaced_classname
+      self.class.name =~ UNQUALIFIED_CLASS_NAME_REGEX
+      Regexp.last_match(1)
+    end
+
+
+    def object_to_json_struct(object)
+      return nil unless object
+      object.to_json_struct
+    end
+
+
+    def attrs_and_values
+      attrs.map do |attr|
+        # Clean up and andle the `query-input` attribute, which
+        # doesn't follow the normal camelCase convention.
+        attr_name   = snake_case_to_lower_camel_case(attr.to_s.delete_prefix('@')).sub('queryInput', 'query-input')
+        attr_value = instance_variable_get(attr)
+
+        [attr_name, resolve_value(attr_value)]
+      end.to_h
+    end
+
+
+    def resolve_value(value)
+      if value.is_a?(Array)
+        value.map { |v| resolve_value(v) }
+
+      elsif value.is_a?(Date)
+        value.to_s
+
+      elsif is_schema_type?(value)
+        value.to_json_struct
+        
+      else
+        value
+      end
+    end
+
+
+    def snake_case_to_lower_camel_case(snake_case)
+      snake_case.to_s.split('_').map.with_index { |s, i| i.zero? ? s : s.capitalize }.join
+    end
+
+
+    def attrs
+      instance_variables.reject{ |v| [:@validation_context, :@errors].include?(v) }
+    end
+
+
+    def is_schema_type?(object)
+      object.class.module_parent == SchemaDotOrg
+    end
+
+
+    def rails_production?
+      defined?(Rails) && Rails.env.production?
+    end
+  end
+end
+
+
+require 'schema_dot_org/aggregate_offer'
+require 'schema_dot_org/college_or_university'
+require 'schema_dot_org/contact_point'
 require 'schema_dot_org/item_list'
 require 'schema_dot_org/list_item'
+require 'schema_dot_org/organization'
 require 'schema_dot_org/person'
 require 'schema_dot_org/place'
-require 'schema_dot_org/aggregate_offer'
+require 'schema_dot_org/product'
 require 'schema_dot_org/offer'
-require 'schema_dot_org/contact_point'
-
-module SchemaDotOrg
-end
+require 'schema_dot_org/search_action'
+require 'schema_dot_org/web_site'

data/schema_dot_org.gemspec

@@ -7,7 +7,7 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 Gem::Specification.new do |spec|
   spec.required_ruby_version = '>= 2.6'
   spec.name          = 'schema_dot_org'
-  spec.version       = '2.2.1'
+  spec.version       = '2.2.3'
   spec.authors       = ['Robb Shecter']
   spec.email         = ['robb@public.law']
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: schema_dot_org
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 2.2.3
 platform: ruby
 authors:
 - Robb Shecter
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-10-12 00:00:00.000000000 Z
+date: 2023-10-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: validated_object
@@ -87,6 +87,7 @@ files:
 - bin/tapioca
 - lib/schema_dot_org.rb
 - lib/schema_dot_org/aggregate_offer.rb
+- lib/schema_dot_org/college_or_university.rb
 - lib/schema_dot_org/contact_point.rb
 - lib/schema_dot_org/item_list.rb
 - lib/schema_dot_org/list_item.rb
@@ -95,7 +96,6 @@ files:
 - lib/schema_dot_org/person.rb
 - lib/schema_dot_org/place.rb
 - lib/schema_dot_org/product.rb
-- lib/schema_dot_org/schema_type.rb
 - lib/schema_dot_org/search_action.rb
 - lib/schema_dot_org/web_site.rb
 - schema_dot_org.gemspec

data/lib/schema_dot_org/schema_type.rb

@@ -1,110 +0,0 @@
-require 'json'
-require 'validated_object'
-
-module SchemaDotOrg
-  class SchemaType < ValidatedObject::Base
-    ROOT_ATTR = { "@context" => "http://schema.org" }.freeze
-    UNQUALIFIED_CLASS_NAME_REGEX = /([^:]+)$/
-
-
-    def to_s
-      json_string = to_json_ld(pretty: (!rails_production? && !ENV['SCHEMA_DOT_ORG_MINIFIED_JSON']))
-
-      # Mark as safe if we're in Rails
-      if json_string.respond_to?(:html_safe)
-        json_string.html_safe
-      else
-        json_string
-      end
-    end
-
-
-    def to_json_ld(pretty: false)
-      "<script type=\"application/ld+json\">\n" + to_json(pretty: pretty, as_root: true) + "\n</script>"
-    end
-
-
-    def to_json(pretty: false, as_root: false)
-      structure = as_root ? ROOT_ATTR.merge(to_json_struct) : to_json_struct
-
-      if pretty
-        JSON.pretty_generate(structure)
-      else
-        structure.to_json
-      end
-    end
-
-
-    # Use the class name to create the "@type" attribute.
-    # @return a hash structure representing json.
-    def to_json_struct
-      { "@type" => un_namespaced_classname }.merge(_to_json_struct.reject { |_, v| v.blank? })
-    end
-
-
-    def _to_json_struct
-      attrs_and_values
-    end
-
-
-    # @return the classname without the module namespace.
-    def un_namespaced_classname
-      self.class.name =~ UNQUALIFIED_CLASS_NAME_REGEX
-      Regexp.last_match(1)
-    end
-
-
-    def object_to_json_struct(object)
-      return nil unless object
-      object.to_json_struct
-    end
-
-
-    def attrs_and_values
-      attrs.map do |attr|
-        # Clean up and andle the `query-input` attribute, which
-        # doesn't follow the normal camelCase convention.
-        attr_name   = snake_case_to_lower_camel_case(attr.to_s.delete_prefix('@')).sub('queryInput', 'query-input')
-        attr_value = instance_variable_get(attr)
-
-        [attr_name, resolve_value(attr_value)]
-      end.to_h
-    end
-
-
-    def resolve_value(value)
-      if value.is_a?(Array)
-        value.map { |v| resolve_value(v) }
-
-      elsif value.is_a?(Date)
-        value.to_s
-
-      elsif is_schema_type?(value)
-        value.to_json_struct
-        
-      else
-        value
-      end
-    end
-
-
-    def snake_case_to_lower_camel_case(snake_case)
-      snake_case.to_s.split('_').map.with_index { |s, i| i.zero? ? s : s.capitalize }.join
-    end
-
-
-    def attrs
-      instance_variables.reject{ |v| [:@validation_context, :@errors].include?(v) }
-    end
-
-
-    def is_schema_type?(object)
-      object.class.module_parent == SchemaDotOrg
-    end
-
-
-    def rails_production?
-      defined?(Rails) && Rails.env.production?
-    end
-  end
-end