Thanks for these very helpful suggestions. It is great to have our use of JSON schema reviewed for
compliance with the developments in it since we originally based our work on it in 2011. I should note that
the use of propert names containing periods such as "fluid.prefs.textSize" or "#fluid.prefs.textSize" is
problematic with the current version of Infusion - if these appear in IoC references, the periods will be
interpreted as property indirections, making it impossible to reference either these properties or anything
nested within them. Our practice has been to escape these either explicitly, using the "\." syntax, or else
in an implicit way by replacing them with underscores "_". Do you have a preference between these, or any
other alternative suggestions?
Cheers,
Antranig
On 14/04/2017 10:03, Tony Atkins wrote:
As agreed in the PCP API meeting, I have been reviewing the "primary schema"
wiki page for the preferences
framework:
http://docs.fluidproject.org/infusion/development/PrimarySchemaForPreferencesFramework.html
First of all, although I recognize that this is an example, it lacks some
pretty basic context. The example
does not make use of the "/$schema/" field
<https://spacetelescope.github.io/understanding-json-schema/basics.html#declaring-a-json-schema>,
and as
such there is no indication of the fact that this is even a JSON schema, or of
what version of the standard
we are using. This should be addressed. If for example our "/$schema/" field
indicated that our schema was
written to work with draft v3, it might still reasonably expected to work with
validators that support newer
versions.
The next biggest thing I notice (as their use is not valid in the root of a
schema) is that the example
field definitions are "snippets" of schema content rather than a valid schema.
I'm not arguing that every
example has to be a complete schema, only that we mention the context in which
an examples would be used.
So, I'm assuming these snippets belong in either the "definitions
<http://json-schema.org/latest/json-schema-validation.html#rfc.section.5.26>" or
"properties
<https://spacetelescope.github.io/understanding-json-schema/reference/object.html#properties>"
block of a
schema. As mentioned in my note to Steve, even if the goal is to describe the
fields that are accepted in a
particular document type (AKA "properties"), defining the fields in a
"definitions" block gives the best
options for reuse. As I also mentioned in my note to Steve, my advice is to make use of
the "id" field, as
shown in these examples
<http://json-schema.org/latest/json-schema-core.html#rfc.section.8.2>.
Combining
all of the above, the main definitions file might look something like:
{
"$schema": "http://json-schema.org/schema#";,
"id": "http://real.site/schemas/preferences.json";,
"definitions": {
"fluid.prefs.textSize": {
"id": "#fluid.prefs.textSize",
"type": "number",
"default": 1,
"min": 1,
"max": 2,
"multipleOf": 0.1
},
// Remaining defs omitted for brevity
}
}
Although "/id/" values are not strictly required, using them gives us a simpler
way to refer to a definition
from another file. If we are dealing with a file in the same directory (hosted
or local), we can now either
refer to "/preferences.json/definitions/fluid.prefs.textSize/" (the path
relative to the root of the
document) or "/preferences.json#fluid.prefs.textSize/" (the "/id/"). Within
the preferences.json document
itself, once we have "/id/" values, we can use references like
"/#fluid.prefs.textSize/", which seems
closest to our use of namespaced grades in other contexts.
Even within the snippets, I can see that we are using an older version of the
standard. This example has
also been updated to reflect the need to use "/multipleOf
<https://spacetelescope.github.io/understanding-json-schema/reference/numeric.html#multiples>/"
instead of
the earlier "/divisibleBy/", as discussed in the meeting.
I'll stop there, as I think just looking at the examples highlights enough for
a single note. I also plan
to review the JSON schemas (or snippets) in various repos and will comment
under separate cover.
Cheers,
Tony
_______________________________________________
Architecture mailing list
Architecture@lists.gpii.net
http://lists.gpii.net/mailman/listinfo/architecture
_______________________________________________
Architecture mailing list
Architecture@lists.gpii.net
http://lists.gpii.net/mailman/listinfo/architecture
