JSON+LD en gestructureerde data, waarom en praktische voorbeelden

Auteur: Wiljan Slofstra

Machines zijn dom. We horen allemaal grootse verhalen over artificial intelligence die de mensheid gaat overnemen, dat we geen banen meer hebben over een paar jaar. Maar laten we niet op de zaken vooruit lopen, want machines zijn daar nog lang niet. Om machines te laten leren is er veel data nodig. En het is voor machines lastig om te leren van ongestructureerde data. Om machines onze code en content beter te laten begrijpen kunnen we informatie labelen. En één methode daarvoor is structured data doormiddel van JSON+LD.

tl;dr; Het eerste deel vertelt de hoe en waarom van JSON+LD. Mocht je dit al weten/begrijpen dan kan je ook direct naar de voorbeelden gaan.

Wat is JSON+LD?

De eerste vraag is, wat is JSON. JSON staat voor JavaScript Object Notation en is een manier waarop we data kunnen omschrijven en er als volgt uitziet:

{
  'company_name': 'OrangeTalent',
  'contact_options: {
    'email': 'info@orangetalent.nl',
    'website': 'https://www.orangetalent.nl' 
  }
}

JSON wordt onder andere gebruikt om data uit te wisselen tussen verschillende systemen, maar ook voor de communicatie tussen front-end en back-end.

JSON+LD is een laag bovenop JSON, waarbij LD staat voor ‘Linked Data’. JSON+LD is een specificatie die is vastgesteld door de W3C (de organisatie die de web standaarden beheren). Deze specificatie voegt onderdelen toe aan JSON om te kunnen linken naar externe URL’s en zo ook gebruik te maken van schema’s.

In de praktijk plaatsen we JSON+LD in de <head> (of ergens anders) in de HTML van onze websites. Hier komen we later in het artikel op terug. Met JSON+LD kunnen we informatie specificeren over een document, organisatie, recepten, artikel, auteur, koppelingen naar andere platformen, enzovoort. JSON+LD is niet alleen om interne verbindingen te leggen, maar ook om verbindingen naar buiten te definiëren. Zo kan je in de JSON+LD voor een organisatie ook je social media profielen linken.

Gestructureerde data

HTML brengt structuur aan je content, maar HTML is ook voor elke website anders. Waar de ene ontwikkelaar kiest om een <h1> te gebruiken als kop voor zijn artikel, gebruikt de ander een <h2>. En weer anderen gebruiken helemaal geen koppen (wat niet aan te raden is). Machines zoals de Google Bot hebben het moeilijk om je inhoud te indexeren en zullen het daarbij ook vaak genoeg fout interpreteren.

Daarnaast is er informatie die je niet zichtbaar wil maken op je website, maar die wel interessant kunnen zijn voor machines. Bijvoorbeeld wanneer een artikel voor het laatst geüpdatet is, welke social media profielen bij een auteur van een artikel horen, enzovoort.

Met JSON+LD kunnen we een vast standaard gebruiken die makkelijk begrepen kan worden door bijvoorbeeld Google.

Hoe kunnen we JSON+LD toevoegen aan een website?

Er is geen vaste plek waar JSON+LD moet staan in een HTML document. Meestal plaatsen we het in de <head> van een website, maar het kan ook voorkomen dat we halverwege de <body> een JSON+LD van een artikel plaatsen.

JSON+LD ziet er als volgt uit:

<script type="application/ld+json">
{ 
    "@context": "http://schema.org",
    "@type": "Organization",
    "url": "https://www.orangetalent.dev"
}
</script>

Wat hier vooral opvalt is @context en @type. Deze twee geven aan welk schema gebruikt wordt. Als we dit schema bekijken op schema.org dan kunnen we zien welke velden beschikbaar zijn en door ons gevuld kunnen worden.

Elk schema heeft veel velden die door ons gevuld kunnen worden. Maar over het algemeen zijn onze JSON+LD implementaties vooral gericht op zoekmachines (Google, Bing) en sociale media (op dit moment voornamelijk Facebook). En deze partijen ondersteunen maar een klein aantal schema’s (er komen wel regelmatig nieuwe bij), en van de ondersteunde schema’s weer een klein deel van de velden.

Een aantal schema’s die gebruikt worden en de moeite waard zijn om te specificeren voor de grote platformen zijn:

  • Article - Google kan blogposts makkelijker oppakken en toont bijvoorbeeld ook de publicatie datum in de zoekresultaten.
  • Breadcrumb - Maakt het voor machines duidelijk hoe je website gestructureerd is.
  • Event - Evenementen worden in de zoekresultaten van Google getoond als mensen zoeken op bijv. “feest in Ermelo dit weekend.” Er is zelfs de mogelijkheid om je evenement zo op te maken, dat tickets vanuit Google besteld kunnen worden.
  • JobPosting - Google komt met Google Jobs. Wanneer je vacatures opmaakt met de JobPosting specificatie zullen deze in Google Jobs terug komen.
  • Product - Door deze op te maken kan Google bijvoorbeeld prijzen, beschikbaarheid en een review score tonen in de zoekresultaten.

Voor alle, op dit moment mogelijke JSON+LD schema’s, kan je in de Google documentatie kijken. Zij geven ook code voorbeelden van de verschillende schema’s.

JSON+LD in code

@id

Veel data in je JSON+LD schema’s kunnen dubbel zijn. Om dubbele informatie te voorkomen kunnen we gebruik maken van @id om te linken naar andere blokken JSON+LD in je HTML. Bijvoorbeeld:

<script type="application/ld+json">
{
    "@context": "http://schema.org",
    "@id": "orangetalent-organization",
    "@type": "Organization",
    // Meer informatie
}
</script>

<script type="application/ld+json">
{
    "@context": "http://schema.org",
    "@type": "Article",
    "title": "Ons blog bericht",
    "author": {
        "@id": "orangetalent-organization"
    },
    "publisher": {
        "@id": "orangetalent-organization"
    }
}
</script>

We hebben eerst een algemeen organisatie JSON+LD blok geplaatst (mogelijk hebben we die op elke pagina). Zodra we een artikel willen opmaken met JSON+LD kunnen we de auteur met een @id koppelen.

mainEntitityOfPage

mainEntitityOfPage zul je ook vaak tegenkomen in JSON+LD. Het geeft aan op welke URL het beschreven item ‘primair’ is. Stel dat je een blogpost aan het opmaken bent, dan is de URL van het artikel de mainEntityOfPage.

Voorbeeld:

<script type="application/ld+json">
{
    "@context": "http://schema.org",
    "@type": "Article",
    "title": "Ons blog bericht",
    "mainEntityOfPage": "https://www.orangetalent.nl/nieuws/ons-blog-bericht"
}
</script>

Voorbeeld: Organization

Het eerste wat we doen is de organisatie in JSON+LD zetten. Vrijwel elke website heeft wel een organisatie. Een voorbeeld van onze eigen website (met wat kleine wijzigingen):

<script type="application/ld+json">
{
    "@context": "http://schema.org",
    "@type": "Organization",
    "@id": "https://www.orangetalent.nl#identity",
    "logo": "https://www.orangetalent.nl/img/logo.png",
    "image": "https://www.orangetalent.nl/img/logo.png",
    "name": "OrangeTalent",
    "address": {
        "@type": "PostalAddress",
        "streetAddress": "Jagerserf 24",
        "addressLocality": "Ermelo",
        "postalCode": "3851SM",
        "addressCountry": "The Netherlands"
    },
    "url": "https://www.orangetalent.nl",
    "telephone": "+31341123456",
    "contactPoint": [{
        "@type": "ContactPoint",
        "telephone": "+31341123456",
        "contactType": "customer service",
        "areaServed": "nl",
        "availableLanguage": "Dutch"
    }],
    "sameAs": [
        "https://twitter.com/orangetalent",
        "https://www.facebook.com/orangetalentnl/",
        "https://www.linkedin.com/company/orangetalent/",
        "https://www.instagram.com/orangetalent/"
    ]
}
</script>

Veel van de informatie zal voor zich spreken, logo's, naam, adres, klantenservice/contactpunt, telefoonnummer en URL. sameAs is wat lastiger te begrijpen, Schema.org definieert het als volgt:

URL of a reference Web page that unambiguously indicates the item's identity.

In bovenstaande stuk code hebben we een @id geplaatst die we later in andere JSON+LD blokken terugzien.

Voorbeeld: Article

We kunnen artikelen of blogposts ook opmaken met JSON+LD. Hiervan komt in ieder geval de publicatiedatum in Google terug. En met een beetje geluk wordt een artikel ook in de nieuws carousel van Google getoond.

Een voorbeeld:

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "Person",
    "@id": "https://www.orangetalent.nl#person",
    "description": "Omschrijving van persoon",
    "jobTitle": "Functieomschrijving",
    "name": "Naam van auteur",
    "mainEntityOfPage": "https://www.orangetalent.nl/over-ons/team/naam-van-auteur",
    "memberOf": {
        "@id": "https://www.orangetalent.nl#identity"
    }
}
</script>

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "Article",
    "mainEntityOfPage": {
        "@type": "WebPage",
        "@id": "https://www.orangetalent.nl/inspiratie/blog-post"
    },
    "headline": "Blogpost",
    "image": [
        "https://www.orangetalent.nl/media/afbeelding.jpg"
    ],
    "datePublished": "2019-07-16T00:00:00+02:00",
    "dateModified": "2019-08-21T11:11:08+02:00",
    "author": {
        "@id": "https://www.orangetalent.nl#person"
    },
    "publisher": {
        "@id": "https://www.orangetalent.nl#identity"
    },
    "copyrightHolder": {
        "@id": "https://www.orangetalent.nl#identity"
    },
    "description": "Omschrijving van blogpost"
}
</script>

In het eerste onderdeel definiëren we een persoon, deze kunnen we net als een Organization doormiddel van de @id hergebruiken. Deze persoon is ook gekoppeld aan de organisatie met memberOf.

Het tweede deel bevat het daadwerkelijke artikel. Bovenaan staat de mainEntityOfPage waar we het ook over hebben gehad. Dit geeft aan waar het artikel zich bevindt.

Met de @id koppelingen zien we terug dat we de auteur, Publisher en copyright houder koppelen.

Voorbeeld: JobPosting

Google Jobs is een nieuwe toevoeging van Google’s assortiment aan diensten. Google Jobs is/wordt een vacaturebank die ‘automatisch’ gevuld wordt met vacatures. Om ervoor te zorgen dat ook de vacatures op jouw website worden opgepakt kunnen we deze opmaken met JSON+LD.

<script type="application/ld+json">
{
    "@context": "http://schema.org",
    "@type": "JobPosting",
    "title": "Vacature titel",
    "description": "Vacature omschrijving",
    "hiringOrganization": {
        "@id": "https://www.orangetalent.nl#identity"
    },
    "employmentType": "FULL_TIME",
    "occupationalCategory": "categorie_naam",
    "jobLocation": {
        "@type": "Place",
        "address": {
            "@type": "PostalAddress",
            "streetAddress": "Jagerserf 24",
            "addressLocality": "Ermelo",
            "postalCode": "3851SM",
            "addressCountry": "NL"
        }
    },
    "workHours": "32-40 hours per week",
    "datePosted": "2019-06-06"
}
</script>

Er begint zich een trend te vormen in de manier waarop de JSON+LD geschreven wordt. We zien weer een @id koppeling in hiringOrganization. En we zien ook geneste JSON+LD blokken in het geval van bijvoorbeeld de Place.

Hoe kan ik JSON+LD testen en controleren?

In bovenstaande voorbeelden zie je een klein deel van de mogelijke velden. Ik heb in ieder geval de verplichte velden laten zien, maar er is nog veel meer mogelijk. Toch blijft de vraag, hoe kunnen we onze JSON+LD implementatie testen?

Ten eerste kan je de documentatie doorlezen van Google. Deze hebben een aantal belangrijke schema’s beschreven en welke velden verplicht zijn. Voor nog meer informatie kan je in schema.org zoeken naar een specifiek schema.

Ten tweede heeft Google een tool gemaakt die JSON+LD valideert. Deze heet de Google Structured Data Testing Tool. Daarin kan je een URL of directe HTML invoeren. Aan de rechterkant worden de gevonden blokken getoond en eventuele waarschuwingen en fouten weergeven. Sommige van de typen kunnen ook in een voorbeeldweergave worden bekeken.

En als laatste kan je zodra je JSON+LD online staat alles in de gaten houden met Google Search Console. Alles wat te maken heeft met de indexering van je website in Google kan je daar terugvinden. Na livegang van je JSON+LD kan het mogelijk een paar dagen duren voordat resultaten te zien zijn. Hierin zie je ook welke mogelijke fouten er in je gestructureerde data zitten.

Conclusie

JSON+LD is een waardevolle toevoeging aan je website om data te structureren zodat machines het makkelijk kunnen begrijpen. Het grootste deel van de voorbeelden hierboven is gericht op Google, en dat is voor ons één van de belangrijkste redenen om JSON+LD in te zetten op websites. Maar ook Bing ondersteund gestructureerde data met JSON+LD.