Google JSON Style Guide

Revision 0.9

Each style point has a summary for which additional information is available by toggling the accompanying arrow button that looks this way: . You may toggle all summaries with the big arrow button:

Toggle all summaries
Table of Contents

Overview

Important Note

Display Hidden Details in this Guide

This style guide contains many details that are initially hidden from view. They are marked by the triangle icon, which you see here on your left. Click it now. You should see "Hooray" appear below.

Introduction

This style guide documents guidelines and recommendations for building JSON APIs at Google. In general, JSON APIs should follow the spec found at JSON.org. This style guide clarifies and standardizes specific cases so that JSON APIs from Google have a standard look and feel. These guidelines are applicable to JSON requests and responses in both RPC-based and REST-based APIs.

Definitions

For the purposes of this style guide, we define the following terms:

{
  // The name/value pair together is a "property".
  "propertyName": "propertyValue"
}

Javascript's number type encompasses all floating-point numbers, which is a broad designation. In this guide, number will refer to JavaScript's number type, while integer will refer to integers.

General Guidelines

Comments

No comments in JSON objects.

Double Quotes

Use double quotes.

Flattened data vs Structured Hierarchy

Data should not be arbitrarily grouped for convenience.

Property Name Guidelines

Property Name Format

Choose meaningful property names.

Key Names in JSON Maps

JSON maps can use any Unicode character in key names.

Reserved Property Names

Certain property names are reserved for consistent use across services.

Singular vs Plural Property Names

Array types should have plural property names. All other property names should be singular.

Naming Conflicts

Avoid naming conflicts by choosing a new property name or versioning the API.

Property Value Guidelines

Property Value Format

Property values must be Unicode booleans, numbers, strings, objects, arrays, or null.

Empty/Null Property Values

Consider removing empty or null values.

Enum Values

Enum values should be represented as strings.

Property Value Data Types

As mentioned above, property value types must be booleans, numbers, strings, objects, arrays, or null. However, it is useful define a set of standard data types when dealing with certain values. These data types will always be strings, but they will be formatted in a specific manner so that they can be easily parsed.

Date Property Values

Dates should be formatted as recommended by RFC 3339.

Time Duration Property Values

Time durations should be formatted as recommended by ISO 8601.

Latitude/Longitude Property Values

Latitudes/Longitudes should be formatted as recommended by ISO 6709.

JSON Structure & Reserved Property Names

In order to maintain a consistent interface across APIs, JSON objects should follow the structure outlined below. This structure applies to both requests and responses made with JSON. Within this structure, there are certain property names that are reserved for specific uses. These properties are NOT required; in other words, each reserved property may appear zero or one times. But if a service needs these properties, this naming convention is recommend. Here is a schema of the JSON structure, represented in Orderly format (which in turn can be compiled into a JSONSchema). You can few examples of the JSON structure at the end of this guide.

object {
  string apiVersion?;
  string context?;
  string id?;
  string method?;
  object {
    string id?
  }* params?;
  object {
    string kind?;
    string fields?;
    string etag?;
    string id?;
    string lang?;
    string updated?; # date formatted RFC 3339
    boolean deleted?;
    integer currentItemCount?;
    integer itemsPerPage?;
    integer startIndex?;
    integer totalItems?;
    integer pageIndex?;
    integer totalPages?;
    string pageLinkTemplate /^https?:/ ?;
    object {}* next?;
    string nextLink?;
    object {}* previous?;
    string previousLink?;
    object {}* self?;
    string selfLink?;
    object {}* edit?;
    string editLink?;
    array [
      object {}*;
    ] items?;
  }* data?;
  object {
    integer code?;
    string message?;
    array [
      object {
        string domain?;
        string reason?;
        string message?;
        string location?;
        string locationType?;
        string extendedHelp?;
        string sendReport?;
      }*;
    ] errors?;
  }* error?;
}*;

The JSON object has a few top-level properties, followed by either a data object or an error object, but not both. An explanation of each of these properties can be found below.

Top-Level Reserved Property Names

The top-level of the JSON object may contain the following properties.

apiVersion

Property Value Type: string
Parent: -

context

Property Value Type: string
Parent: -

id

Property Value Type: string
Parent: -

method

Property Value Type: string
Parent: -

params

Property Value Type: object
Parent: -

data

Property Value Type: object
Parent: -

error

Property Value Type: object
Parent: -

Reserved Property Names in the data object

The data property of the JSON object may contain the following properties.

data.kind

Property Value Type: string
Parent: data

data.fields

Property Value Type: string
Parent: data

data.etag

Property Value Type: string
Parent: data

data.id

Property Value Type: string
Parent: data

data.lang

Property Value Type: string (formatted as specified in BCP 47)
Parent: data (or any child element)

data.updated

Property Value Type: string (formatted as specified in RFC 3339)
Parent: data

data.deleted

Property Value Type: boolean
Parent: data (or any child element)

data.items

Property Value Type: array
Parent: data

Reserved Property Names for Paging

The following properties are located in the data object, and help page through a list of items. Some of the language and concepts are borrowed from the OpenSearch specification.

The paging properties below allow for various styles of paging, including:

An example of how to use these properties to implement paging can be found at the end of this guide.

data.currentItemCount

Property Value Type: integer
Parent: data

data.itemsPerPage

Property Value Type: integer
Parent: data

data.startIndex

Property Value Type: integer
Parent: data

data.totalItems

Property Value Type: integer
Parent: data

data.pagingLinkTemplate

Property Value Type: string
Parent: data

data.pageIndex

Property Value Type: integer
Parent: data

data.totalPages

Property Value Type: integer
Parent: data

The following properties are located in the data object, and represent references to other resources. There are two forms of link properties: 1) objects, which can contain any sort of reference (such as a JSON-RPC object), and 2) URI strings, which represent URIs to resources (and will always be suffixed with "Link").

data.self / data.selfLink

Property Value Type: object / string
Parent: data

data.edit / data.editLink

Property Value Type: object / string
Parent: data

data.next / data.nextLink

Property Value Type: object / string
Parent: data

data.previous / data.previousLink

Property Value Type: object / string
Parent: data

Reserved Property Names in the error object

The error property of the JSON object may contain the following properties.

error.code

Property Value Type: integer
Parent: error

error.message

Property Value Type: string
Parent: error

error.errors

Property Value Type: array
Parent: error

error.errors[].domain

Property Value Type: string
Parent: error.errors

error.errors[].reason

Property Value Type: string
Parent: error.errors

error.errors[].message

Property Value Type: string
Parent: error.errors

error.errors[].location

Property Value Type: string
Parent: error.errors

error.errors[].locationType

Property Value Type: string
Parent: error.errors

error.errors[].extendedHelp

Property Value Type: string
Parent: error.errors

error.errors[].sendReport

Property Value Type: string
Parent: error.errors

Property Ordering

Properties can be in any order within the JSON object. However, in some cases the ordering of properties can help parsers quickly interpret data and lead to better performance. One example is a pull parser in a mobile environment, where performance and memory are critical, and unnecessary parsing should be avoided.

Kind Property

kind should be the first property

Items Property

items should be the last property in the data object

Property Ordering Example

Examples

YouTube JSON API

Here's an example of the YouTube JSON API's response object. You can learn more about YouTube's JSON API here: http://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html.

Paging Example

This example demonstrates how the Google search items could be represented as a JSON object, with special attention to the paging variables.

Appendix

Appendix A: Reserved JavaScript Words

A list of reserved JavaScript words that should be avoided in property names.

Revision 0.9