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 [email protected] http://lists.gpii.net/mailman/listinfo/architecture
