## 属性名格式 **选择有意义的属性名** 属性名必须遵循以下准则: * 属性名应该是具有定义语义的有意义的名称。 * 属性名必须是驼峰式的，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"] } } ~~~