From 233b48fc747a4658094626a69d8d6be2fd82649d Mon Sep 17 00:00:00 2001 From: monsur Date: Wed, 24 Feb 2010 15:52:50 +0000 Subject: [PATCH] Adding an HTML version of the JSON-C Style Guide --- jsoncstyleguide.html | 2538 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 2538 insertions(+) create mode 100644 jsoncstyleguide.html diff --git a/jsoncstyleguide.html b/jsoncstyleguide.html new file mode 100644 index 0000000..e6ca10e --- /dev/null +++ b/jsoncstyleguide.html @@ -0,0 +1,2538 @@ + + + +Google JSON Style Guide + + + + + + +

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 +
+
+
+

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, and null. +
+ +
+ +
+ +
+ +
+

+Empty/Null Property Values +

+▶ + +
+If a property is optional or has an empty/null value, consider dropping the property from the JSON, unless there's a strong semantic reason for its existence. +
+ +
+ +
+ +
+ +
+

+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 time. 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 are related to paging items. Some of the language and concepts are borrowed from the OpenSearch specification. The paging properties listed below allows users to page based on number of items. However some services may wish to offer page-based paging. For example, rather than jump to item number 200, some services may request page number 20. For these cases, two page-based properties have been added: "pageIndex" and "totalPages". 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. +
+ +
+ +
+ +
+ +
+

+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 +

+ + +
+ +
+ + + +