Re: [Architecture] Review of the "primary schema" wiki page...

[Antranig Basman]

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
,
 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
" or 
"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 
.  
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
/"
 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

[Architecture] Review of the "primary schema" wiki page...

[Tony Atkins]

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
,
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
"
or "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
.
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
*"
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