JSON을 규칙적으로 사용해보자 - Google JSON Style Guide

가이드 라인을 참고하여 작성하였습니다.

General Guidelines

주석

JSON은 주석을 포함하지 않는다.

• correct
• { "propertyName": "propertyValue" }
• wrong
• { // You may see comments in the examples below, // But don't include comments in your JSON. "propertyName": "propertyValue" }

쌍따옴표

모든 propertyName은 쌍따옴표로 둘러싸여 있어야 한다.

모든 propertyValue는 쌍따옴표로 둘러싸여 있어야 한다.

단, boolean이나 number는 안해도된다.

• correct
• { "propertyName": "propertyValue", "numberProperty": 123, "booleanProperty": true, }
• wrong
• { propertyName: propertyValue, numberProperty: 123, booleanProperty: true, }

---

Property Name Guidelines

Property Name Format

propertyName은 다음 가이드를 따를 것을 권장한다.

• propertyName은 의미있게 지어야 한다.
• propertyName은 camel-case, ascii strings 으로만 이루어져야한다.
• studentName, circleRadius …
• propertyName의 첫 글자는 영문자, 언더바 (_), 달러 ($)여야 한다.
• 첫 글자가 아니면 영문자, 숫자, 언더바 (_), 달러 ($)여야 한다.
• JavaScript 키워드는 사용하지 않는다.

Key Names in JSON Maps

map 안에 있는 key는 가이드라인을 따를 필요가 없다.

Singular VS Plural Property Name

Array(List) 유형은 복수의 속성 이름을 가져야 한다.

pens, icons …

전체 아이템 갯수를 나타내기 위해 totalItems를 사용한다 하면 오해의 여지가 생길 수 있다. 따라서 itemCount같은 좀 더 명확한 표현을 쓰자.

Naming Conflicts

propertyName이 충돌하는 것을 방지하기 위해 새로운 propertyName을 선택하거나, versioning을 한다.

{
  "apiVersion": "1.0",
  "data": {
    "recipeName": "pizza",
    "ingredients": ["tomatoes", "cheese", "sausage"]
  }
}

• 새로운 propertyName을 선택하는 경우
• { "apiVersion": "1.0", "data": { "recipeName": "pizza", "ingredientsData": "Some new property", "ingredients": ["tomatoes", "cheese", "sausage"] } }
• major version 결정
• { "apiVersion": "2.0", "data": { "recipeName": "pizza", "ingredients": "Some new property", "recipeIngredients": ["tomatos", "cheese", "sausage"] } }

---

Property Value Guidelines

Property Value Format

지원되는 형식은 다음과 같다

• boolean
• number
• string
• object
• arrays
• null

{
  "canPigsFly": null,     // null
  "areWeThereYet": false, // boolean
  "answerToLife": 42,     // number
  "name": "Bart",         // string
  "moreData": {},         // object
  "things": []            // array
}

Empty/Null Property Values

빈 값이나, null은 최대한 지양하라

Enum Values

enum 값은 string 형태로 표현이 되어야 한다.

public enum Color {
  WHITE,
  BLACK,
  RED,
  YELLOW,
  BLUE
}

{
  "color": "WHITE"
}

---

Property Value Data Types

Date Property Values

날짜 타입의 데이터 형태는 RFC 3339 를 따른다.

{
    // 2007년 11월 6일 16시 34분 41초 
  "lastUpdate": "2007-11-06T16:34:41.000Z"
}

Time Duration Property Values

duration은 ISO 8601 을 따른다.

{
  // 3년 6개월 4일 12시간 30분 5초
  "duration": "P3Y6M4DT12H30M5S"
}

위도 /경도 Property Values

위도 경도는 ISO 6709 를 따른다.

{
  // The latitude/longitude location of the statue of liberty.
  "statueOfLiberty": "+40.6894-074.0447"
}

---

오류 객체

에러코드, 메시지 전달 방식

{
  "error":{
    "code": 404
    "message": "File Not Found",
    "errors": [{"message": "File Not Found"}]
  }
}