index.html

---
layout: page
title: JSON Schema
permalink: /
---

<p><b>JSON Schema</b> is a vocabulary that allows you to <b>annotate</b> and <b>validate</b> JSON documents.</p>

<h2>Advantages</h2>
<div class="block" style="float:left;width:50%;">
	<h3>JSON Schema</h3>
	<ul>
		<li>describes your existing data format</li>
		<li>clear, human- and machine-readable documentation</li>
		<li>complete structural validation, useful for
			<ul>
				<li>automated testing</li>
				<li>validating client-submitted data</li>
			</ul>
		</li>
	</ul>
</div>
<div class="block" style="float:right;width:50%;">
	<h3>JSON Hyper-Schema</h3>
	<ul>
		<li>describes your existing API - no new structures required</li>
		<li>links (including <a href="http://tools.ietf.org/html/rfc6570">URI Templates</a> for target URIs)</li>
		<li>forms - specify a JSON Schema for the desired data</li>
	</ul>
</div>
<div style="clear:both"></div>


<h2>Quickstart</h2>

<p>The JSON document being validated or described we call the <i>instance</i>, and the document containing the description is called the <i>schema</i>.</p>

<p>The most basic schema is a blank JSON object, which constrains nothing, allows anything, and describes nothing:</p>

<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{}</span><span class="w">
</span></code></pre>
</div>

<p>You can apply constraints on an instance by adding validation keywords to the schema. For instance, the "type" keyword can be used to restrict an instance to an object, array, string, number, boolean, or null:</p>

<div class="highlighter-rouge"><pre class="highlight"><code><span class="p">{</span><span class="w"> </span><span class="nt">"type"</span><span class="p">:</span><span class="w"> </span><span class="s2">"string"</span><span class="w"> </span><span class="p">}</span><span class="w">
</span></code></pre>
</div>

<p>JSON Schema is hypermedia ready, and ideal for annotating your existing JSON-based HTTP API. JSON Schema documents are identified by URIs, which can be used in HTTP Link headers, and inside JSON Schema documents to allow recursive definitions.</p>

<h2>More</h2>
<div class="block">
	<p>Interested? Check out:
	<ul>
		<li>the <a href="documentation.html">specification</a></li>
		<li>some <a href="examples.html">examples</a></li>
		<li>this <a href="http://spacetelescope.github.io/understanding-json-schema/">excellent guide</a> for schema authors, from the <a href="http://www.stsci.edu/">Space Telescope Science Institute</a>
		<li>the growing list of <a href="implementations.html">JSON (Hyper-)Schema software</a></li>
	</ul>
	<p>Questions?  Feeling helpful?  Get involved on:
	<ul>
		<li>the <a href="http://github.com/json-schema-org/json-schema-spec">GitHub repo</a></li>
		<li>the <a href="https://groups.google.com/forum/#!forum/json-schema">Google Group</a></li>
		<li>the <a href="irc://chat.freenode.net/json-schema">IRC channel</a> (<a href="https://webchat.freenode.net/?channels=json-schema">Freenode Webchat</a>)</li>

	</ul>
</div>