## 屬性名格式 **選擇有意義的屬性名** 屬性名必須遵循以下準則: * 屬性名應該是具有定義語義的有意義的名稱。 * 屬性名必須是駝峰式的，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"] } } ~~~