schema_dot_org

Table of Contents

• SchemaDotOrg
  • Usage
    • Principle: No silent failures
    • You are prevented from creating invalid markup
  • Supported Schema.org Types
  • Examples
    • BreadcrumbList
    • WebSite
  • Installation
  • Development
  • Contributing
  • License

SchemaDotOrg

Easily create Structured Data with correct syntax and semantics. Good structured data helps enhance a website's search result appearance:

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

@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:            '[e-mail]',
  telephone:        '[phone]',
  url:              'https://www.public.law',
  logo:             'https://www.public.law/favicon-196x196.png',
  same_as: [
    'https://twitter.com/law_is_code',
    'https://www.facebook.com/PublicDotLaw'
    ]
  )

...and then output it in a template:

<%= @my_org %>

...you'll get this perfectly formatted structured data in your HTML:

<script type="application/ld+json">
{
  "@context": "http://schema.org",
  "@type": "Organization",
  "name": "Public.Law",
  "email": "[e-mail]",
  "telephone": "[phone]",
  "url": "https://www.public.law",
  "logo": "https://www.public.law/favicon-196x196.png",
  "foundingDate": "2009-03-06",
  "founder": {
    "@type": "Person",
    "name": "Robb Shecter"
  },
  "foundingLocation": {
    "@type": "Place",
    "address": "Portland, OR"
  },
  "sameAs": [
    "https://twitter.com/law_is_code",
    "https://www.facebook.com/PublicDotLaw"
  ]
}
</script>

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

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 the problem:

Place.new(address: 12345)
# => ArgumentError: Address is class Integer, not String

Place.new(
  address: '12345 Happy Street',
  author:  'Hemmingway'
)
# => NoMethodError: undefined method `author'

In my experience, I never get errors from the lib. I code it once, it works, and then I move on to other things.

[!NOTE] This automatic validation comes from my ValidatedObject gem, which in turn, is a thin wrapper around ActiveRecord::Validations. So there's nothing magical going on here.

Supported Schema.org Types

See each type's RSpec for an example of how to use it.

Name	Schema.org Page	RSpec Spec	Source Code
AggregateOffer	Schema.org		Source
BreadcrumbList	Schema.org	RSpec	Source
CollegeOrUniversity	Schema.org	RSpec	Source
Comment	Schema.org	RSpec	Source
ContactPoint	Schema.org		Source
DiscussionForumPosting	Schema.org	RSpec	Source
InteractionCounter	Schema.org	RSpec	Source
ItemList	Schema.org	RSpec	Source
Language	Schema.org	RSpec	Source
ListItem	Schema.org		Source
Offer	Schema.org		Source
Organization	Schema.org	RSpec	Source
Person	Schema.org	RSpec	Source
Place	Schema.org	RSpec	Source
PostalAddress	Schema.org	RSpec	Source
Product	Schema.org	RSpec	Source
SearchAction	Schema.org	RSpec	Source
WebSite	Schema.org	RSpec	Source

Examples

BreadcrumbList

The make_breadcrumbs convenience method creates a BreadcrumbList from a simple array of hashes:

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:

<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

Example with only the required attributes:

WebSite.new(
  name: 'Texas Public Law',
  url:  'https://texas.public.law',
)

With the optional SearchAction to enable a Sitelinks Searchbox:

WebSite.new(
  name: 'Texas Public Law',
  url:  'https://texas.public.law',
  potential_action: SearchAction.new(
    target: 'https://texas.public.law/?search={search_term_string}',
    query_input: 'required name=search_term_string'
  )
)

Installation

Add this line to your application's Gemfile:

gem 'schema_dot_org'

Development

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:

class Product < SchemaType
  validated_attr :description,  type: String, allow_nil: true
  validated_attr :image,        type: Array,  allow_nil: true
  validated_attr :name,         type: String
  validated_attr :offers,       type: SchemaDotOrg::AggregateOffer
  validated_attr :url,          type: String
end

The attributes are from the Schema.org Product spec.

All Rails validations are available. These are just the attributes we've felt like adding. PR's are welcome if you want to add more. Also for more Schema.org types.

Contributing

Bug reports and pull requests are welcome on GitHub.

License

The gem is available as open source under the terms of the MIT License.