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

A slightly more complicated json-ld

"@context":
  "@vocab": https://schema.org     // Use schema.org vocabulary
  "@base": https://example.com     // Set base url
"@type": "BlogPosting"
author:
  - "@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 https://example.com/author/johnsmith.yml. 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 schema.org json-ld

In Sambal, every piece of data is assumed to be schema.org 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
author:
  "@id": /author/johnsmith.yml
image:
  "@id": https://example.com/2021/media/image-1.webp
---
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": "https://example.com/2021/media/image-1.webp",
        "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 schema.org ImageObject json-ld too! Sambal can also auto generate thumbnails for images. Check out image for more detail.

What if you are unfamiliar with schema.org?

While Sambal assume every data will be using schema.org 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
author:
  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 schema.org format and that the json-ld files generated by Sambal will not validate with Google structured data testing tool.