diff --git a/jsoncstyleguide.css b/jsoncstyleguide.css deleted file mode 100644 index 108e43d..0000000 --- a/jsoncstyleguide.css +++ /dev/null @@ -1,102 +0,0 @@ -body { - background-color: #FFF; - color: #666; - font-family: sans-serif; - font-size: 10pt; - margin-right: 100px; - margin-left: 100px; -} - -h1, h2, h3, h4, h5, h6, .toc_title { - color: #06C; - margin-top: 2em; - margin-bottom: 1em; -} - -h1 { - text-align: center; - font-size: 18pt; -} - -h2, .toc_title { - font-weight: bold; - font-size: 12pt; - margin-left: -40px; -} - -h3, h4, h5, h6 { - font-size: 10pt; - margin-left: -20px; -} - -.toc_category, .toc_stylepoint { - font-size: 10pt; - padding-top: .3em; - padding-bottom: .3em; -} - -table { - border-collapse: collapse; -} - -td, th { - border-top: 1px solid #CCC; - border-bottom: 1px solid #CCC; - border-left: 5px solid #CCC; - border-right: 5px solid #CCC; - padding-left: 12px; - padding-right: 12px; -} - -code,samp,var { - color: #060; -} - -pre { - font-size: 10pt; - display: block; - color: #060; - background-color: #F8FFF8; - border-color: #F0FFF0; - border-style: solid; - border-top-width: 1px; - border-bottom-width: 1px; - border-right-width: 1px; - border-left-width: 5px; - padding-left: 12px; - padding-right: 12px; - padding-top: 4px; - padding-bottom: 4px; -} - -pre.badcode { - color: #C00; - background-color: #FFF8F8; - border-color: #FFF0F0; -} - -.showhide_button { - cursor: pointer; -} - -.link_button { - background-color: #F8F8FF; - border-color: #F0F0FF; - border-style: solid; - border-width: 1px; - font-size: 75%; - margin-top: 20px; - margin-left: -50px; - padding: 4px; - line-height: 0px; -} - -address { - text-align: right; -} - -hr { - margin-top: 10em; - border-width: 1px; - color: #FFF; -} \ No newline at end of file diff --git a/jsoncstyleguide.html b/jsoncstyleguide.html index dffb5bd..1bef466 100644 --- a/jsoncstyleguide.html +++ b/jsoncstyleguide.html @@ -1,2551 +1,18 @@ - - - -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, 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. -
- -
- -
- -
- -
- -
- - -

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

- - -
- -
- - - - + + + + + + + Redirecting + + + + Redirecting you to jsoncstyleguide.xml. + + diff --git a/styleguide.css b/styleguide.css index 2d4b1d6..adba8f3 100644 --- a/styleguide.css +++ b/styleguide.css @@ -1,13 +1,16 @@ body { - background-color: #ffffff; - color: black; - margin-right: 1in; - margin-left: 1in; + background-color: #fff; + color: #333; + font-family: sans-serif; + font-size: 10pt; + margin-right: 100px; + margin-left: 100px; } -h1, h2, h3, h4, h5, h6 { - color: #3366ff; - font-family: sans-serif; +h1, h2, h3, h4, h5, h6, .toc_title { + color: #06c; + margin-top: 2em; + margin-bottom: 1em; } h1 { @@ -15,105 +18,106 @@ h1 { font-size: 18pt; } -h2 { - margin-left: -0.5in; - margin-top: 0.5in; -} - -h3 { - margin-left: -0.25in; -} - -h4 { - margin-left: -0.125in; -} - -hr { - margin-left: -1in; -} - -.h2toc { - font-size: 12pt; - color: #3366ff; +h2, .toc_title { font-weight: bold; - margin-left: 0.5in; - line-height: 200%; + font-size: 12pt; + margin-left: -40px; } -.h3toc { - font-size: 11pt; - color: #3366ff; - font-weight: normal; - margin-left: 1in; +h3, h4, h5, h6 { + font-size: 10pt; + margin-left: -20px; } -/* Use the tag for bits of code and for variables and objects. */ -code,samp,var { - color: #005000; - font-size: 110%; +.toc_category, .toc_stylepoint { + font-size: 10pt; + padding-top: .3em; + padding-bottom: .3em; } -PRE { - margin-left: 2%; +table { + border-collapse: collapse; +} + +td, th { + border: 1px solid #ccc; + padding: 2px 12px; + font-size: 10pt; +} + +.toc td, .toc th { + border-width: 1px 5px; +} + +code, samp, var { + color: #060; +} + +pre { font-size: 10pt; display: block; - color: #005000; - background-color: #fbfefb; - border-color: #fafffa; - border-left-width: 1px; - border-right-width: 0px; - border-top-width: 0px; - border-bottom-width: 0px; + color: #060; + background-color: #f8fff8; + border-color: #f0fff0; border-style: solid; - border-top: 1px solid #fffaff; - border-left: 1px solid #fffaff; - border-right: 1px dotted #eff0ef; - border-bottom: 1px dotted #eff0ef; + border-top-width: 1px; + border-bottom-width: 1px; + border-right-width: 1px; + border-left-width: 5px; padding-left: 12px; padding-right: 12px; padding-top: 4px; padding-bottom: 4px; } -PRE { - -moz-border-radius: 12px; +pre.badcode { + color: #c00; + background-color: #fff8f8; + border-color: #fff0f0; } -PRE.badcode { - color: #CC0000; - background-color: #fffcfc; - border-right: 1px solid #f0efef; - border-bottom: 1px solid #f0efef; - border-top: 1px dotted #faffff; - border-left: 1px dotted #faffff; -} - -TABLE { - border-collapse: collapse; - border-color: #dddddd; - border-style: dotted; -} - -TD { - border-color: #bbbbbb; +.showhide_button { + float: left; + cursor: pointer; + border-width: 1px; border-style: solid; - border-width: thin + border-color: #ddd #aaa #aaa #ddd; + padding: 0 3px 1px; + margin: 0 4px 8px 0; + border-radius: 3px; + -webkit-border-radius: 3px; + -moz-border-radius: 3px; } -TH { - border-collapse: collapse; - border-color: #dddddd; - border-style: none; - border-width: thin; - color: #444444; - font-family: sans-serif; +.link_button { + float: left; + display: none; + background-color: #f8f8ff; + border-color: #f0f0ff; + border-style: solid; + border-width: 1px; + font-size: 75%; + margin-top: 0; + margin-left: -50px; + padding: 4px; + border-radius: 3px; + -webkit-border-radius: 3px; + -moz-border-radius: 3px; } address { text-align: right; } +hr { + margin-top: 3.5em; + border-width: 1px; + color: #fff; +} + .stylepoint_section { + display: block; + margin-bottom: 1em; color: #5588ff; font-family: sans-serif; font-size: 90%; @@ -129,53 +133,15 @@ address { margin-left: -1%; } -.showhide_button { - border-color: #dddddd; - border-style: outset; - border-width: medium; - cursor: pointer; +.stylepoint_subsubsection { + color: #667799; font-family: sans-serif; + font-size: 80%; + font-weight: bold; + margin-left: 0; } - -.link_button { - background-color: #ffffd0; - border-color: #fcfca0; - border-style: solid; - border-width: 1px; - font-family: sans-serif; - font-size: 75%; - font-variant: small-caps; - margin-left: -2%; - padding-left: 1px; - padding-right: 1px; - padding-top: 1px; - padding-bottom: 1px; +.revision { + text-align: right; } -.toc { - background-color: #fcfcff; - padding-left: 12px; - padding-right: 12px; - padding-top: 4px; - padding-bottom: 4px; -} - -.toc_title { - font-family: sans-serif; - font-size: 110%; - font-weight: 700; -} - -.toc_category { - margin-left: 5%; - font-family: sans-serif; -} - -.toc_stylepoint { - margin-left: 5%; - font-family: sans-serif; - font-size: 90%; - padding-top: 5px; - padding-bottom: 5px; -} diff --git a/styleguide.xsl b/styleguide.xsl index 2bba7aa..e82e8f1 100644 --- a/styleguide.xsl +++ b/styleguide.xsl @@ -32,10 +32,13 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> function ShowHideByName(bodyName, buttonName) { var bodyElements; + var linkElement; if (document.getElementsByName) { bodyElements = document.getElementsByName(bodyName); + linkElement = document.getElementsByName('link-' + buttonName)[0]; } else { bodyElements = [document.getElementById(bodyName)]; + linkElement = document.getElementById('link-' + buttonName); } if (bodyElements.length != 1) { alert("ShowHideByName() got the wrong number of bodyElements: " + bodyElements.length); @@ -50,9 +53,11 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> } if (bodyElement.style.display == "none" || bodyElement.style.display == "") { bodyElement.style.display = "inline"; + linkElement.style.display = "block"; buttonElement.innerHTML = ''; } else { bodyElement.style.display = "none"; + linkElement.style.display = "none"; buttonElement.innerHTML = ''; } } @@ -83,7 +88,8 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> if (root[i].className == 'showhide_button') { root[i].innerHTML = newButton; } - if (root[i].className == 'stylepoint_body') { + if (root[i].className == 'stylepoint_body' || + root[i].className == 'link_button') { root[i].style.display = newState; } } @@ -136,11 +142,12 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">

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:

- + @@ -152,7 +159,6 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> -

Overview

@@ -213,6 +219,12 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> ') + + + ?showone=# + link + + @@ -246,12 +258,6 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions"> display: none - - - ?showone=# - link - -
@@ -306,6 +312,14 @@ xmlns:fn="http://www.w3.org/2005/xpath-functions">

+ +

+ + + +

+ +