By Matthew TysonContributor, InfoWorld |JSON-LD looks to unite the promise of self-describing hypermedia with the simple familiarity of Json. By incorporating data links, JSON-LD lets developers add semantic information to a typical JSON API. Let's take a look at this powerful extension to JSON.JSON-LD (JavaScript Object Notation for Linked Data) extends the JSON format to include linking information. The extension has a wide range of uses from knowledge graphs to SEO. One of the most interesting use cases for JSON-LD is bringing JSON-based APIs closer to the original vision for REST, where hypermedia documents are self-describing and maintain loose coupling between server and client. A big problem with typical JSON APIs is that they create a strong coupling between the client and the server. The client knows where assets live and their relationships in the services. Hard-coding the URLs, as JSON does, creates a point of brittleness in clients. It contradicts the ideal of REST, wherein the assets themselves tell the client where to find the related information.At a high level, JSON-LD makes JSON a member of the semantic web, aka Web 3.0. The semantic web is an idea for how to make the web more meaningful. It looks to replace the current system of arbitrary locations with an interconnected network of related assets. This is a big project with many facets. For our discussion here, we'll focus on the hands-on experience of working with JSON-LD, by building an application that demonstrates the semantic web concept in a client-server setup.As described in Creating 3rd Generation Web APIs with Hydra, JSON-LD moves us toward the possibility of truly generic clients that can render and interact with services by interpreting the meta information contained in the data.To get a sense for how JSON-LD works, we'll build a small client-server application that serves JSON-LD from a Node.js server, along with a simple UI that lets us navigate the structure. We’ll use an interrelated set of data describing music. We’ll be able to start with a list of albums—just a couple to keep things simple—then click on an album name to see simple data about it. We'll also be able to click on a song name and see who the songwriters were.Let's start by displaying our albums by name and letting the user click on them for more information. Instead of hardcoding the URL where we've stored the album details, we'll use JSON-LD to define the URL in the JSON itself, as the ID. This setup moves us away from using a number for the ID and toward using the actual location.The data that the endpoint issues is typical JSON, except that it has the @id property. Properties beginning with the address sign (@ symbol) are JSON-LD-specific. In this case, we provide an actual link that the client can use. Note that in the Web 3.0 ideal, links would be absolute, to help form a universally navigable knowledge graph. We are using the relative URLs for development purposes.In a typical JSON API, we’d have an ID field and an integer for a value. Then, the client would form a URL based on that ID. In this case, the client can actually use the ID field as-is. The server handles such URLs as appropriate in the /music/albums/:albumId endpoint. (A real-world endpoint would require more sophisticated handling.)A simple client for this API would look like Listing 2.Listing 2 is a greatly simplified example, designed to highlight the main point: that the client can deal with the links in a generic fashion, by simply issuing fetch requests against the @id fields. This is a first step toward generalizing clients so that they avoid knowing about the structure of the service API.There is a lot more to JSON-LD, and the @context and @type fields are a big part of how it helps form semantic documents. There are several public repositories for context and type information that you can use, including schema.org, XML namespaces, and JSON-LD’s contexts. Schema.org is a consortium of search engines and is vast. XML Namespaces are ancient and familiar, and also more extensive. JSON-LD’s contexts are intended to be simpler and still comprehensive. An application can also define its own types, and use a blend of definition sources.The basic idea to the @context and @type fields is to let the JSON document describe what its content is in a (more) universally discoverable format.In Listing 3, we see how to use the schema.org @context and definitions like the MusicComposition @type.We've used the definition hosted at schema.org and given it the name “music.” The definition acts as a namespace when we give types to our data elements; in this case, music:MusicComposition and music:MusicGroup.The client can now use the @context and @type data. For a simple example, in our application, we could make decisions about how to display the data based on these fields. Note that the application isn’t actually fetching anything from schema.org; it’s only using it as a unique namespace and as a reference for structuring its own data.In reference to @type, it’s worth mentioning the notion of expand and compact. Expanding allows for a more verbose view, while compact makes for a tighter syntax. Expand will take the @type, like our music:MusicAlbum, and expand it to http://schema.org/MusicAlbum. Compact will do the reverse.Libraries like jsonls.js support these operations, and others, such as converting to RDF format.JSON-LD will play an important part in making semantic web ideals more realizable for developers. JSON is the lingua franca of API formats, and JSON-LD provides an easy entry point for adding semantic metadata to it. Next read this:Matthew Tyson is a founder of Dark Horse Group, Inc. He believes in people-first technology. When not playing guitar, Matt explores the backcountry and the philosophical hinterlands. He has written for JavaWorld and InfoWorld since 2007.Copyright © 2023 IDG Communications, Inc.Copyright © 2023 IDG Communications, Inc.