Expressing metadata in JSON
Introduction
Background
SData [1] is a standards-based protocol used by many Sage products to share information and promote integration. SData is based on HTTP (Hypertext Transfer Protocol), the protocol that powers most of the internet traffic around the globe, and is suitable for use in Application Programming Interfaces (APIs), mobile applications, and for application integration.
SData is published under a Creative Commons Licence, and may be freely reused as a specification.
SData version 1.0 was published in 2010, and updated in 2011 to the current version, v1.1. This document, along with four others defines the next version of SData, 2.0, which focuses on simplifying the protocol and introduces full support for JavaScript Object Notation (JSON) [2], alongside the XML and Atom support introduced in SData v1.0.
The full set of documents defining SData 2.0 is:
| "The underlying approach to evolving SData" | Outlines how the SData Working Group approached the task of updating the SData protocol while ensuring compatibility with implementations of version 1.0 and 1.1 already in use. |
| "SData 2.0 Core" | Defines the main elements of the SData protocol, explains how these elements are being updated (and in some cases, relaxed) for the 2.0 release, and outlines how JSON is being integrated into these elements. |
| "JSON formatted SData responses" | Defines the JSON format for SData content, focusing on structural aspects of content and representation. |
| "SData 2.0 Expressing metadata in JSON" | This document. Builds on the JSON formatted SData responses to define how providers should express metadata in JSON. |
| "SData 2.0 and Sage ID" | Specifies how Sage ID Authentication is handled in SData 2.0. |
Overview
When designing distributed systems, there is always a balance to be struck between flexibility and simplicity. One particular instance of this balance is in the amount of “hard-coded” or built-in knowledge that a client, or consumer, should have about the server, or provider, that it is using¹. Historically, consumers have been designed with significant amounts of built-in knowledge about the provider, tipping the balance in favour of simplicity and against flexibility. In this situation the provider needs only to provide raw information, as knowledge necessary to handle this raw information is encoded into the client. Increasingly, however, we are building more versatile clients, capable of communicating with several different providers and able to adapt, dynamically, to data and metadata from any given provider.
SData 2.0 is focused on supporting these more versatile clients and treats the representation, transport, and handling of metadata as an important protocol element. This document defines how SData providers should expose JSON metadata at the feed, entry and property level.
1. Provider” and “consumer” are used in SData broadly interchangeably with the terms “server” and “client”.