Define "applicability" and "attachment" #424
Conversation
This consolidates all of the URI Template resolution sections into
one section. The new section is at the top level, as it applies
to both LDO keywords ("href", "anchor", and all of the algorithm
modifiers) and to a schema keyword ("base").
As much of the algorithm as possible is now given in pseudocode,
although whether this is the most readable form is debatable.
It is certainly more concise, and forced detailed consideration
of some steps which had been under-specified, particularly with
respect to "hrefSchema".
The main change is that the input data for "hrefSchema" is
prepopulated only with instance data that validates against
all applicable subschemas within "hrefSchema". Expressing
this properly requires the "applicability" concept from PR json-schema-org#424.
Previously, the only mention of how to exclude a field from being
used to pre-populate input was the advice to set the "properties"
subschema to "false". However, this does not hold up once you
start using more complex schemas.
This consolidates all of the URI Template resolution sections into
one section. The new section is at the top level, as it applies
to both LDO keywords ("href", "anchor", and all of the algorithm
modifiers) and to a schema keyword ("base").
As much of the algorithm as possible is now given in pseudocode,
although whether this is the most readable form is debatable.
It is certainly more concise, and forced detailed consideration
of some steps which had been under-specified, particularly with
respect to "hrefSchema".
The main changes are that setting any applicable subschema for
a template variable to "false" in "hrefSchema" excludes that
variable from accepting input, and that the input data for
"hrefSchema" is prepopulated only with instance data that
validates against all applicable subschemas within "hrefSchema".
Expressing this properly requires the "applicability" concept
from PR json-schema-org#424.
Previously, the only mention of how to exclude a field from being
used to pre-populate input was the advice to set the "properties"
subschema to "false". However, this does not hold up once you
start using more complex schemas.
handrews
force-pushed
the
applicability
branch
2 times, most recently
from
ff4fdfa to
210ade2
Compare
handrews
force-pushed
the
applicability
branch
from
210ade2 to
7e81fe4
Compare
jsonschema-hyperschema.xml
Outdated
| When multiple subschemas are applicable to a given sub-instance, all "link" | ||
| arrays MUST be concatenated, in any order, into a single array. Each object | ||
| in the resulting array MUST retain its own list of applicable "base" values | ||
| from the same schema and any parent schemas. |
There was a problem hiding this comment.
This paragraph makes me think back about #124. So if links was an object, what does concatenation would mean?
Might be an argument in favor of keeping the array...
There was a problem hiding this comment.
If links becomes an object, then it's an object of arrays, so for each relation that appears in multiple subschemas, you would concatenate the arrays for that relation to produce the array in the resulting combined value.
There was a problem hiding this comment.
True. I realized about that after writing the comment.
jsonschema-validation.xml
Outdated
| <t> | ||
| A validation implementation MAY choose to implement determining subschema | ||
| applicability and providing access to the value(s) of applicable annotation | ||
| kewords. Implementation of this feature MAY instead be done separately. |
jsonschema-validation.xml
Outdated
| kewords. Implementation of this feature MAY instead be done separately. | ||
| </t> | ||
| <t> | ||
| Since many subschemas can be applicable to any single sub-isntance, each |
There was a problem hiding this comment.
@handrews That one is still there.
There was a problem hiding this comment.
dammit... I distinctly remember searching for this, but I must have done it in hyperschema and forgotten about validation. Fixed now. For reals. I think.
jsonschema-validation.xml
Outdated
| available as an array in which order is not significant and items need not | ||
| be unique. | ||
| </t> | ||
| <section title="Combinatoric and conditoinal schemas"> |
Thanks for this, it really makes reviewing pleasant as far as I am concerned. |
You're welcome! I do try to make it easy when I see how it can be split up (I just tend to see that criteria a bit differently sometimes, it seems). BTW, I finally figured out why I keep having so much trouble with spelling typos: the vim spell-checker ignores text within elements in XML. It will check text in attributes, but not element contents. I DO NOT UNDERSTAND WHY. But at least I finally know why they keep getting through. (although apparently I forgot to turn it on at all this time as it would have caught the "conditional" at least). |
|
I'm still looking at this. |
|
@awwright language suggestions welcome. I am also working on a test suite format for this to add to the test suite repo, so I think that will help clarify as well. |
handrews
force-pushed
the
applicability
branch
3 times, most recently
from
d5cd621 to
d9c913a
Compare
|
@dlax I think I fixed all the typos. I merged them into the existing commits because then they are less distracting for other people reading for the first time. |
|
Just to make sure I understand the applicability and attachment element... It's mainly to do with c55678a#diff-2391a2ef934e9aed11cbf87a65eb61c9R1172 In that, annotation key words are only attached to a sub-instance if the sub-schema validates successfully for the sub-instance? (please do ping me on slack when you reply to this so I pick it up right away) |
|
@Relequestual yup, that's correct |
|
@awwright @Relequestual please let me know if your concerns have been addressed, and if not, what actionable objections you have. This is a fundamental piece of defining how JSON Schema works as a multi-vocabulary media type, and in particular how validation serves as a base for applying other vocabularies. |
The format and string-encoded content keywords have validation semantics (even if only optionally), so they should go between the required validation keywords and the metadata keywords.
In preparation for the applicability text, split out "definitions" into its own section about re-use, and rename the remainder of the old metadata section to focus on annotation of schemas with keywords or new vocabularies. Rework the "definitions" section text, but leave the other sections alone until the next commit.
Generalize this and move it into validation, updating the hyper-schema spec to reference it.
...with some intro text, and re-indentation, but no changes to the contents of the re-indented sections.
With the applicability/attachment concept, we now have a way to talk about what happens when multiple annotation values are present. Add notes to each keyword as needed.
handrews
force-pushed
the
applicability
branch
from
c60b5d4 to
abc40aa
Compare
@awwright has this cleared up with more reading? Or do you have actionable feedback such as indicating the unclear language? It's been two weeks since this comment and I'm not sure how to move forward. |
|
Given that this has two approvals, I am going to go ahead and merge. @awwright I am happy to accept further issues on this to work on it more, but it's been nearly 3 weeks since your "I'm thinking" comment and neither mentioning you here nor asking offline has produced anything actionable. We have plenty of time before anything will be published so this is not irreversible. |
This consolidates all of the URI Template resolution sections into
one section. The new section is at the top level, as it applies
to both LDO keywords ("href", "anchor", and all of the algorithm
modifiers) and to a schema keyword ("base").
As much of the algorithm as possible is now given in pseudocode,
although whether this is the most readable form is debatable.
It is certainly more concise, and forced detailed consideration
of some steps which had been under-specified, particularly with
respect to "hrefSchema".
The main changes are that setting any applicable subschema for
a template variable to "false" in "hrefSchema" excludes that
variable from accepting input, and that the input data for
"hrefSchema" is prepopulated only with instance data that
validates against all applicable subschemas within "hrefSchema".
Expressing this properly requires the "applicability" concept
from PR json-schema-org#424.
Previously, the only mention of how to exclude a field from being
used to pre-populate input was the advice to set the "properties"
subschema to "false". However, this does not hold up once you
start using more complex schemas.
gregsdennis
added
clarification
This is a bit more groundwork for the rewrite, and is relevant
to issue #423.
NOTE: This has been updated from its original approach to move the concept into the validation specification!
The commits have been broken up with individual messages into useful chunks:
Rework the whole applicability/attachement concept from the
hyper-schema specification into the validations specification,
and establish it as the basis for working with annotation keywords.
Update the annotation kewyords with clarifications on how to
handle values across multiple applicable schemas.
Update the hyper-schema specification to reference the now more
generic description of validation interaction in the validation
spec itself, with additional clarifications about how to handle
combinign keywords from multiple applicable schemas.
Split the "Metadata" section into a re-use section for just the
"definitions" keyword, and a section on annotation and extensibility
which defines applicability/attachement and defines the simple
annotation vocabulary that was already present in the validation
spec.
Move all of that after "format" and "String-encoding non-JSON data"
as those sections are both more closely aligned with validation
than with either re-use or annotations.