JSON 스타일 가이드라인

• 자바스크립트 언어 자료

JSON 스타일 가이드라인

JSON에서 가장 중요한 것은 상호운용성이다. 그러므로 JSON 데이터 피드를 수신자 측에서 바라는 형태로 제공하는 것이 중요하다. Google은 JSON 스타일 가이드(https://google.github.io/styleguide/jsoncstyleguide.xml)를 배포하여 모범 사례를 공유하고 유지보수성을 향상시키는 데 기여하고 있다.
Google의 JSON 스타일 가이드는 매우 광범위하지만, API 설계자 및 개발자에게 가장 중요한 것을 꼽자면 다음과 같다.

• 속성이름
• 날짜 속성값
• 열거형 값

속성 이름

속성 이름은(Google의 표현을 따르자면) 이름 값 쌍에서 콜론 왼쪽에 위치한다(속성 값은 콜론의 오른쪽). JSON의 속성 이름을 짓는 주요 스타일은 다음과 같은 두 가지 방법이 있다.

• lowerCamelCase
• snake_case

lowerCamelCase는 여러 단어를 붙여쓰되, 첫 단어를 제외한 각 단어의 첫 글자를 대문자로 한다. Java와 JavaScritp 커뮤니티 코딩 가이드에서 볼 수 있다.
snake_case는 모든 글자를 소문자로 하되 단어와 단어 사이를 언더스크오(_)로 연결한다. Ruby on Rails 커뮤니티에서 이를 많이 볼 수 있다.
Google 및 RESTful API 대부분에서는 속성 이름에 lowerCamelCase를 사용한다.

{
    "firstName": "John Smith"
}

날짜 속성 값

Google의 JSON 스타일 가이드sms RFC 3339를 준수하는 것을 선호한다.

{
    "dateRegisterd": "2018-06-08T23:46:11-05:00"
}

위 날자 표현은, UTC/GMT(coordinated Universal Time)와의 시간차가 -5시간, 즉 미국 동부표준시라는 것을 알 수 있다. RFC 3339는 ISO 8601의 요약본으로, 양자 간의 주된 차이는 ISO 8601(http://www.iso.org/iso/home/standards/iso8601.html)이 T(날짜와 시간 사이의)를 공백문자로 대체할 수 있다는 점이다. RFC 3339에서는 이것이 허용되지 않는다.

위도 및 경도 값

지리 API(예: Google Maps 등)나 지리 정보시스템(GIS)과 관련된 API는 위도 및 경도 데이터를 자주 다룬다. Google JSON 스타일 가이드에서는 일관성을 위해 위도 경도 데이터를 ISO 6709(http://en.wikipedia.org/wiki/ISO_6709) 표준을 준수하여 다루라고 권고하고 있다. Google Maps는 뉴욕 시 엠파이어스테이트 빌딩의 좌표를 북위 40.748747, 서경 73.985547도라 나타내고 있는데 이를 JSON으로 나타내면 아래와 같다.

{
    "empireStateBuilding": "40.748747-73.985547"    
}

위는 다음과 같은 원칙에 따라 +-DD.DDDD+-DDD.DDDD 포멧으로 위도 경도를 나타낸다.

• 위도를 먼저 표기한다.
• 북위가 양수이다.
• 동경이 양수이다.
• 위도 및 경도 값은 문자열로 나타낸다. 음수 기호 때문에 숫자로 취급할 수 없다.

들여쓰기

Google JSON 스타일 가이드는 들여쓰기에 대해서 특별히 언급하지 않지만, 여기에도 몇가지 원칙이 있다.

• JSON은 직렬화를 위한 포멧이지 보여주기 위한 포멧이 아니다. 그러므로 API 제공 측과 사용 측 사이에서 들여쓰기는 의가 없다.
• 대부분의 JSON 포메터는 JSON을 보기 좋게 정리할 때 2글자에서 4글자 사이로 들여쓰기를 선택할 수 있게끔 한다.
• JSON은 JavaScript(ECMA 262 표준의일부)로부터 왔다. 그러나 JavaScript커뮤니티와 조율이 된 부분은 아무것도 없다.
• 대부분의 개발자와 코딩 스타일 가이드 문서는 2글자 공백문자를 선호한다. 하지만 다른 스타일을 사용하고 싶다면 그렇게 해도 무방하다.
  다만, 일관성을 지키는 것이 중요하다.

API 설계 실무에 바로 적용하는 JSON. 토마스 지음, 심효섭 옮김, 2018년 ⓒ인사이트