Adopting JSON-LD Schema for cleaner, more powerful SEO

Implementing schema.org is vital for improving SEO performance, especially for public-facing projects. At MarsBased, we adopted a standard approach that must be applied to every client project prioritizing SEO.

We have written about this in the past, in A cleaner implementation of Schema.org using JSON but we have a few extra considerations, five years later.

What is Schema and why is it necessary?

Schema, primarily referencing the resource schema.org, is the tool that crawlers use to better understand the typology of indexed content. By defining entities, you can detail attributes for an organisation - such as MarsBased - (like team size, address, and social profiles) or other content types. While not implementing schema will not break a website, doing so significantly improves your SEO performance.

Historically, schema was implemented using Microdata, which involved scattering attributes such as item scope and item prop directly within the HTML. This mixes meta attributes with the actual content and is not easily maintainable, particularly across large codebases, because changes are hard to track across scattered code, like in this example:

The solution we adopted a few years ago is JSON-LD. This approach is cleaner and more maintainable because it centralizes all schema information into a single block using a JSON format script.

See an example here:

Why did we change?

• Programmatic implementation: MarsBased currently uses a presenter (code below) in our Ruby on Rails CMS (Maglev) to programmatically generate the schema script for elements like job offers.
• Centralised management: This programmatic, centralised approach reduces the complexity associated with scattered variables and code, making it much more maintainable over time, especially in projects with heavy team rotation, like our company website, where 100% of our employes has contributed to its codebase!

Here's the example of our presenter that generates the JSON script for job offers:

  # rubocop:disable Metrics/MethodLength
  def to_jsonld
    {
      '@context': 'https://schema.org/',
      '@type': 'JobPosting',
      title: full_title,
      description: job_offer.summary,
      identifier: {
        '@type': 'PropertyValue',
        name: 'MarsBased',
        value: ENV.fetch('JOB_POSTING_COMPANY_IDENTIFIER', '')
      },
      datePosted: job_offer.published_at&.to_date,
      applicantLocationRequirements: [
        { '@type': 'Country', 'name': 'Austria' },
       # removed this long list of countries for readability
      ],
      jobLocationType: 'TELECOMMUTE',
      employmentType: job_offer.in_house? ? 'IN_HOUSE' : 'CONTRACTOR',
      hiringOrganization: {
        '@type': 'Organization',
        name: 'MarsBased',
        sameAs: 'https://marsbased.com',
        logo: ENV.fetch('MARSBASED_LOGO_URL', '')
      },
      baseSalary: {
        '@type': 'MonetaryAmount',
        currency: 'EUR',
        value: {
          '@type': 'QuantitativeValue',
          minValue: job_offer.salary_min,
          maxValue: job_offer.salary_max,
          unitText: job_offer.in_house? ? 'YEAR' : 'HOUR'
        }
      }
    }.to_json
  end

Core Schema implementation best practices

To ensure proper implementation and maximum benefit, our team adheres to the following decisions and best practices:

• Stick to one format: Schema implementation must only use one format, preferably JSON-LD. Implementing both JSON-LD and Microdata can confuse crawlers and lead to the detection of duplicated properties.
• Ensure Server-Side Rendering (SSR): JSON-LD needs to be implemented on the server side. Most crawlers require the JSON-LD content to be in the HTML served by the server, which is a critical technical consideration for applications using front-end-only frameworks like React or NextJS.
• Focus your tagging scope: Focus schema tagging on main items, such as the company, blog posts, employees or job openings. Over-tagging is generally not beneficial and can become a time sink with little to no return on investment.
• Validate implementation: Always validate your schema implementation using tools available on schema.org, Google Search Tools, or Bing. These tools inform you if any mandatory attributes are missing. There are a few Chome add-ons as well that can help you with that!

By implementing schema correctly, you improve how content appears in search results and when URLs are unfurled on social media or by AI tools like ChatGPT, Perplexity and the like. Make yourself and your projects more visible in the vast sea of business!