Skip to content

Commit 3cbfc8b

Browse files
awwrightawwright
committed
Rework definition of instance/schema/data model
1 parent 23ba42e commit 3cbfc8b

File tree

1 file changed

+51
-59
lines changed

1 file changed

+51
-59
lines changed

‎jsonschema-core.xml

+51-59
Original file line numberDiff line numberDiff line change
@@ -102,36 +102,73 @@
102102

103103
<section title="Core terminology">
104104

105-
<section title="Property, item">
105+
<section title="JSON document">
106106
<t>
107-
When referring to a JSON Object, as defined by <xref target="RFC7159"/>, the
108-
terms "member" and "property" may be used interchangeably.
107+
A JSON document is an information resource (series of octets) describable by the application/json media type.
109108
</t>
110-
111109
<t>
112-
When referring to a JSON Array, as defined by <xref target="RFC7159"/>, the terms
113-
"element" and "item" may be used interchangeably.
110+
In JSON Schema, the terms "JSON document", "JSON text", and "JSON value" are interchangable because of the data model it defines.
114111
</t>
115112
</section>
116113

117-
<section title="JSON Schema, keywords">
114+
<section title="instance">
118115
<t>
119-
A JSON Schema is a JSON document, and that document MUST be an object. Object
120-
members (or properties) defined by JSON Schema (this specification, or related
121-
specifications) are called keywords, or schema keywords.
116+
JSON Schema interperts JSON data according to a data model. A JSON value interperted according to this data model is called an "instance".
122117
</t>
118+
<t>
119+
An instance has one of six primitive types, and a range of possible values depending on the type:
123120

121+
<list style="hanging">
122+
<t hangText="null">A JSON "null" production</t>
123+
<t hangText="boolean">A "true" or "false" value, from the JSON "true" or "false" productions</t>
124+
<t hangText="object">An unordered set of properties mapping a string to an instance, from the JSON "object" production</t>
125+
<t hangText="array">An ordered list of instances, from the JSON "array" production</t>
126+
<t hangText="number">An arbitrary-precision, base-10 decimal number value, from the JSON "number" production</t>
127+
<t hangText="string">A string of Unicode code points, from the JSON "string" production</t>
128+
</list>
129+
</t>
130+
<t>
131+
Whitespace and formatting conserns are thus outside the scope of JSON Schema.
132+
</t>
124133
<t>
125-
If an instance is described by a schema, and a keyword is defined in the schema, then within this document that instance is informally said to be "described by" the keyword as well.
134+
Since an object cannot have two properties with the same key, behavior for a JSON document that tries to define two properties (the "member" production) with the same key (the "string" production) in a single object is undefined.
126135
</t>
136+
</section>
127137

138+
<section title="instance equality">
128139
<t>
129-
A JSON Schema MAY contain properties which are not schema keywords.
130-
Unknown keywords SHOULD be ignored.
140+
Two JSON instances are said to be equal if and only if they are of the same type and have the same value according to the data model. Specifically, this is if:
141+
142+
<list>
143+
<t>both are null; or</t>
144+
<t>both are true; or</t>
145+
<t>both are false; or</t>
146+
<t>both are strings, and are the same codepoint-for-codepoint; or</t>
147+
<t>both are numbers, and have the same mathematical value; or</t>
148+
<t>both are arrays, and have an equal value item-for-item; or</t>
149+
<t>both are objects, and each property in one has exactly one property with an equal key the other, and that other property has an equal value.</t>
150+
</list>
151+
</t>
152+
<t>
153+
Implied in this definition is that arrays must be the same length, objects must have the same number of members, there is no way to define multiple properties with the same key, and mere formatting differences (indentation, placement of commas, trailing zeros) are insignificant.
131154
</t>
132155
</section>
133156

134-
<section title="Empty schema">
157+
<section title="JSON Schema document">
158+
<t>
159+
A JSON Schema document, or simply a schema, is a JSON document used to describe an instance.
160+
A schema is itself interperted as an instance.A JSON schema MUST be an object.
161+
</t>
162+
<t>
163+
Properties that are used to describe the instance are called keywords, or schema keywords. The meaning of properties is specified by the vocabulary that the schema is using.
164+
</t>
165+
<t>
166+
A JSON Schema MAY contain properties which are not schema keywords.
167+
Unknown keywords SHOULD be ignored.
168+
</t>
169+
<t>
170+
A schema that itself describes a schema is called a meta-schema. Meta-schemas are used to specify validate JSON Schemas and specify which vocabulary it is using.
171+
</t>
135172
<t>
136173
An empty schema is a JSON Schema with no properties, or only unknown properties.
137174
</t>
@@ -162,51 +199,6 @@
162199
</t>
163200
</section>
164201

165-
<section title="JSON Schema primitive types">
166-
<t>
167-
JSON Schema validates and interperts data according to a data model.
168-
</t>
169-
<t>
170-
JSON Schema defines six primitive types for JSON values:
171-
<list style="hanging">
172-
<t hangText="object">A JSON "object" production</t>
173-
<t hangText="array">A JSON "array" production</t>
174-
<t hangText="boolean">A JSON "true" or "false" production</t>
175-
<t hangText="number">A JSON "number" production</t>
176-
<t hangText="null">A JSON "null" production</t>
177-
<t hangText="string">A JSON "string" production</t>
178-
</list>
179-
</t>
180-
<t>
181-
Whitespace and formatting conserns are thus outside the scope of JSON Schema.
182-
</t>
183-
</section>
184-
185-
<section title="JSON value equality">
186-
<t>
187-
Two JSON values are said to be equal if and only if:
188-
189-
<list>
190-
<t>both are null; or</t>
191-
<t>both are true; or</t>
192-
<t>both are false; or</t>
193-
<t>both are strings, and are the same codepoint-for-codepoint; or</t>
194-
<t>both are numbers, and have the same mathematical value; or</t>
195-
<t>both are arrays, and have an equal value item-for-item; or</t>
196-
<t>both are objects, and each property in one has exactly one property with an equal key the other, and that other property has an equal value. No way is provided for a key to be used multiple times.</t>
197-
</list>
198-
</t>
199-
</section>
200-
201-
<section title="Instance">
202-
<t>
203-
An instance is any JSON value being described by a schema.
204-
</t>
205-
<t>
206-
An instance may also be referred to as a "JSON instance", "JSON data", "JSON-text", or "JSON document".
207-
</t>
208-
</section>
209-
210202
</section>
211203

212204
<section title="Overview">

0 commit comments

Comments
 (0)