google JSON風格指南
原文連接：https://github.com/darcyliu/google-styleguide/blob/master/JSONStyleGuide.mdjavascript
版本：0.9html
英文版：https://google.github.io/styleguide/jsoncstyleguide.xmljava
翻譯：Darcy Liugit
譯文狀態：草稿github
簡介
該風格指南是對在Google建立JSON APIs而提供的指導性準則和建議。整體來說，JSON APIs應遵循JSON.org上的規範。這份風格指南澄清和標準化了特定狀況，從而使Google的JSON APIs有一種標準的外觀和感受。這些指南適用於基於RPC和基於REST風格的API的JSON請求和響應。web
定義
爲了更好地實現這份風格指南的目的，下面幾項須要說明：apache
- 屬性(property) - JSON對象內的鍵值對(name/value pair)
- 屬性名(property name) - 屬性的名稱(或鍵)
- 屬性值(property value) - 分配給屬性的值
示例：json
{
// 一組鍵值對稱做一個 "屬性".
"propertyName": "propertyValue"
}
Javascript的數字(number)包含全部的浮點數,這是一個寬泛的指定。在這份指南中，數字(number)指代Javascript中的數字(number)類型，而整型(integer)則指代整型。api
通常準則
註釋
JSON對象中不包含註釋。數組
JSON對象中不該該包含註釋。該指南中的某些示例含有註釋。但這僅僅是爲了說明示例。
{
// 你可能在下面的示例中看到註釋,
// 但不要在你的JSON數據中加入註釋.
"propertyName": "propertyValue"
}
雙引號
使用雙引號
若是（某個）屬性須要引號，則必須使用雙引號。全部的屬性名必須在雙引號內。字符類型的屬性值必須使用雙引號。其它類型值（如布爾或數字）不該該使用雙引號。
扁平化數據 VS 結構層次
不能爲了方便而將數據任意分組
JSON中的數據元素應以扁平化方式呈現。不能爲了方便而將數據任意分組。
在某些狀況下，好比描述單一結構的一批屬性，由於它被用來保持結構層次，於是是有意義的。可是遇到這些狀況仍是應當慎重考慮，記住只有語義上有意義的時候才使用它。例如，一個地址能夠有表示兩種方式，但結構化的方式對開發人員來說可能更有意義：
扁平化地址:
{
"company": "Google",
"website": "http://www.google.com/",
"addressLine1": "111 8th Ave",
"addressLine2": "4th Floor",
"state": "NY",
"city": "New York",
"zip": "10011"
}
結構化地址：
{
"company": "Google",
"website": "http://www.google.com/",
"address": {
"line1": "111 8th Ave",
"line2": "4th Floor",
"state": "NY",
"city": "New York",
"zip": "10011"
}
}
屬性名準則
屬性名格式
選擇有意義的屬性名
屬性名必須遵循如下準則:
- 屬性名應該是具備定義語義的有意義的名稱。
- 屬性名必須是駝峯式的，ASCII碼字符串。
- 首字符必須是字母，下劃線(_)或美圓符號($)。
- 隨後的其餘字符能夠是字母，數字，下劃線(_)或美圓符號($)。
- 應該避免使用Javascript中的保留關鍵字(下文附有Javascript保留字清單)
這些準則反映JavaScript標識符命名的指導方針。使JavaScript的客戶端可使用點符號來訪問屬性。(例如, result.thisIsAnInstanceVariable).
下面是一個對象的一個屬性的例子：
{
"thisPropertyIsAnIdentifier": "identifier value"
}
JSON Map中的鍵名
在JSON Map中鍵名可使用任意Unicode字符
當JSON對象做爲Map(映射)使用時，屬性的名稱命名規則並不適用。Map（也稱做關聯數組）是一個具備任意鍵/值對的數據類型，這些鍵/值對經過特定的鍵來訪問相應的值。JSON對象和JSON Map在運行時看起來是同樣的；這個特性與API設計相關。當JSON對象被看成map使用時，API文件應當作出說明。
Map的鍵名不必定要遵循屬性名稱的命名準則。鍵名能夠包含任意的Unicode字符。客戶端可以使用maps熟悉的方括號來訪問這些屬性。（例如result.thumbnails["72"]）
{
// "address" 屬性是一個子對象
// 包含地址的各部分.
"address": {
"addressLine1": "123 Anystreet",
"city": "Anytown",
"state": "XX",
"zip": "00000"
},
// "address" 是一個映射
// 含有響應規格所對應的URL，用來映射thumbnail url的像素規格
"thumbnails": {
"72": "http://url.to.72px.thumbnail",
"144": "http://url.to.144px.thumbnail"
}
}
保留的屬性名稱
某些屬性名稱會被保留以便能在多個服務間相容使用
保留屬性名稱的詳細信息，連同完整的列表，可在本指南後面的內容中找到。服務應按照被定義的語義來使用屬性名稱。
單數屬性名 VS 複數屬性名
數組類型應該是複數屬性名。其它屬性名都應該是單數。
數組一般包含多個條目，複數屬性名就反映了這點。在下面這個保留名稱中能夠看到例子。屬性名items是複數由於它描述的是一組對象。大多數的其它字段是單數。
固然也有例外，尤爲是涉及到數字的屬性值的時候。例如，在保留屬性名中，totalItems 比 totalItem更合理。而後，從技術上講，這並不違反風格指南，由於 totalItems 能夠被看做 totalOfItems, 其中 total 是單數（依照風格指南），OfItems 用來限定總數。字段名也可被改成 itemCount，這樣看起來更象單數.
{
// 單數
"author": "lisa",
// 一組同胞, 複數
"siblings": [ "bart", "maggie"],
// "totalItem" 看起來並不對
"totalItems": 10,
// 但 "itemCount" 要好些
"itemCount": 10
}
命名衝突
經過選擇新的屬性名或將API版本化來避免命名衝突
新的屬性可在未來被添加進保留列表中。JSON中不存在命名空間。若是存在命名衝突，可經過選擇新的屬性名或者版本化來解決這個問題。例如，假設咱們由下面的JSON對象開始：
{
"apiVersion": "1.0",
"data": {
"recipeName": "pizza",
"ingredients": ["tomatoes", "cheese", "sausage"]
}
}
若是咱們但願未來把ingredients列爲保留字，咱們能夠經過下面兩件事情來達成:
1.選一個不一樣的名字
{
"apiVersion": "1.0",
"data": {
"recipeName": "pizza",
"ingredientsData": "Some new property",
"ingredients": ["tomatoes", "cheese", "sausage"]
}
}
2.在主版本上從新命名屬性
{
"apiVersion": "2.0",
"data": {
"recipeName": "pizza",
"ingredients": "Some new property",
"recipeIngredients": ["tomatos", "cheese", "sausage"]
}
}
屬性值準則
屬性值格式
屬性值必須是Unicode 的 booleans（布爾）, 數字(numbers), 字符串(strings), 對象(objects), 數組(arrays), 或 null.
JSON.org上的標準準確地說明了哪些類型的數據能夠做爲屬性值。這包含Unicode的布爾(booleans), 數字(numbers), 字符串(strings), 對象(objects), 數組(arrays), 或 null。JavaScript表達式是不被接受的。APIs應該支持該準則，併爲某個特定的屬性選擇最合適的數據類型（好比，用numbers表明numbers等）。
好的例子：
{
"canPigsFly": null, // null
"areWeThereYet": false, // boolean
"answerToLife": 42, // number
"name": "Bart", // string
"moreData": {}, // object
"things": [] // array
}
很差的例子：
{
"aVariableName": aVariableName, // Bad - JavaScript 標識符
"functionFoo": function() { return 1; } // Bad - JavaScript 函數
}
空或Null 屬性值
考慮移除空或null值
若是一個屬性是可選的或者包含空值或null值，考慮從JSON中去掉該屬性，除非它的存在有很強的語義緣由。
{
"volume": 10,
// 即便 "balance" 屬性值是零, 它也應當被保留,
// 由於 "0" 表示 "均衡"
// "-1" 表示左傾斜和"＋1" 表示右傾斜
"balance": 0,
// "currentlyPlaying" 是null的時候可被移除
// "currentlyPlaying": null
}
枚舉值
枚舉值應當以字符串的形式呈現
隨着APIs的發展，枚舉值可能被添加，移除或者改變。將枚舉值看成字符串可使下游用戶幽雅地處理枚舉值的變動。
Java代碼：
public enum Color {
WHITE,
BLACK,
RED,
YELLOW,
BLUE
}
JSON對象：
{
"color": "WHITE"
}
屬性值數據類型
上面提到，屬性值必須是布爾(booleans), 數字(numbers), 字符串(strings), 對象(objects), 數組(arrays), 或 null. 然而在處理某些值時，定義一組標準的數據類型是很是有用的。這些數據類型必須始終是字符串，可是爲了便於解析，它們也會以特定的方式被格式化。
日期屬性值
日期應該使用RFC3339建議的格式
日期應該是RFC 3339所建議的字符串格式。
{
"lastUpdate": "2007-11-06T16:34:41.000Z"
}
時間間隔屬性值
時間間隔應該使用ISO 8601建議的格式
時間間隔應該是ISO 8601所建議的字符串格式。
{
// 三年, 6個月, 4天, 12小時,
// 三十分鐘, 5秒
"duration": "P3Y6M4DT12H30M5S"
}
緯度/經度屬性值
緯度/經度應該使用ISO 6709建議的格式
緯度/經度應該是ISO 6709所建議的字符串格式。 並且, 它應該更偏好使用 e ±DD.DDDD±DDD.DDDD 角度格式.
{
// 自由女神像的緯度/經度位置.
"statueOfLiberty": "+40.6894-074.0447"
}
JSON結構和保留屬性名
爲了使APIs保持一致的藉口，JSON對象應當使用如下的結構。該結構適用於JSON的請求和響應。在這個結構中，某些屬性名將被保留用做特殊用途。這些屬性並非必需的，也就是說，每一個保留的屬性可能出現零次或一次。可是若是服務須要這些屬性，建議遵循該命名條約。下面是一份JSON結構語義表，以Orderly格式呈現(如今已經被歸入 JSONSchema)。你能夠在該指南的最後找到關於JSON結構的例子。
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?;
}*;
JSON對象有一些頂級屬性，而後是data對象或error對象，這二者不會同時出現。下面是這些屬性的解釋。
頂級保留屬性名稱
頂級的JSON對象可能包含下面這些屬性
apiVersion
屬性值類型: 字符串(string) 父節點: -
呈現請求中服務API指望的版本，以及在響應中保存的服務API版本。應隨時提供apiVersion。這與數據的版本無關。將數據版本化應該經過其餘的機制來處理，如etag。
示例：
{ "apiVersion": "2.1" }
context
屬性值類型: 字符串(string) 父節點: -
客戶端設置這個值，服務器經過數據做出迴應。這在JSON-P和批處理中頗有用，用戶可使用context將響應與請求關聯起來。該屬性是頂級屬性，由於無論響應是成功仍是有錯誤，context總應當被呈現出來。context不一樣於id在於context由用戶提供而id由服務分配。
示例：
請求 #1:
http://www.google.com/myapi?context=bart
請求 #2:
http://www.google.com/myapi?context=lisa
響應 #1:
{
"context": "bart",
"data": {
"items": []
}
}
響應 #2:
{
"context": "lisa",
"data": {
"items": []
}
}
公共的JavaScript處理器經過編碼同時處理如下兩個響應：
function handleResponse(response) {
if (response.result.context == "bart") {
// 更新頁面中的 "Bart" 部分。
} else if (response.result.context == "lisa") {
// 更新頁面中的 "Lisa" 部分。
}
}
id
屬性值類型: 字符串(string) 父節點: -
服務提供用於識別響應的標識(不管請求是成功仍是有錯誤)。這對於將服務日誌和單獨收到的響應對應起來頗有用。
示例：
{ "id": "1" }
method
屬性值類型: 字符串(string) 父節點: -
表示對數據即將執行，或已被執行的操做。在JSON請求的狀況下，method屬性能夠用來指明對數據進行何種操做。在JSON響應的狀況下，method屬性代表對數據進行了何種操做。
一個JSON-RPC請求的例子，其中method屬性表示要在params上執行的操做：
{
"method": "people.get",
"params": {
"userId": "@me",
"groupId": "@self"
}
}
params
屬性值類型: 對象(object) 父節點: -
這個對象做爲輸入參數的映射發送給RPC請求。它能夠和method屬性一塊兒用來執行RPC功能。若RPC方法不須要參數，則能夠省略該屬性。
示例：
{
"method": "people.get",
"params": {
"userId": "@me",
"groupId": "@self"
}
}
data
屬性值類型: 對象(object) 父節點: -
包含響應的全部數據。該屬性自己擁有許多保留屬性名，下面會有相應的說明。服務能夠自由地將本身的數據添加到這個對象。一個JSON響應要麼應當包含一個data對象，要麼應當包含error對象，但不能二者都包含。若是data和error同時出現，則error對象優先。
error
屬性值類型: 對象(object) 父節點: -
代表錯誤發生，提供錯誤的詳細信息。錯誤的格式支持從服務返回一個或多個錯誤。一個JSON響應能夠有一個data對象或者一個error對象，但不能二者都包含。若是data和error都出現，error對象優先。
示例：
{
"apiVersion": "2.0",
"error": {
"code": 404,
"message": "File Not Found",
"errors": [{
"domain": "Calendar",
"reason": "ResourceNotFoundException",
"message": "File Not Found
}]
}
}
data對象的保留屬性名
JSON對象的data屬性可能包含如下屬性。
data.kind
屬性值類型: 字符串(sting) 父節點: data
kind屬性是對某個特定的對象存儲何種類型的信息的指南。能夠把它放在data層次，或items的層次，或其它任何有助於區分各種對象的對象中。若是kind對象被提供，它應該是對象的第一個屬性（詳見下面的屬性順序部分）。
示例：
// "Kind" indicates an "album" in the Picasa API.
{"data": {"kind": "album"}}
data.fields
屬性值類型: 字符串(string) 父節點: data
表示作了部分GET以後響應中出現的字段，或作了部分PATCH以後出如今請求中的字段。該屬性僅在作了部分GET請求/批處理時存在，且不能爲空。
示例：
{
"data": {
"kind": "user",
"fields": "author,id",
"id": "bart",
"author": "Bart"
}
}
data.etag
屬性值類型: 字符串(string) 父節點: data
響應時提供etag。關於GData APIs中的ETags詳情能夠在這裏找到：http://code.google.com/apis/gdata/docs/2.0/reference.html#ResourceVersioning
示例：
{"data": {"etag": "W/"C0QBRXcycSp7ImA9WxRVFUk.""}}
data.id
屬性值類型: 字符串(string) 父節點: data
一個全局惟一標識符用於引用該對象。id屬性的具體細節都留給了服務。
示例：
{"data": {"id": "12345"}}
data.lang
屬性值類型: 字符串(string)(格式由BCP 47指定) 父節點: data (或任何子元素)
表示該對象內其餘屬性的語言。該屬性模擬HTML的lang屬性和XML的xml:lang屬性。值應該是BCP 47中定義的一種語言值。若是一個單一的JSON對象包含的數據有多種語言，服務負責制定和標明lang屬性的適當位置。
示例：
{"data": {
"items": [
{ "lang": "en",
"title": "Hello world!" },
{ "lang": "fr",
"title": "Bonjour monde!" }
]}
}
data.updated
屬性值類型: 字符串(string)(格式由RFC 3339指定) 父節點: data
指明條目更新的最後日期/時間(RFC 3339)，由服務規定。
示例：
{"data": {"updated": "2007-11-06T16:34:41.000Z"}}
data.deleted
屬性值類型: 布爾(boolean) 父節點: data (或任何子元素)
一個標記元素，當出現時，表示包含的條目已被刪除。若是提供了刪除屬性，它的值必須爲true;爲false會致使混亂，應該避免。
示例：
{"data": {
"items": [
{ "title": "A deleted entry",
"deleted": true
}
]}
}
data.items
屬性值類型: 數組(array) 父節點: data
屬性名items被保留用做表示一組條目(例如,Picasa中的圖片，YouTube中的視頻)。這種結構的目的是給與當前結果相關的集合提供一個標準位置。例如，知道頁面上的items是數組，JSON輸出即可能插入一個通用的分頁系統。若是items存在，它應該是data對象的最後一個屬性。（詳見下面的屬性順序部分）。
示例：
{
"data": {
"items": [
{ /* Object #1 */ },
{ /* Object #2 */ },
...
]
}
}
用於分頁的保留屬性名
下面的屬性位於data對象中，用來給一列數據分頁。一些語言和概念是從OpenSearch規範中借鑑過來的。
下面的分頁數據容許各類風格的分頁，包括：
- 上一頁/下一頁 - 容許用戶在列表中前進和後退，一次一頁。nextLink 和previousLink屬性 (下面的"連接保留屬性名"部分有描述) 用於這種風格的分頁。
- 基於索引的分頁 - 容許用戶直接跳到條目列表的某個條目位置。例如，要從第200個條目開始載入10個新的條目，開發者能夠給用戶提供一個URL的查詢字符串?startIndex=200。
- 基於頁面的分頁 - 容許用戶直接跳到條目內的具體頁。這跟基於索引的分頁很相似,但節省了開發者額外的步驟，不需再爲新一頁的條目計算條目索引。例如，開發人員能夠直接跳到第20頁，而不是跳到第200條條目。基於頁面分頁的網址，可使用查詢字符串?page=1或?page=20。pageIndex和 totalPages 屬性用做這種風格的分頁.
在這份指南的最後能夠找到如何使用這些屬性來實現分頁的例子。
data.currentItemCount
屬性值類型: 整數(integer) 父節點: data
結果集中的條目數目。應該與items.length相等，並做爲一個便利屬性提供。例如，假設開發者請求一組搜索條目，而且要求每頁10條。查詢集共有14條。第一個條目頁將會有10個條目，所以itemsPerPage和currentItemCount都應該等於10。下一頁的條目還剩下4條；itemsPerPage仍然是10,可是currentItemCount是4.
示例：
{
"data": {
// "itemsPerPage" 不須要與 "currentItemCount" 匹配
"itemsPerPage": 10,
"currentItemCount": 4
}
}
data.itemsPerPage
屬性值類型: 整數(integer) 父節點: data
items結果的數目。未必是data.items數組的大小；若是咱們查看的是最後一頁，data.items的大小可能小於itemsPerPage。可是，data.items的大小不該超過itemsPerPage。
示例：
{
"data": {
"itemsPerPage": 10
}
}
data.startIndex
屬性值類型: 整數(integer) 父節點: data
data.items中第一個條目的索引。爲了一致，startIndex應從1開始。例如，第一組items中第一條的startIndex應該是1。若是用戶請求下一組數據，startIndex多是10。
示例：
{
"data": {
"startIndex": 1
}
}
data.totalItems
屬性值類型: 整數(integer) 父節點: data
當前集合中可用的總條目數。例如，若是用戶有100篇博客文章，響應可能只包含10篇，可是totalItems應該是100。
示例：
{
"data": {
"totalItems": 100
}
}
data.pagingLinkTemplate
屬性值類型: 字符串(string) 父節點: data
URL模板指出用戶能夠如何計算隨後的分頁連接。URL模板中也包含一些保留變量名：表示要載入的條目的{index}，和要載入的頁面的{pageIndex}。
示例：
{
"data": {
"pagingLinkTemplate": "http://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N"
}
}
data.pageIndex
屬性值類型: 整數(integer) 父節點: data
條目的當前頁索引。爲了一致，pageIndex應從1開始。例如，第一頁的pageIndex是1。pageIndex也能夠經過基於條目的分頁而計算出來pageIndex = floor(startIndex / itemsPerPage) + 1。
示例：
{
"data": {
"pageIndex": 1
}
}
data.totalPages
屬性值類型: 整數(integer) 父節點: data
當前結果集中的總頁數。totalPages也能夠經過上面基於條目的分頁屬性計算出來: totalPages = ceiling(totalItems / itemsPerPage).。
示例：
{
"data": {
"totalPages": 50
}
}
用於連接的保留屬性名
下面的屬性位於data對象中，用來表示對其餘資源的引用。有兩種形式的連接屬性：1）對象，它能夠包含任何種類的引用（好比JSON-RPC對象），2)URL字符串，表示資源的URIs(後綴總爲'Link')。
data.self / data.selfLink
屬性值類型: 對象(object)/字符串(string) 父節點: data
自身連接能夠用於取回條目數據。好比，在用戶的Picasa相冊中，條目中的每一個相冊對象都會包含一個selfLink用於檢索這個相冊的相關數據。
示例：
{
"data": {
"self": { },
"selfLink": "http://www.google.com/feeds/album/1234"
}
}
data.edit / data.editLink
屬性值類型: 對象(object)/字符串(string) 父節點: data
編輯連接代表用戶能夠發送更新或刪除請求。這對於REST風格的APIs頗有用。該連接僅在用戶可以更新和刪除該條目時提供。
示例：
{
"data": {
"edit": { },
"editLink": "http://www.google.com/feeds/album/1234/edit"
}
}
data.next / data.nextLink
屬性值類型: 對象(object)/字符串(string) 父節點: data
該下一頁連接標明如何取得更多數據。它指明載入下一組數據的位置。它能夠同itemsPerPage，startIndex 和 totalItems 屬性一塊兒使用用於分頁數據。
示例：
{
"data": {
"next": { },
"nextLink": "http://www.google.com/feeds/album/1234/next"
}
}
data.previous / data.previousLink
屬性值類型: 對象(object)/字符串(string) 父節點: data
該上一頁連接標明如何取得更多數據。它指明載入上一組數據的位置。它能夠連同itemsPerPage，startIndex 和 totalItems 屬性用於分頁數據。
示例：
{
"data": {
"previous": { },
"previousLink": "http://www.google.com/feeds/album/1234/next"
}
}
錯誤對象中的保留屬性名
JSON對象的error屬性應包含如下屬性。
error.code
屬性值類型: 整數(integer) 父節點: error
表示該錯誤的編號。這個屬性一般表示HTTP響應碼。若是存在多個錯誤，code應爲第一個出錯的錯誤碼。
示例：
{
"error":{
"code": 404
}
}
error.message
屬性值類型: 字符串(string) 父節點: error
一我的類可讀的信息，提供有關錯誤的詳細信息。若是存在多個錯誤，message應爲第一個錯誤的錯誤信息。
示例：
{
"error":{
"message": "File Not Found"
}
}
error.errors
屬性值類型: 數組(array) 父節點: error
包含關於錯誤的附加信息。若是服務返回多個錯誤。errors數組中的每一個元素表示一個不一樣的錯誤。
示例：
{ "error": { "errors": [] } }
error.errors[].domain
屬性值類型: 字符串(string) 父節點: error.errors
服務拋出該錯誤的惟一識別符。它幫助區分服務的從普通協議錯誤(如,找不到文件)中區分出具體錯誤(例如，給日曆插入事件的錯誤)。
示例：
{
"error":{
"errors": [{"domain": "Calendar"}]
}
}
error.errors[].reason
屬性值類型: 字符串(string) 父節點: error.errors
該錯誤的惟一識別符。不一樣於error.code屬性，它不是HTTP響應碼。
示例：
{
"error":{
"errors": [{"reason": "ResourceNotFoundException"}]
}
}
error.errors[].message
屬性值類型: 字符串(string) 父節點: error.errors
一我的類可讀的信息，提供有關錯誤的更多細節。若是隻有一個錯誤，該字段應該與error.message匹配。
示例：
{
"error":{
"code": 404
"message": "File Not Found",
"errors": [{"message": "File Not Found"}]
}
}
error.errors[].location
屬性值類型: 字符串(string) 父節點: error.errors
錯誤發生的位置（根據locationType字段解釋該值）。
示例：
{
"error":{
"errors": [{"location": ""}]
}
}
error.errors[].locationType
屬性值類型: 字符串(string) 父節點: error.errors
標明如何解釋location屬性。
示例：
{
"error":{
"errors": [{"locationType": ""}]
}
}
error.errors[].extendedHelp
屬性值類型: 字符串(string) 父節點: error.errors
help text的URI，使錯誤更易於理解。
示例：（注：原示例這裏有筆誤，中文版這裏作了校訂）
{
"error":{
"errors": [{"extendedHelp": "http://url.to.more.details.example.com/"}]
}
}
error.errors[].sendReport
屬性值類型: 字符串(string) 父節點: error.errors
report form的URI，服務用它來收集錯誤狀態的數據。該URL會預先載入描述請求的參數
示例：
{
"error":{
"errors": [{"sendReport": "http://report.example.com/"}]
}
}
屬性順序
在JSON對象中屬性可有任意順序。然而，在某些狀況下，有序的屬性能夠幫助分析器快速解釋數據，並帶來更好的性能。在移動環境下的解析器就是個例子，在這種狀況下，性能和內存是相當重要的，沒必要要的解析也應儘可能避免。
Kind屬性
Kind屬性應爲第一屬性
假設一個解析器負責將一個原始JSON流解析成一個特定的對象。kind屬性會引導解析器將適合的對象實例化。於是它應該是JSON對象的第一個屬性。這僅適用於對象有一個kind屬性的狀況(一般能夠在data和items屬性中找到)。
Items屬性
items應該是data對象的最後一個屬性
這使得閱讀每個具體條目前前已讀全部的集合屬性。在有不少條目的狀況下，這樣就避免了開發人員只須要從數據的字段時沒必要要的解析這些條目。
這讓閱讀全部集合屬性先於閱讀單個條目。如遇多個條目的狀況，當開發者僅須要數據中的字段時，這就可避免解析沒必要要的條目。
屬性順序示例：
// "kind" 屬性區分 "album" 和 "photo".
// "Kind" 始終是它父對象的第一個屬性.
// "items" 屬性是 "data" 對象的最後一個屬性.
{
"data": {
"kind": "album",
"title": "My Photo Album",
"description": "An album in the user's account",
"items": [
{
"kind": "photo",
"title": "My First Photo"
}
]
}
}
示例
YouTube JSON API
這是YouTube JSON API響應對象的示例。你能夠從中學到更多關於YouTube JSON API的內容：http://code.google.com/apis/youtube/2.0/developers_guide_jsonc.html
{
"apiVersion": "2.0",
"data": {
"updated": "2010-02-04T19:29:54.001Z",
"totalItems": 6741,
"startIndex": 1,
"itemsPerPage": 1,
"items": [
{
"id": "BGODurRfVv4",
"uploaded": "2009-11-17T20:10:06.000Z",
"updated": "2010-02-04T06:25:57.000Z",
"uploader": "docchat",
"category": "Animals",
"title": "From service dog to SURFice dog",
"description": "Surf dog Ricochets inspirational video ...",
"tags": [
"Surf dog",
"dog surfing",
"dog",
"golden retriever",
],
"thumbnail": {
"default": "http://i.ytimg.com/vi/BGODurRfVv4/default.jpg",
"hqDefault": "http://i.ytimg.com/vi/BGODurRfVv4/hqdefault.jpg"
},
"player": {
"default": "http://www.youtube.com/watch?v=BGODurRfVv4&feature=youtube_gdata",
"mobile": "http://m.youtube.com/details?v=BGODurRfVv4"
},
"content": {
"1": "rtsp://v5.cache6.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYDSANFEgGUgZ2aWRlb3MM/0/0/0/video.3gp",
"5": "http://www.youtube.com/v/BGODurRfVv4?f=videos&app=youtube_gdata",
"6": "rtsp://v7.cache7.c.youtube.com/CiILENy73wIaGQn-Vl-0uoNjBBMYESARFEgGUgZ2aWRlb3MM/0/0/0/video.3gp"
},
"duration": 315,
"rating": 4.96,
"ratingCount": 2043,
"viewCount": 1781691,
"favoriteCount": 3363,
"commentCount": 1007,
"commentsAllowed": true
}
]
}
}
分頁示例
如何將Google搜索條目做爲JSON對象展示出來，對分頁變量也有特別關注。
這個示例僅用做說明。下面的API實際上並不存在。
這是Google搜索結果頁面的示例： 
這是該頁面JSON形式的呈現：
{
"apiVersion": "2.1",
"id": "1",
"data": {
"query": "chicago style pizza",
"time": "0.1",
"currentItemCount": 10,
"itemsPerPage": 10,
"startIndex": 11,
"totalItems": 2700000,
"nextLink": "http://www.google.com/search?hl=en&q=chicago+style+pizza&start=20&sa=N"
"previousLink": "http://www.google.com/search?hl=en&q=chicago+style+pizza&start=0&sa=N",
"pagingLinkTemplate": "http://www.google.com/search/hl=en&q=chicago+style+pizza&start={index}&sa=N",
"items": [
{
"title": "Pizz'a Chicago Home Page"
// More fields for the search results
}
// More search results
]
}
}
這是如何展示屏幕截圖中的色塊的例子（背景顏色對應下圖中的顏色）
- Results 11 - 20 of about 2,700,000 = startIndex
- Results 11 - 20 of about 2,700,000 = startIndex + currentItemCount - 1
- Results 11 - 20 of about 2,700,000 = totalItems
- Search results = items (formatted appropriately)
- Previous/Next = previousLink / nextLink
- Numbered links in "Gooooooooooogle" = Derived from "pageLinkTemplate". The developer is responsible for calculating the values for {index} and substituting those values into the "pageLinkTemplate". The pageLinkTemplate's {index} variable is calculated as follows:
- Index #1 = 0 * itemsPerPage = 0
- Index #2 = 2 * itemsPerPage = 10
- Index #3 = 3 * itemsPerPage = 20
- Index #N = N * itemsPerPage
附錄
附錄A:JavaScript中的保留字
下列JavaScript保留字應該避免在屬性名中使用
下面的清單是JavaScript中的保留字，並不能經過點訪問符訪問。這份清單集合了當前最新的關鍵字，該清單可能會根據具體的執行環境而有所變動。
abstract boolean break byte case catch char class const continue debugger default delete do double else enum export exten33ds false final finally float for function goto if implements import in instanceof int interface let long native new null package private protected public return short static super switch synchronized this throw throws transient true try typeof var volatile void while with yield
除了特別說明，該頁面的內容均由共同創做協議(CC BY 3.0)受權許可，示例代碼均由Apache 2.0許可證受權許可）
－EOF-
Google 開源項目風格指南 (中文版) http://zh-google-styleguide.readthedocs.io/en/latest/
- 1. Python風格指南(Google版)
- 2. Google 開源項目風格指南
- 3. Google Java編程風格指南
- 4. [譯]Google C++編程風格指南（一）
- 5. Google JavaScript代碼風格指南
- 6. Google Java編程風格指南(中文)
- 7. Google Java 編程風格指南
- 8. Google JavaScript 代碼風格指南
- 9. Google HTML/CSS/JS代碼風格指南
- 10. Google C++編程風格指南
- 更多相關文章...
- • SQL 指南 - 網站建設指南
- • HTML 指南 - 網站建設指南
- • 算法總結-雙指針
- • IntelliJ IDEA代碼格式化設置
-
每一个你不满意的现在，都有一个你没有努力的曾经。