JSON Style Guide

Apply Google's JSON Style Guide conventions for consistent, well-structured JSON APIs and data formats.

Overview

This skill provides guidelines for creating JSON APIs and data structures following Google's JSON Style Guide. The guide clarifies naming conventions, property structures, reserved property names, and standard patterns for JSON requests and responses in both RPC-based and REST-based APIs.

Core Principles

Use Double Quotes

All property names must be surrounded by double quotes. String values must use double quotes. Other value types (boolean, number, null, arrays, objects) should not be quoted.

json

{
  "propertyName": "string value",
  "count": 42,
  "isActive": true,
  "data": null
}

No Comments

Do not include comments in JSON objects. JSON does not support comments in the specification.

Flatten Data Appropriately

Data should be flattened unless there is a clear semantic reason for structured hierarchy. Group properties only when they represent a single logical structure.

Structured (preferred for related data):

json

{
  "company": "Google",
  "address": {
    "line1": "111 8th Ave",
    "city": "New York",
    "state": "NY",
    "zip": "10011"
  }
}

Property Naming

Naming Format

Property names must:

Be meaningful with defined semantics
Use camelCase (not snake_case or PascalCase)
Start with a letter, underscore (_), or dollar sign ($)
Contain only letters, digits, underscores, or dollar signs
Avoid JavaScript reserved keywords

json

{
  "firstName": "John",
  "lastName": "Doe",
  "accountBalance": 1000.50,
  "isVerified": true
}

Singular vs Plural

Use plural names for arrays. Use singular names for all other properties.

json

{
  "author": "lisa",
  "siblings": ["bart", "maggie"],
  "totalItems": 10,
  "itemCount": 10
}

JSON Maps vs Objects

When using a JSON object as a map (associative array), keys can use any Unicode characters. Map keys do not need to follow property naming guidelines.

json

{
  "address": {
    "addressLine1": "123 Anystreet",
    "city": "Anytown"
  },
  "thumbnails": {
    "72": "https://url.to.72px.thumbnail",
    "144": "https://url.to.144px.thumbnail"
  }
}

Property Values

Valid Value Types

Property values must be:

Boolean:
```
true
```
or
```
false
```
Number: integers or floating-point
String: Unicode strings in double quotes
Object:
```
{}
```
Array:
```
[]
```
Null:
```
null
```

JavaScript expressions and functions are not allowed.

Empty or Null Values

Consider removing properties with empty or null values unless there is a strong semantic reason. A property with value

false

, or

""

may have semantic meaning and should be kept.

json

{
  "volume": 10,
  "balance": 0,
  "currentlyPlaying": null
}

Better:

json

{
  "volume": 10,
  "balance": 0
}

Enum Values

Represent enums as strings (not numbers) to handle graceful changes as APIs evolve.

json

{
  "color": "WHITE",
  "status": "ACTIVE"
}

Standard Data Types

Dates

Format dates according to RFC 3339:

json

{
  "lastUpdate": "2007-11-06T16:34:41.000Z",
  "createdAt": "2024-02-19T10:30:00.000Z"
}

Time Durations

Format durations according to ISO 8601:

json

{
  "duration": "P3Y6M4DT12H30M5S"
}

Latitude/Longitude

Format coordinates according to ISO 6709 using ±DD.DDDD±DDD.DDDD degrees format:

json

{
  "location": "+40.6894-074.0447"
}

Standard JSON Structure

Top-Level Properties

A JSON response should have these optional top-level properties:

```
apiVersion
```
- Version of the API (string)
```
context
```
- Client-set value echoed by server (string)
```
id
```
- Server-assigned response identifier (string)
```
method
```
- Operation performed (string)
```
params
```
- Input parameters for RPC requests (object)
```
data
```
- Container for successful response data (object)
```
error
```
- Error details if request failed (object)

A response should contain either

data

error

, but not both.

json

{
  "apiVersion": "2.1",
  "data": {
    "kind": "user",
    "id": "12345",
    "name": "John Doe"
  }
}

Data Object Properties

Common properties in the

data

object:

```
kind
```
- Type of object (should be first property)
```
fields
```
- Fields present in partial response
```
etag
```
- Entity tag for versioning
```
id
```
- Unique identifier
```
lang
```
- Language code (BCP 47)
```
updated
```
- Last update timestamp (RFC 3339)
```
deleted
```
- Boolean marker for deleted entries
```
items
```
- Array of items (should be last property)

Pagination Properties

For paginated data in the

data

object:

```
currentItemCount
```
- Number of items in current response
```
itemsPerPage
```
- Requested page size
```
startIndex
```
- Index of first item (1-based)
```
totalItems
```
- Total available items
```
pageIndex
```
- Current page number (1-based)
```
totalPages
```
- Total number of pages
```
pagingLinkTemplate
```
- URI template for pagination

Link Properties

Link properties in the

data

object:

```
self
```
/
```
selfLink
```
- Link to retrieve this resource
```
edit
```
/
```
editLink
```
- Link to update/delete this resource
```
next
```
/
```
nextLink
```
- Link to next page
```
previous
```
/
```
previousLink
```
- Link to previous page

Error Object Properties

When an error occurs, use the

error

object:

```
code
```
- HTTP status code (integer)
```
message
```
- Human-readable error message (string)
```
errors
```
- Array of error details (array)

Each error in

errors

array can have:

```
domain
```
- Service identifier
```
reason
```
- Error type identifier
```
message
```
- Detailed error message
```
location
```
- Where error occurred
```
locationType
```
- How to interpret location
```
extendedHelp
```
- URI to help documentation
```
sendReport
```
- URI to error report form

json

{
  "apiVersion": "2.0",
  "error": {
    "code": 404,
    "message": "File Not Found",
    "errors": [{
      "domain": "Calendar",
      "reason": "ResourceNotFoundException",
      "message": "File Not Found"
    }]
  }
}

Property Ordering

While property order is not enforced by JSON, certain orderings improve parsing efficiency:

kind
should be first - Helps parsers determine object type early
items
should be last in
data
- Allows reading collection metadata before parsing items

json

{
  "data": {
    "kind": "album",
    "title": "My Photo Album",
    "totalItems": 100,
    "items": [
      {
        "kind": "photo",
        "title": "My First Photo"
      }
    ]
  }
}

Quick Reference

Naming Checklist

Use camelCase for property names
Use plural names for arrays
Use singular names for other properties
Avoid JavaScript reserved keywords
Choose meaningful, semantic names

Value Type Checklist

Use strings for enum values
Format dates as RFC 3339
Format durations as ISO 8601
Remove null/empty values unless semantically meaningful
Use appropriate types (boolean, number, string, object, array, null)

Structure Checklist

Include
```
apiVersion
```
in responses
Use
```
data
```
for success,
```
error
```
for failures (not both)
Place
```
kind
```
first in objects
Place
```
items
```
last in
```
data
```
object
Use reserved property names for standard semantics

Additional Resources

Reference Files

For detailed specifications:

references/naming-conventions.md
- Complete naming rules and reserved keywords
references/reserved-properties.md
- Full list of reserved property names and their semantics
references/pagination-patterns.md
- Detailed pagination implementation patterns

Example Files

Working examples in

examples/

examples/api-response.json
- Standard API response structure
examples/error-response.json
- Error handling example
examples/paginated-response.json
- Pagination example with all properties

json-style

NPX Install

Tags

SKILL.md Content

JSON Style Guide

Overview

Core Principles

Use Double Quotes

No Comments

Flatten Data Appropriately

Property Naming

Naming Format

Singular vs Plural

JSON Maps vs Objects

Property Values

Valid Value Types

Empty or Null Values

Enum Values

Standard Data Types

Dates

Time Durations

Latitude/Longitude

Standard JSON Structure

Top-Level Properties

Data Object Properties

Pagination Properties

Link Properties

Error Object Properties

Property Ordering

Quick Reference

Naming Checklist

Value Type Checklist

Structure Checklist

Additional Resources

Reference Files

Example Files