title: Best practice for documenting a JSON file structure?
body: <p>I want others to be able to create JSON files that my code can understand. How would I best document what the required / allowed structure is?</p>
  
  <p>Example:</p>
  
  <pre><code>{
      "customer1" : {
          "open-orders" : [
              123,
              456
          ],
          "terms" : [
              "net 30"
          ]
      }, ...
  }
  </code></pre>
  
  <p>How would I state stuff like "on the first level, it's the customer ID as found in the CRM system. Then 'terms' is required to be there and may have between 1 and 3 items in the array. You must not ever call a first-level tag 'error' but all other unknown tags are ignored etc. etc."</p>
  
  <p>In XML I could use a DTD that already captures some of this information, and I could add some additional comments.</p>
  
  <p>But what's best practice for JSON? Right now I'm playing with a table structure where in the left column I have a valid JSON file according to my structure, which is chopped into chunks, each of which is a row in the table. In the right columns, I then write prose, one chunk/row at a time. I'm not too happy with it. Are there better ideas?</p>