diff --git a/jsoncstyleguide.xml b/jsoncstyleguide.xml index ab2dfa7..010c585 100644 --- a/jsoncstyleguide.xml +++ b/jsoncstyleguide.xml @@ -21,7 +21,7 @@ This style guide contains many details that are initially hidden from view. The -

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.

+

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.

For the purposes of this style guide, we define the following terms:

@@ -129,8 +129,8 @@ JSON maps can use any Unicode character in key names. // The "thumbnails" property is a map that maps // a pixel size to the thumbnail url of that size. "thumbnails": { - "72": "http://url.to.72px.thumbnail", - "144": "http://url.to.144px.thumbnail" + "72": "https://url.to.72px.thumbnail", + "144": "https://url.to.144px.thumbnail" } } @@ -212,10 +212,10 @@ Avoid naming conflicts by choosing a new property name or versioning the API. -Property values must be Unicode booleans, numbers, strings, objects, arrays, or null. +Property values must be booleans, numbers, Unicode strings, objects, arrays, or null. -

The spec at JSON.org specifies exactly what type of data is allowed in a property value. This includes Unicode booleans, numbers, strings, objects, arrays, and null. JavaScript expressions are not allowed. APIs should support that spec for all values, and should choose the data type most appropriate for a particular property (numbers to represent numbers, etc.).

Good:

+

The spec at JSON.org specifies exactly what type of data is allowed in a property value. This includes booleans, numbers, Unicode strings, objects, arrays, and null. JavaScript expressions are not allowed. APIs should support that spec for all values, and should choose the data type most appropriate for a particular property (numbers to represent numbers, etc.).

Good:

{ "canPigsFly": null, // null @@ -334,7 +334,7 @@ Latitudes/Longitudes should be formatted as recommended by ISO 6709.
-

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.

+

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 recommended. 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?; @@ -661,7 +661,7 @@ Property Value Type: array
Parent: data
-

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.

+

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.

Property Value Type: integer
Parent: data @@ -935,7 +935,7 @@ Property Value Type: string
Parent: error.errors { "error":{ - "code": 404 + "code": 404, "message": "File Not Found", "errors": [{"message": "File Not Found"}] } @@ -985,7 +985,7 @@ Property Value Type: string
Parent: error.errors { "error":{ - "errors": [{"extendedHelper": "http://url.to.more.details.example.com/"}] + "errors": [{"extendedHelper": "https://url.to.more.details.example.com/"}] } }