Give Codeship’s CI/CD Platform a Try

Want to learn more?

However, JSON by itself is pretty meaningless. Well. It has meaning, but only to the original creator of that format. They can share that meaning via documentation, conversation, or usage, but those often exist in places far removed from the JSON document you’re looking at.

What if the meaning itself was encoded directly into the document? What if every key in a JSON document had its own unique identity which you could look up (because web!) and read about its meaning? Wouldn’t that be slick?

You likely know what all that means (more or less). However, your software doesn’t, unless you coded it exactly to those string names. While there’s some possibility we picked the same keys (yay us!), there’s a higher likelihood we didn’t. We probably fix our :coffee: differently too. Who knows.

Currently, we’d need to write some code that took my JSON and turned the first_name key into your firstName key (or into first which is inside your name object or into given or… whatever). We’d then need to do that again the next time we found someone else with information about a person that used different key names. Rinse. Repeat.

What if we could match first_name, name.first, given, and even an obfuscated sadfeqpoif key into a meaningful Thing which made each of these “mean” the same thing? It can be done!

In this upgraded version of the earlier JSON document, you’ll see a new @context object. This object handles the mapping from my ad hoc terminology to the Schema.org vocabulary which is referenced via value of @vocab.

The key/value pairs below the @vocab key map directly to meaningful URLs at http://schema.org/. Now, my keys have meaning. Each key now has:

How does the @context object help get around that? We’re still just looking for the strings not the Things.

We have two options:

expansion

compaction

Expansion

Expansion in JSON-LD parlance means taking those meaningful, URL-based names and making them (at least within the processing code) actually be the URLs. Here’s the output from the expansion process done on both the above contextualized examples (remember! They’re identicial now!):

The above is the internal, identical representation in a JSON-LD processing system of both the above documents. It’s structured that way because there’s much more data that can (and likely will, in a real-life example) be added to those arrays, objects, etc.

However, you’re likely not currently inspired to switch all your JSON processing code to use this format. No worries! That’s where compaction comes in!

Compaction

JSON-LD processors will take the above two example docs, turn them into that expanded format, and then (if asked) turn them into a much more human-friendly compacted variation that looks like this:

Conclusion

I now have three different but meaningfully normalized variations of… myself. I can merge these in a number of ways depending on which data store I’m using. The keys all match now. They all have meaningful identifiers that, when followed, result in documentation for the key names. That’s far more than I got from the raw GET requests to these various APIs.

Next time you sit down to code up some JSON document — even one you think only you will use — consider mapping your key names to meaningful vocabulary terms via JSON-LD. Your future self will thank you.

Subscribe via Email

Over 60,000 people from companies like Netflix, Apple, Spotify and O'Reilly are reading our articles. Subscribe to receive a weekly newsletter with articles around Continuous Integration, Docker, and software development best practices.

We promise that we won't spam you. You can unsubscribe any time.

Join the Discussion

Leave us some comments on what you think about this topic or if you like to add something.