2024-06-06

understanding json-ld

When developing software, the decisions I often make were the type of data, i.e. "Should the data be JSON or XML or raw bytes?"

Sometimes I would even consider the format of my data when interfacing clients of different needs, i.e. "How should my objects be nested in such a way that my client can consume them more easily?"

Over time, engineers had recognized some common patterns in this type of server vs. client interactions and developed a generalized convention, which is json-ld.

json and json-ld

Json-ld stands for Json for Linked Data. It's data delivery convention to improve accessibility for machine. It's a good convention to follow when developing federated software over http.

There are also other types of conventions such as Microdata, RDFa, etc.

Here is an example json with 2 related person objects:

{
    "@type": "Person",
    "name": "alice",
    "children": [
        {
            "@type": "Person",
            "name": "bob",
            "children": []
        }
    ]
}

type

"@type" is a vocabulary denoting a concrete typed object in the code. The value of type is technically not bounded by any protocols or contracts. It can vary depending on the implementer's software design.

For example, Mastodon uses ActivityPub protocol's "Person" type to enable discoverability through webfinger.

"@type" can technically use any value. A popular use case is in the implmentation of AP (ActivityPub), where the AP specs offers a limited set of values that defines the various "@type" for Object or Actor.

headers

Additionally server side needs client request to specify the followed key value in the headers to denote the response data is indeed structured according to json-ld schema:

Accept: application/ld+json

context

@context is a vocabulary that data is being linked to. For example, the example context below is being linked to "schema.org":

"@context": "https://schema.org",

testing

To validate the accessibility of json-ld data, "schema.org" has a tool called validator to test the response data.