JSON-LD Syntax and Integration

Introduction

Now that we know how to structure data using JSON and use schema.org to conceptualize Things, we can begin to learn how to serialize schema.org into JSON-LD.

Our JSON-LD code will be placed within the <head> of our web pages. We will use the <script> HTML element with the type attribute. The type attribute will hold a value for the ld+json MIME type, which is application/ld+json. In the following snippet, I place this element just before the closing </head> tag. The JSON-LD metadata will be placed between the opening and closing <script> tags.

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Using the Linux OS for Systems Administration</title>
        <base href="https://www.example.org/">
        <link rel="stylesheet" href="css/style.css">
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta name="author" content="C. Sean Burns">
        <meta name="description" content="An introduction to Systems Administration with Linux OS, including Debian and Ubuntu">
        <meta name="keywords" content="systems administration, linux, debian, ubuntu">
        <style>
            html { font-family: monospace; }
        </style> 
        <script type="application/ld+json">
        </script>
    </head>
    <body>
    </body>
</html>

Step 2: Creating a Data Model

In the last section, I showed how data models dictate the kind of metadata we can collect. I showed an initial example of how Dublin Core's fifteen main data fields can be used to capture specific metadata elements of a novel. That was a relatively easy example, and that's in large part because Dublin Core is a fairly flat and small schema. Knowing how to use schema.org to capture the important metadata elements is a bit more involved, and this is because schema.org is a big, general purpose taxonomy.

The first step in identifying the schema.org elements to use is to start with the content of the web page that you want to describe with schema.org. The next step is to identify the main topic(s) of that content. For example, is the main topic a person? If so, then we should start with the Person schema.org type. Or is the main topic an event, like a sporting event or a hackathon? Then we should start with the SportsEvent schema.org type or Hackathon schema.org type. Or are there multiple topics? In no way are you expected to memorize all the available Types that schema.org provides, however, identifying the needed Types does involve searching through schema.org to locate what's most relevant to your topic.

In the HTML snippet above, my made-up web page entails at least four topics:

Systems Administration
Linux
Debian
Ubuntu

Without knowing anything else, I can use these four topics to begin building a data model for my web page. However, I want to reiterate that in real-world practice, we build a JSON-LD data model based on the content and not just on what appears in the <title> and <meta> HTML tags. This is because JSON-LD is meant to capture details about the content in the web document and not just about the document overall.

For example, consider a recipe for Baked Kibbeh, a Lebanese dish made of lamb, bulgur wheat, onion, and spices, often eaten when the meat is raw and sometimes cooked. If we search the source code of the recipe's web page, we find that it uses JSON-LD. We can examine that JSON-LD by pasting the URL in the schema.org validator, and see that the entire recipe, including ingredients and recipe instructions, is described in the JSON-LD.

Content creators do not need to manually create their JSON-LD markup. The recipe site above likely uses JSON-LD generated by the Yoast SEO WordPress CMS plugin. Other CMS platforms can probably do similar things. The NY Times, the WSJ, and other major news platforms also embed JSON-LD and their JSON-LD are likely created through other automated mechanisms.

Step 3: Serializing schema.org as JSON-LD

When we create a JSON-LD data model for our web pages, we must use data extracted from the content on the web pages and no more. If our web page has an article on Linux Systems Administration, as suggested in the various <meta> elements in the above HTML snippet, then we must create a JSON-LD model based on that topic and on the content in that article only. If we add schema.org Types, Properties, and Instances to our JSON-LD that are not covered in the systems administration article, search engines will demote our website in their search results.

Here's a basic JSON-LD example that describes the Debian GNU/Linux distribution, one of the topics of my made-up webpage. Note that a JSON-LD object begins with an @context statement and a link to the schema.org site. Then, the @type is declared:

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "SoftwareApplication",
    "name": "Debian GNU/Linux",
    "description": "The Universal Operating System",
    "operatingSystem": "Debian",
    "softwareVersion": "12.10",
    "applicationCategory": "Operating System",
    "applicationSubCategory": "Linux Distribution",
    "memoryRequirements": "780MB",
    "storageRequirements": "1160MB",
    "url": "https://www.debian.org/",
    "downloadUrl": "https://www.debian.org/distrib",
    "releaseNotes": "https://www.debian.org/News/2025/20250315",
    "datePublished": "2025-03-15"
}
</script>

The above example is based on SoftwareApplication type. This is declared in the second line with "@type": "SoftwareApplication". This type entails a range of properties but also inherits properties from parent/ancestor types. That is, since SoftwareApplication is a descendant/subclass of the CreativeWork type, which itself is a subclass of Thing type, then SoftwareApplication can use properties from itself but also from CreativeWork and Thing. Therefore, in the JSON-LD code above, I use properties from SoftwareApplication but also from CreativeWork and Thing, as detailed at the schema.org link above and in the list below:

- Thing (TYPE), properties of Thing:
    - name
    - description
    - url
        - CreativeWork (TYPE), property of CreativeWork:
            - datePublished
                - SoftwareApplication (TYPE), properties of SoftwareApplication:
                    - applicationCategory
                    - applicationSubCategory
                    - downloadUrl
                    - memoryRequirements
                    - operatingSystem
                    - releaseNotes
                    - softwareVersion
                    - storageRequirements

The above JSON-LD is a good start, but we can capture more metadata about the Debian operating system. For example, the Debian OS is overseen by The Debian Project, which is a legal entity and the creator of the OS. We can modify our JSON-LD code to include that metadata. Specifically, we will use the creator property, which accepts either the Organization or Person properties as values (or instances). Since both instances are schema.org Types, we can create a nested JSON object: To capture more detail, we can list the main features of Debian using the featureList property of the SoftwareApplication type. I use a JSON list (using square brackets) to list the system's features. Remember that square brackets [] indicate a list of values (an array), while curly braces {} represent a nested object. If you need a refresher on how arrays and nested objects work in JSON, see the earlier section on JSON Basics.

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "SoftwareApplication",
    "name": "Debian GNU/Linux",
    "description": "The Universal Operating System",
    "operatingSystem": "Debian",
    "softwareVersion": "12.10",
    "applicationCategory": "Operating System",
    "applicationSubCategory": "Linux Distribution",
    "memoryRequirements": "780MB",
    "storageRequirements": "1160MB",
    "url": "https://www.debian.org/",
    "downloadUrl": "https://www.debian.org/distrib",
    "releaseNotes": "https://www.debian.org/News/2025/20250315",
    "datePublished": "2025-03-15",
    "license": "https://www.debian.org/legal/licenses/",
    "creator": {
        "@type": "Organization",
        "name": "Debian Project",
        "url": "https://www.debian.org/intro/about"
    },
    "featureList": [
        "free software",
        "stable",
        "secure",
        "extensive hardware support",
        "flexible installer",
        "smooth upgrades",
        "community-developed",
        "long-term support"
    ]
}

Finally, we're missing a subtle addition to the JSON-LD. My made-up web page is about using Debian for systems administration. It's not about Debian, per se. Thus, the above JSON-LD might be appropriate on the Debian homepage, but my web page talks about using Debian rather than being about Debian. Understanding this requires acquiring a judgment of thing's aboutness. In any case, to capture this distinction, I add the WebPage type to the JSON-LD, along with name and description properties, and make the rest of the JSON nested in that type. I also name the nested JSON-LD object as about:

<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "WebPage",
    "name": "Introduction to Linux Systems Administration with Debian",
    "description": "An educational web page covering systems administration with Linux, focusing on Debian GNU/Linux.",
    "about": {
        "@type": "SoftwareApplication",
        "name": "Debian GNU/Linux",
        "description": "The Universal Operating System",
        "operatingSystem": "Debian",
        "softwareVersion": "12.10",
        "applicationCategory": "Operating System",
        "applicationSubCategory": "Linux Distribution",
        "memoryRequirements": "780MB",
        "storageRequirements": "1160MB",
        "url": "https://www.debian.org/",
        "downloadUrl": "https://www.debian.org/distrib",
        "releaseNotes": "https://www.debian.org/News/2025/20250315",
        "datePublished": "2025-03-15",
        "license": "https://www.debian.org/legal/licenses/",
        "creator": {
            "@type": "Organization",
            "name": "Debian Project",
            "url": "https://www.debian.org/intro/about"
        },
        "featureList": [
            "free software",
            "stable",
            "secure",
            "extensive hardware support",
            "flexible installer",
            "smooth upgrades",
            "community-developed",
            "long-term support"
        ]
    }
}
</script>

Step 4: Validating Our JSON-LD

It's quite easy to make mistakes when manually writing JSON-LD code. Therefore, be sure to test your JSON-LD using the Schema Markup Validator. The validator will test both the syntax of your JSON-LD but also show if any schema.org types or properties are missing.

Also, the JSON-LD Playground is not a validator, but it's useful for visualizing your code.

You can also use the Rich Results Test tool. From the site, Rich results are experiences on Google surfaces, such as Search, that go beyond the standard blue link. Rich results can also include carousels, images, or other non-textual elements. In other words, Rich Results are those results that feature prominently at the top of a Google search and generally include images and other descriptive content about a search result. For this to work, include images on your site and describe them in your JSON-LD. Also, these types of results are based on a subset of structured data. See: Structured data markup that Google Search supports.

Step 5: Inserting JSON-LD in Your HTML Document

Now that I've completed my JSON-LD object that describes one aspect of the topic of my Linux Systems Administration page, I can add it to my web document. To do that, I insert the JSON-LD object into the <head> section. The following snippet illustrates this:

<!DOCTYPE html>
<html lang="en">
    <head>
        <title>Using the Linux OS for Systems Administration</title>
        <base href="https://www.example.org/">
        <link rel="stylesheet" href="css/style.css">
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1.0">
        <meta name="author" content="C. Sean Burns">
        <meta name="description" content="An introduction to Systems Administration with Linux OS, including Debian and Ubuntu">
        <meta name="keywords" content="systems administration, linux, debian, ubuntu">
        <style>
            html { font-family: monospace; }
        </style> 
<script type="application/ld+json">
{
    "@context": "https://schema.org",
    "@type": "WebPage",
    "name": "Introduction to Linux Systems Administration with Debian",
    "description": "An educational web page covering systems administration with Linux, focusing on Debian GNU/Linux.",
    "about": {
        "@type": "SoftwareApplication",
        "name": "Debian GNU/Linux",
        "description": "The Universal Operating System",
        "operatingSystem": "Debian",
        "softwareVersion": "12.10",
        "applicationCategory": "Operating System",
        "applicationSubCategory": "Linux Distribution",
        "memoryRequirements": "780MB",
        "storageRequirements": "1160MB",
        "url": "https://www.debian.org/",
        "downloadUrl": "https://www.debian.org/distrib",
        "releaseNotes": "https://www.debian.org/News/2025/20250315",
        "datePublished": "2025-03-15",
        "license": "https://www.debian.org/legal/licenses/",
        "creator": {
            "@type": "Organization",
            "name": "Debian Project",
            "url": "https://www.debian.org/intro/about"
        },
        "featureList": [
            "free software",
            "stable",
            "secure",
            "extensive hardware support",
            "flexible installer",
            "smooth upgrades",
            "community-developed",
            "long-term support"
        ]
    }
}

</script>
    </head>
    <body>
    </body>
</html>

If I have additional topics, I could add additional types to my JSON-LD. Generally, it's good to use JSON-LD that's fairly descriptive of the content on the page.

Note that JSON-LD isn't completely reusable across a site, since it's meant to mirror the content of a specific page. Therefore, each webpage on a website should include unique JSON-LD.

Conclusion

In this section, we explored how to describe web content using schema.org and JSON-LD. We learned how to model page content with appropriate types and properties, use JSON syntax to serialize metadata, validate the results, and add your JSON-LD to your web page.

Semantic Web Development