-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathindex.html
256 lines (226 loc) · 7.74 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
<html>
<head>
<title>JSchema</title>
<link rel="stylesheet" type="text/css" href="style.css" />
</head>
<body>
<center>
<h1>JSchema</h1>
<p><i>"Simplicity is a prerequisite for reliability."</i></p>
<p><i>See also <a href="rpc.html">jschema-rpc</a></i></p>
</center>
<h2>Introduction</h2>
<p>
The great virtue of <a href="http://json.org">JSON</a> is that it is simple. Its grammar consists of 15 productions, making it both easy to parse and produce.
</p>
<p>
A simple data interchange format demands a simple schema mechanism. The current schema standard, <a href="http://json-schema.org">JSON Schema</a>, does not satisfy this requirement.
</p>
<p>
JSchema fills this gap. The design goals of JSchema are:
</p>
<ul>
<li>Its grammar should be at most 15 productions beyond JSON</li>
<li>It should be flexible enough to specify most existing JSON content</li>
<li>It should communicate the structure of the JSON document visually</li>
<li>It should be trivial to convert an example JSON document into a schema</li>
<li>It should map cleanly to standard programming language concepts and data structures</li>
</ul>
<p>
In order to retain simplicity it is necessary to forego some features. JSchema does not support:
</p>
<ul>
<li>Fine-grained schema mixing</li>
<li>List/Array sizing</li>
<li>Subtyping/specialization</li>
<li>Various useful data types (e.g. intervals)</li>
</ul>
<h2>Schema URL and File Conventions</h2>
<p>
Assuming JSON content matching a given JSchema is available at <pre>http://example.com/path/</pre> then the JSchema should be available at <pre>http://example.com/path/?JSchema</pre>
</p>
<p>
Locally, JSchema files should end with the <code>.jsc</code> file suffix.
</p>
<h2>Grammar</h2>
<p>A JSchema document is a valid JSON document conforming to the following grammar:</p>
<pre>
<type> ::=
<core_types> |
<array_type> |
<enum_type> |
<map_type> |
<struct_type> |
<a href="#type_defs"><string></a>
<a name="core_type_g"><core_types></a> ::=
<a href="#string_type">'"string"'</a> |
<a href="#boolean_type">'"boolean"'</a> |
<a href="#date_type">'"date"'</a> |
<a href="#uri_type">'"uri"'</a> |
<a href="#integer_type">'"int"'</a> |
<a href="#number_type">'"number"'</a> |
<a href="#self_type">'"self"'</a> |
<a href="#object_type">'"object"'</a>
<a href="#array_type"><array_type></a> ::=
'[' type ']'
<a href="#enum_type"><enum_type></a> ::=
'{' '"enum"' ':' '[' <enum_values> ']' '}'
<enum_values> ::=
string
string ',' <enum_values>
<a href="#map_type"><map_type></a> ::=
'{' '"map_of"' ':' <type> '}'
<a href="#struct_type"><struct_type></a> ::=
'{' <typedefs_and_props> '}'
<typedefs_and_props> ::=
<typedefs_map> ',' <props> |
<props> |
<typedefs_map> ::=
'"typedefs@"' ':' '{' <type_defs> '}'
<a href="#type_defs"><type_defs></a> ::=
<type_def> |
<type_def> ',' <type_defs>
<type_def> ::=
<string> ':' <type_def_type>
<type_def_type> ::=
<struct_type> |
<enum_type>
<props> ::=
<prop> |
<prop> ',' <props>
<prop> ::=
<string> ':' <type>
</pre>
<h2>Types</h2>
<a name="string_type"><h3>"string"</h3></a>
<p>
A string may be a JSON string.
</p>
<a name="boolean_type"><h3>"boolean"</h3></a>
<p>
A boolean may have a value of 'true' or 'false', sans quotes.
</p>
<a name="date_type"><h3>"date"</h3></a>
<p>
A date may be a JSON string in any format specified by the W3C <a href="http://www.w3.org/TR/NOTE-datetime">NOTE-datetime</a>.
</p>
<a name="uri_type"><h3>"uri"</h3></a>
<p>
A uri may be a JSON string that is a valid URI.
</p>
<a name="integer_type"><h3>"int"</h3></a>
<p>
An int may be a JSON int.
</p>
<a name="number_type"><h3>"number"</h3></a>
<p>
A number may be a JSON number.
</p>
<a name="self_type"><h3>"self"</h3></a>
<p>
"self" refers to the schema defined by the current JSchema file.
</p>
<a name="object_type"><h3>"object"</h3></a>
<p>
An object may be an arbitrary JSON object.
</p>
<a name="array_type"><h3>Array Type</h3></a>
<p>
An array may be a JSON Array with elements that conform to the type definition enclosed within the array.
</p>
<a name="enum_type"><h3>Enum Type</h3></a>
<p>
An enum must have a JSON string value from domain specified in the array on the right hand side.
</p>
<a name="map_type"><h3>Map Type</h3></a>
<p>
A map may be a JSON object with an arbitrary number of members, where the name of the pair can be a JSON string, and the value must satisfy the right hand type definition.
</p>
<a name="struct_type"><h3>Struct Type</h3></a>
<p>
A struct type defines a JSON object by a series of name/type pairs. For each name/type pair, a conforming JSON object, if a pair with the name is present, will have a value conforming to the type. If the name is not present, it is interpreted as being null. Additionally, pairs not mentioned in the Struct Type may be present and should be preserved at runtime for re-serialization.
</p>
<a name="type_defs"><h3>Struct TypeDefs</h3></a>
<p>
A struct type may define types to refer to by name using the 'typedef@' syntax. A typedef consists of a string name and a type definition. The name of each typedef must be unique and not conflict with the core type names. Typedef names are valid within the context of the struct type they are defined in.
</p>
<p>
Typedefs may be either Struct Types or Enum Types.
</p>
<h2>Nullability</h2>
<p>
All values in a JSON document described by a JSchema schema may have a null value. The interpretation of the null value is left to implementations, with the caveat that null should be preserved for re-serialization.
</p>
<h2>Comments</h2>
<p>
JSchema implementations are required to <a href="http://tech.groups.yahoo.com/group/json/message/152">accept c-style comments</a> in JSchema files.
</p>
<h2>Examples</h2>
<table class="examples-table">
<tr>
<th>
Schema
</th>
<th>
Examples
</th>
</tr>
<tr>
<td>
{ "name" : "string", "age" : "int" }
</td>
<td>
{ "name" : "Joe", "age" : 42 }
</td>
</tr>
<tr>
<td>
{ "people" : [ { "name" : "string",
"age" : "int"} ] }
</td>
<td>
{ "people" : [
{ "name" : "Joe", "age" : 42 }
{ "name" : "Paul", "age" : 28 }
{ "name" : "Mack", "age" : 55 } ] }
</td>
</tr>
<tr>
<td>
{ "people" : [ { "name" : "string",
"age" : "int",
"eye_color" : {"enum" : ["brown",
"blue",
"green"]}} ] }
</td>
<td>
{ "people" : [
{ "name" : "Joe", "age" : 42, "eye_color" : "brown" },
{ "name" : "Paul", "age" : 28, "eye_color" : "brown" },
{ "name" : "Mack", "age" : 55, "eye_color" : "blue" } ] }
</td>
</tr>
<tr>
<td>
{ "id_to_people" : {
"map_of" : { "name" : "string",
"age" : "int",
"eye_color" : {"enum" : ["brown",
"blue",
"green"]}
}
}
}
</td>
<td>
{ "id_to_people" : {
"1" : { "name" : "Joe", "age" : 42, "eye_color" : "brown" },
"2" : { "name" : "Paul", "age" : 28, "eye_color" : "brown" },
"3" : { "name" : "Mack", "age" : 55, "eye_color" : "blue" }
}
}
</td>
</tr>
<table>
</body>
</html>