From 254e0ebcb3f71182e0fba38a8c3fe036de9a78f5 Mon Sep 17 00:00:00 2001 From: Mike Frysinger Date: Fri, 25 Apr 2025 11:50:00 -0400 Subject: [PATCH] jsoncstyleguide: sync from latest internal version PiperOrigin-RevId: 751434392 --- jsoncstyleguide.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) 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:

  • Previous/Next paging - Allows user's to move forward and backward through a list, one page at a time. The nextLink and previousLink properties (described in the "Reserved Property Names for Links" section below) are used for this style of paging.
  • Index-based paging - Allows user's to jump directly to a specific item position within a list of items. For example, to load 10 items starting at item 200, the developer may point the user to a url with the query string ?startIndex=200.
  • Page-based paging - Allows user's to jump directly to a specific page within the items. This is similar to index-based paging, but saves the developer the extra step of having to calculate the item index for a new page of items. For example, rather than jump to item number 200, the developer could jump to page 20. The urls during page-based paging could use the query string ?page=1 or ?page=20. The pageIndex and totalPages properties are used for this style of paging.

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:

  • Previous/Next paging - Allows user's to move forward and backward through a list, one page at a time. The nextLink and previousLink properties (described in the "Reserved Property Names for Links" section below) are used for this style of paging.
  • Index-based paging - Allows user's to jump directly to a specific item position within a list of items. For example, to load 10 items starting at item 200, the developer may point the user to a url with the query string ?startIndex=200.
  • Page-based paging - Allows user's to jump directly to a specific page within the items. This is similar to index-based paging, but saves the developer the extra step of having to calculate the item index for a new page of items. For example, rather than jump to item number 200, the developer could jump to page 20. The urls during page-based paging could use the query string ?page=1 or ?page=20. The pageIndex and totalPages properties are used for this style of paging.

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/"}] } }