Skip to content
This repository was archived by the owner on Nov 2, 2023. It is now read-only.

Convert other html pages to Markdown #85

Merged
merged 5 commits into from
May 8, 2017
Merged

Convert other html pages to Markdown #85

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
a93ab98
Convert other html pages to Markdown
adamvoss Mar 19, 2017
2dd4664
Use .md extension for links within repository
adamvoss Mar 24, 2017
e05c9a0
Merge remote-tracking branch 'origin/master' into markdownify
adamvoss Mar 26, 2017
4bbc001
Merge upstream changes into markdownify
adamvoss May 7, 2017
fdbad86
Merge remote-tracking branch 'origin/master' into markdownify
adamvoss May 7, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions _config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,3 +29,6 @@ collections:
docs:
output: true
permalink: "/:title:output_ext"

gems:
- jekyll-relative-links
70 changes: 0 additions & 70 deletions documentation.html
View file
Open in desktop

This file was deleted.

41 changes: 41 additions & 0 deletions documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
---
layout: page
---

Specification
-------------

The latest Internet-Drafts at the IETF are the draft-wright-json-schema\*-01 documents, which correspond to the draft-06 meta-schemas. These were published on 2017-04-15. (Due to a change in authorship the I-D numbering was reset with the previous draft). The specification is split into three parts, Core, Validation, and Hyper-Schema:

|--------------------------------------------------------------|-------------------------------------------------|
| [JSON Schema Core](latest/json-schema-core.html) | defines the basic foundation of JSON Schema |
| [JSON Schema Validation](latest/json-schema-validation.html) | defines the validation keywords of JSON Schema |
| [JSON Hyper-Schema](latest/json-schema-hypermedia.html) | defines the hyper-media keywords of JSON Schema |

They are also available on the IETF main site: [core (draft-wright-json-schema-01)](http://tools.ietf.org/html/draft-wright-json-schema-01), [validation (draft-wright-json-schema-validation-01)](http://tools.ietf.org/html/draft-wright-json-schema-validation-01) and [hyper-schema (draft-wright-json-schema-hyperschema-01)](http://tools.ietf.org/html/draft-wright-json-schema-hyperschema-01).

For previous versions of the specification, please see the [Specification Links](https://github.com/json-schema-org/json-schema-spec/wiki/Specification-Links) page on our github wiki.

Meta-schemas
------------

The meta-schemas are the schemas which define the JSON Schema and Hyper-Schema formats.

The latest meta-schema is draft-06.

|--------------------------------------------------------------|------------------------------------------------------------|
| [Core/Validation Meta-Schema](http://json-schema.org/schema) | Used for schemas written for pure validation. |
| [Hyper Meta-Schema](http://json-schema.org/hyper-schema) | Used for schemas written for validation and hyper-linking. |

Standard schemas
----------------

These sample schemas describe simple data structures which can be expressed as JSON:

|-----------------------------------------------------|---------------------------------------------------------------------------------|
| [Geographic Coordinate](http://json-schema.org/geo) | a location as longitude and latitude |
| [Card](http://json-schema.org/card) | a microformat-style representation of a person, company, organization, or place |
| [Calendar](http://json-schema.org/calendar) | a microformat-style representation of an event |
| [Address](http://json-schema.org/address) | a microformat-style representation of a street address |


143 changes: 69 additions & 74 deletions example1.html → example1.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,69 +2,65 @@
layout: page
---

<h2>Example data</h2>
<div class="block">
<p>Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an <em>id</em>, a <em>name</em>, a <em>price</em>, and an optional set of <em>tags</em>.</p>
Example data
------------

<h3>Example JSON data for a product API</h3>
<p>An example product in this API is:</p>
Let's pretend we're interacting with a JSON based product catalog. This catalog has a product which has an *id*, a *name*, a *price*, and an optional set of *tags*.

<pre><code class="language-json">
### Example JSON data for a product API

An example product in this API is:

```json
{
"id": 1,
"name": "A green door",
"price": 12.50,
"tags": ["home", "green"]
}
</code></pre>
```

<p>While generally straightforward, that example leaves some open questions. For example, one may ask:</p>
While generally straightforward, that example leaves some open questions. For example, one may ask:

<ul>
<li>What is id?</li>
<li>Is name required?</li>
<li>Can price be 0?</li>
<li>Are all tags strings?</li>
</ul>
- What is id?
- Is name required?
- Can price be 0?
- Are all tags strings?

<p>When you're talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data.</p>
</div>
When you're talking about a data format, you want to have metadata about what fields mean, and what valid inputs for those fields are. JSON schema is a specification for standardizing how to answer those questions for JSON data.

<h2>Starting the schema</h2>
<div class="block">
<p>To start a schema definition, let's begin with a basic JSON schema:</p>
Starting the schema
-------------------

<pre><code class="language-json">
To start a schema definition, let's begin with a basic JSON schema:

```json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
"description": "A product from Acme's catalog",
"type": "object"
}
</code></pre>
```

The above schema has four properties called *keywords*. The *title* and *description* keywords are descriptive only, in that they do not add constraints to the data being validated. The intent of the schema is stated with these two keywords (that is, this schema describes a product).

<p>The above schema has four properties called <em>keywords</em>.
The *type* keyword defines the first constraint on our JSON data: it has to be a JSON Object.

The <em>title</em> and <em>description</em> keywords are descriptive only, in that they do not add
constraints to the data being validated. The intent of the schema is stated with these two keywords
(that is, this schema describes a product).</p>
Finally, the *$schema* keyword states that this schema is written according to the draft v4 specification.

<p>The <em>type</em> keyword defines the first constraint on our JSON data: it has to be a JSON
Object.</p>
Defining the properties
-----------------------

<p>Finally, the <em>$schema</em> keyword states that this schema is written according to the draft
v4 specification.</p>
</div>
Next let's answer our previous questions about this API, starting with id.

<h2>Defining the properties</h2>
<div class="block">
<p>Next let's answer our previous questions about this API, starting with id.</p>
### What is id?

<h3>What is id?</h3>
<p><em>id</em> is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required.</p>
*id* is a numeric value that uniquely identifies a product. Since this is the canonical identifier for a product, it doesn't make sense to have a product without one, so it is required.

<p>In JSON Schema terms, we can update our schema to:</p>
<pre><code class="language-json">
In JSON Schema terms, we can update our schema to:

```json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
Expand All @@ -78,13 +74,13 @@ <h3>What is id?</h3>
},
"required": ["id"]
}
</code></pre>
```

### Is name required?

<h3>Is name required?</h3>
<p><em>name</em> is a string value that describes a product. Since there isn't
much to a product without a name, it also is required. Adding this gives us the schema:</p>
*name* is a string value that describes a product. Since there isn't much to a product without a name, it also is required. Adding this gives us the schema:

<pre><code class="language-json">
```json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
Expand All @@ -102,12 +98,13 @@ <h3>Is name required?</h3>
},
"required": ["id", "name"]
}
</code></pre>
```

### Can price be 0?

<h3>Can price be 0?</h3>
<p>According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify <em>exclusiveMinimum</em>. Therefore we can update our schema with <em>price</em>:</p>
According to Acme's docs, there are no free products. In JSON schema a number can have a minimum. By default this minimum is inclusive, so we need to specify *exclusiveMinimum*. Therefore we can update our schema with *price*:

<pre><code class="language-json">
```json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
Expand All @@ -130,25 +127,20 @@ <h3>Can price be 0?</h3>
},
"required": ["id", "name", "price"]
}
</code></pre>
```

<h3>Are all tags strings?</h3>
<p>Finally, we come to the <em>tags</em> property. Unlike the previous
properties, tags have many values, and is represented as a JSON array. According
to Acme's docs, all tags must be strings, but you aren't required to specify
tags. We simply leave <em>tags</em> out of the list of required properties.</p>
### Are all tags strings?

<p>However, Acme's docs add two constraints:</p>
Finally, we come to the *tags* property. Unlike the previous properties, tags have many values, and is represented as a JSON array. According to Acme's docs, all tags must be strings, but you aren't required to specify tags. We simply leave *tags* out of the list of required properties.

<ul>
<li>there must be at least one tag,</li>
<li>all tags must be unique.</li>
</ul>
However, Acme's docs add two constraints:

<p>The first constraint can be added with <em>minItems</em>, and the second one by
specifying <em>uniqueItems</em> as being true:</p>
- there must be at least one tag,
- all tags must be unique.

<pre><code class="language-json">
The first constraint can be added with *minItems*, and the second one by specifying *uniqueItems* as being true:

```json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product",
Expand Down Expand Up @@ -179,17 +171,20 @@ <h3>Are all tags strings?</h3>
},
"required": ["id", "name", "price"]
}
</code></pre>
</div>
```

Summary
-------

The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the [full standard draft](#definitions).

<h2>Summary</h2>
<div class="block">
<p>The above example is by no means definitive of all the types of data JSON schema can define. For more definitive information see the <a href="#definitions">full standard draft</a>.</p>
<p>As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a <em>dimensions</em> property for the size of the product, and the second is a <em>warehouseLocation</em> field for where the warehouse that stores them is geographically located.</p>
<p>And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the <a href="http://json-schema.org/geo">canonical one</a>.</p>
As a final example, here's a spec for an array of products, with the products having 2 new properties. The first is a *dimensions* property for the size of the product, and the second is a *warehouseLocation* field for where the warehouse that stores them is geographically located.

<h3>Set of products:</h3>
<pre><code class="language-json">
And also, since JSON Schema defines a reference schema for a geographic location, instead of coming up with our own, we'll reference the [canonical one](http://json-schema.org/geo).

### Set of products:

```json
[
{
"id": 2,
Expand Down Expand Up @@ -221,10 +216,11 @@ <h3>Set of products:</h3>
}
}
]
</code></pre>
```

### Set of products schema:

<h3>Set of products schema:</h3>
<pre><code class="language-json">
```json
{
"$schema": "http://json-schema.org/draft-04/schema#",
"title": "Product set",
Expand Down Expand Up @@ -270,6 +266,5 @@ <h3>Set of products schema:</h3>
"required": ["id", "name", "price"]
}
}
</code></pre>
</div>
```

Loading