Linked data

Json vs Json-ld

Many people might not be familiar with json-ld and that's ok. The most important thing to know about json-ld is that it's just json with a few extra special fields. Here is a brief explanation of the special json-ld fields you will encounter with Sambal.

"@context": ""   // To provide context about what vocabularies this data will use
                                   // For Sambal, @context is assumed to be so this field can be omitted
"@type": "BlogPosting"             // The type of the data
  "@id": /author/johnsmith.yml     // @id is json-ld's way of referencing another data fragment

A slightly more complicated json-ld

  "@vocab":     // Use vocabulary
  "@base":     // Set base url
"@type": "BlogPosting"
  - "@id": /author/johnsmith.yml   // Array of references
  - "@id": /author/janedoe.yml

You can set the @base in @context so all relative urls will be relative to this base url. In this case, the absolute url for /author/johnsmith.yml is There's obviously a lot more to json-ld than that. If you're interested, you can check out the full json-ld spec.

Everything is json-ld

In Sambal, every piece of data is assumed to be json-ld. Json-ld is a json based linked data format that allows you to reference another piece of data using the "@id" keyword. Sambal will recursively fetch all references in your json-ld. For example,

"@type": BlogPosting
headline: My first blog post
  "@id": /author/johnsmith.yml
My first blog post!

Both the author and image are referencing another piece of data by uri. Note that the author uri is a relative uri while the image uri is absolute. In Sambal, a relative uri references a local file relative to the root project folder.

Sambal will automatically fetch the references and hydrate the blogpost as such

    "@type": "BlogPosting",
    "headline": "My first blog post",
    "author": {
        "@type": "Person",
        "name": "John Smith",
        "familyName": "Smith",
        "givenName": "John"
    "image": {
        "@type": "ImageObject",
        "contentUrl": "",
        "encodingFormat": "image/webp",
        "width": "<actual width of image>",
        "height": "<actual height of image>"
    "text": "My first blog post!",
    "encodingFormat": "text/markdown"

Notice the image got transformed into a ImageObject json-ld too! Sambal can also auto generate thumbnails for images. Check out image for more detail.

What if you are unfamiliar with

While Sambal assume every data will be using vocabulary, it doesn't do any validation internally. This means that you can still use plain old json with your own schema, for example

title: My first blog post
  name: John Smith
tags: ["keyword1", "keyword2"]
My first blog post!

The downside is that you will not be able to use existing Sambal themes that expect format and that the json-ld files generated by Sambal will not validate with Google structured data testing tool.