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
General Guidelines
	
Comments Double Quotes Flattened data vs Structured Hierarchy


Property Name Guidelines
	
Property Name Format Key Names in JSON Maps Reserved Property Names Singular vs Plural Property Names Naming Conflicts


Property Value Guidelines
	
Property Value Format Empty/Null Property Values Enum Values


Property Value Data Types
	
Date Property Values Time Duration Property Values Latitude/Longitude Property Values


JSON Structure & Reserved Property Names
	


Top-Level Reserved Property Names
	
apiVersion context id method params data error


Reserved Property Names in the data object
	
data.kind data.fields data.etag data.id data.lang data.updated data.deleted data.items


Reserved Property Names for Paging
	
data.currentItemCount data.itemsPerPage data.startIndex data.totalItems data.pagingLinkTemplate data.pageIndex data.totalPages


Reserved Property Names for Links
	
data.self / data.selfLink data.edit / data.editLink data.next / data.nextLink data.previous / data.previousLink


Reserved Property Names in the error object
	
error.code error.message error.errors error.errors[].domain error.errors[].reason error.errors[].message error.errors[].location error.errors[].locationType error.errors[].extendedHelp error.errors[].sendReport


Property Ordering
	
Kind Property Items Property Property Ordering Example


Examples
	
YouTube JSON API Paging Example


Appendix
	
Appendix A: Reserved JavaScript Words
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:

property - a name/value pair inside a JSON object.
property name - the name (or key) portion of the property.
property value - the value portion of the property.
{
  // 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 booleans, numbers, Unicode 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 recommended. 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:

Previous/Next paging - Allows user's to move forward and backward through a list, one page at a time. The nextLink and previousLink properties (described in the "Reserved Property Names for Links" section below) are used for this style of paging.
Index-based paging - Allows user's to jump directly to a specific item position within a list of items. For example, to load 10 items starting at item 200, the developer may point the user to a url with the query string ?startIndex=200.
Page-based paging - Allows user's to jump directly to a specific page within the items. This is similar to index-based paging, but saves the developer the extra step of having to calculate the item index for a new page of items. For example, rather than jump to item number 200, the developer could jump to page 20. The urls during page-based paging could use the query string ?page=1 or ?page=20. The pageIndex and totalPages properties are used for this style of paging.

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
Reserved Property Names for Links

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: https://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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License.

Revision 0.9
