屬性名準則

屬性名格式

選擇有意義的屬性名

屬性名必須遵循以下準則:

• 屬性名應該是具有定義語義的有意義的名稱。
• 屬性名必須是駝峰式的，ASCII碼字符串。
• 首字符必須式字母，下劃線(__)或美元符號($_)。
• 隨后的其他字符可以是字母，數(shù)字，下劃線(__)或美元符號($_)。
• 應該避免使用Javascript中的保留關鍵字(下文附有Javascript保留字清單)

這些準則反映JavaScript標識符命名的指導方針。使JavaScript的客戶端可以使用點符號來訪問屬性。(例如,result.thisIsAnInstanceVariable).

下面是一個對象的一個屬性的例子：

{
  "thisPropertyIsAnIdentifier": "identifier value"
}

JSON Map中的鍵名

在JSON Map中鍵名可以使用任意Unicode字符

當JSON對象作為Map(映射)使用時，屬性的名稱命名規(guī)則并不適用。Map（也稱作關聯(lián)數(shù)組）是一個具有任意鍵/值對的數(shù)據(jù)類型，這些鍵/值對通過特定的鍵來訪問相應的值。JSON對象和JSON Map在運行時看起來是一樣的；這個特性與API設計相關。當JSON對象被當作map使用時，API文件應當做出說明。

Map的鍵名不一定要遵循屬性名稱的命名準則。鍵名可以包含任意的Unicode字符?？蛻舳丝墒褂胢aps熟悉的方括號來訪問這些屬性。（例如result.thumbnails["72"]）

{
  // "address" 屬性是一個子對象
  // 包含地址的各部分.
  "address": {
    "addressLine1": "123 Anystreet",
    "city": "Anytown",
    "state": "XX",
    "zip": "00000"
  },
  // "address" 是一個映射
  // 含有響應規(guī)格所對應的URL，用來映射thumbnail url的像素規(guī)格
  "thumbnails": {
    "72": "http://url.to.72px.thumbnail",
    "144": "http://url.to.144px.thumbnail"
  }
}

保留的屬性名稱

某些屬性名稱會被保留以便能在多個服務間相容使用

保留屬性名稱的詳細信息，連同完整的列表，可在本指南后面的內容中找到。服務應按照被定義的語義來使用屬性名稱。

單數(shù)屬性名 VS 復數(shù)屬性名

數(shù)組類型應該是復數(shù)屬性名。其它屬性名都應該是單數(shù)。

數(shù)組通常包含多個條目，復數(shù)屬性名就反映了這點。在下面這個保留名稱中可以看到例子。屬性名_items_是復數(shù)因為它描述的是一組對象。大多數(shù)的其它字段是單數(shù)。

當然也有例外，尤其是涉及到數(shù)字的屬性值的時候。例如，在保留屬性名中，totalItems?比?_totalItem_更合理。然后，從技術上講，這并不違反風格指南，因為?totalItems?可以被看作?totalOfItems, 其中?total?是單數(shù)（依照風格指南），OfItems?用來限定總數(shù)。字段名也可被改為?itemCount，這樣看起來更象單數(shù).

{
  // 單數(shù)
  "author": "lisa",
  // 一組同胞, 復數(shù)
  "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"]
  }
}