We should determine a useful ordering of keys in schema

[sthagen]

Simply sorting keys does not help explore a schema file with more than a screen full of lines.

I suggest an ordering of JSON Schema keys that states the most useful for human readers first and profits from the fact, that references are resolved only after full parse of the object (so the machine will not complain).

Also we should use the $comment temporary JSON Schema indicator in place to help readers during initial bootstrap of the schema where stability has not been reached, so that they can focus on parts we think are more ready than others, without the editors always having to create additional documentation outside of the schema for guiding review efforts.

[davaya]

A "useful" ordering is nice, but we still need to decide whether other orderings are valid or invalid. This is from your latest YAML schema:

Whether or not some programming languages preserve insertion order does not affect how a schema evaluates the validity of a document. From RFC 8259:

An object is an unordered collection of zero or more name/value
pairs, where a name is a string and a value is a string, number,
boolean, null, object, or array.

An array is an ordered sequence of zero or more values.

This means that if metadata is an object then its properties

set: ...
source: ...
provenance: ...
use: ...

are unordered, and are equivalent to

use: ...
source: ...
set: ...
provenance: ...

or any other ordering. If an application receives a document in a "non useful" order, shall it reject it as invalid or accept it? If the TC wants to reject orderings other than what we call "useful", then an array is required to make that happen.

[sthagen]

@davaya - as I wrote:

I suggest an ordering of JSON Schema keys that states the most useful for human readers first and profits from the fact, that references are resolved only after full parse of the object (so the machine will not complain).

This proposal is concerning the presentation in the specification (schema files and prose) not how applications order the elements in instances.

[davaya]

The ordering of keys in the specification is entirely up to the editors and can be anything useful. I was conflating this with the discussion of insertion-order-preserving program variables and the conformance requirements on random-order DP Metadata files. My bad.