JSON 파일 구조를 문서화하는 가장 좋은 방법은 무엇입니까?

Question

다른 사람들이 내 코드에서 이해할 수있는 JSON 파일을 만들 수 있기를 바랍니다. 필요한/허용 된 구조가 무엇인지 가장 잘 문서화하는 방법은 무엇입니까?

예 :.

{ 
    "customer1" : { 
     "open-orders" : [ 
      123, 
      456 
     ], 
     "terms" : [ 
      "net 30" 
     ] 
    }, ... 
} 

가 어떻게 첫 번째 수준에, 그 다음 '용어'가 필요하고 1 사이에있을 수 있습니다 CRM 시스템에서 발견 고객 ID입니다 "와 같은 물건을 명시 것 그리고 배열의 3 항목. 당신은 첫 번째 수준의 태그 '오류'를 호출하지 말아야하지만 다른 모든 알 수없는 태그는 무시됩니다 등 등. "

XML에서 이미이 정보 중 일부를 캡처 한 DTD를 사용할 수 있으며 몇 가지 추가 의견을 추가 할 수 있습니다.

하지만 JSON의 모범 사례는 무엇입니까? 지금은 테이블 구조에서 놀고 있는데 왼쪽의 열에는 구조에 따라 유효한 JSON 파일이 있습니다.이 파일은 청크로 잘라내어 각각 테이블의 행입니다. 오른쪽 열에서는 한 번에 하나의 청크/행을 작성합니다. 나는 너무 행복하지 않다. 더 좋은 아이디어가 있습니까?

Answer 1

JSON은 데이터 구조를 직렬화하여 표현한 것입니다. 따라서 직렬화 된 출력 대신에 데이터 구조를 문서화해야합니다.

/** 
* @var object Customer 
*/ 
var customer = { 
    /** 
    * @var Number[][] 
    */ 
    "open-orders": [], 
    /** 
    * @var String[][] 
    */ 
    "terms": [] 
}; 

또한 JSON에는 XML과 같은 데이터 사양 (마크 업) 표기가 없습니다. XML은 데이터를 직렬화하는데도 사용할 수 있지만 XSD를 사용하여 데이터 구조를 지정할 수 있습니다. JSON은이 작업을 수행하기위한 것이 아니며 그러한 작업을위한 메커니즘을 제공하지 않습니다.

Answer 2

XML 파일의 경우 dtd와 마찬가지로 json 구조에 대한 스키마를 작성할 수 있습니다. http://json-schema.org

예 :

{ 
    "title": "Example Schema", 
    "type": "object", 
    "properties": { 
     "firstName": { 
      "type": "string" 
     }, 
     "lastName": { 
      "type": "string" 
     }, 
     "age": { 
      "description": "Age in years", 
      "type": "integer", 
      "minimum": 0 
     } 
    }, 
    "required": ["firstName", "lastName"] 
}