JSON Schema
Restructuring Output Formats #63
Replies: 12 comments 86 replies
-
|
I started writing up some comments on some of these issues and it occurred to me that with a bunch of different threads going on at once, nothing is going to get done. So, I propose that we start with the things that don't seem controversial, make sure we have consensus, get it written up, and then move on to the next most important thing. I'll add a thread with the first set of proposals and a consensus measuring mechanism. (Feel free to tell me you don't like this approach. I won't be offended) |
Beta Was this translation helpful? Give feedback.
-
|
The branch I've started takes into consideration everything, just so we can see what it all looks like together. Some of these things don't really do well in the spec by themselves, but we'll see where this takes us. |
Beta Was this translation helpful? Give feedback.
-
|
For this first proposal, we're bundling several changes at once because they appear to be relatively uncontroversial. If changes to this proposal are necessary based on discussion, this comment will be edited with a change log included.
Change Log 10/12: Change proposed new name for Use the following legend to show your support for this proposal. Remember this isn't a vote, it's a general consensus measuring device.
|
Beta Was this translation helpful? Give feedback.
-
|
I think |
Beta Was this translation helpful? Give feedback.
-
I also added language that an implementation that supports the latest version of the spec is only required to support output from that version. It might be really hard to support multiple output formats. |
Beta Was this translation helpful? Give feedback.
-
|
All of these are straightforward except renaming "errors". I feel like we may need to try out a few alternatives and mull on them a bit. Naming is hard! :) |
Beta Was this translation helpful? Give feedback.
-
|
So some history (I put it in the opening comment of #973 but it's worth repeating here): The Given the current schema-based structure, I'd go with |
Beta Was this translation helpful? Give feedback.
-
|
Maybe we defer deciding on the new name for |
Beta Was this translation helpful? Give feedback.
-
I would change
Regarding which of these should be required, perhaps we can just specify that at least one or the other should be included, and both MUST be included if a We also shouldn't imply that only
This has been the case since draft2019-09, although some of the examples there mistakenly added a |
Beta Was this translation helpful? Give feedback.
-
|
I don't know. I'm open to alternatives. It seemed we landed on |
Beta Was this translation helpful? Give feedback.
-
|
@jdesrosiers regarding My implementation subs in a default base URI for when the schema doesn't provide one. It's mostly to facilitate this property in the output. However, when the root subschema is either As such, I have to check this property for null in my JSON converter so that the property isn't serialized. Are you okay with Essentially the output for a {
"valid": false,
"evaluationPath": "",
"instanceLocation": "",
"errors": {
"": "All values are invalid against the false schema"
}
}If the |
Beta Was this translation helpful? Give feedback.
-
|
We could just use something like |
Beta Was this translation helpful? Give feedback.
-
Why not? Isn't that the point of the default base URI? The identifier for the boolean schema would just be the default base URI. |
Beta Was this translation helpful? Give feedback.
-
|
I see what you're saying. In the context of a single validation, I can apply the default base URI to In my implementation, I have a static (global) Yeah, I think this may just be particular to my implementation. |
Beta Was this translation helpful? Give feedback.
-
I've always disliked this being a hard requirement, because some schemas are very small and used inlined in code, and therefore have no "location" to speak of. e.g. one might want to use a small json schema to validate the structure of nested data passed in as a function argument, so the base URI of The spec is clear enough -- the initial base URI is defined according to its context, and implementations should document anything they assume. |
Beta Was this translation helpful? Give feedback.
-
No, it make sense to use a consistent default, because that is encouraged by the relevant specifications and no one has given me a clear reason why it ever needs to be an error instead. Why make things not-work when it is trivial to make them work? |
Beta Was this translation helpful? Give feedback.
-
|
I suppose one place where this would have an immediate impact is the test suite and inclusion of output tests. An output test would need example output to use as a comparison. That example would need to have something in {
"valid": false,
"evaluationPath": "",
"schemaLocation": "https://json-everything/base#",
"instanceLocation": "",
"nested": [
{
"valid": false,
"evaluationPath": "/properties/foo",
"schemaLocation": "https://json-everything/base#/properties/foo",
"instanceLocation": "/foo",
"nested": [
{
"valid": true,
"evaluationPath": "/properties/foo/not",
"schemaLocation": "https://json-everything/base#/properties/foo/not",
"instanceLocation": "/foo"
}
]
}
]
}I use The two options I see are:
I don't particularly like either, but I dislike option 1 less. |
Beta Was this translation helpful? Give feedback.
-
The other option is the spec defining a required value you must use when using a default base URI which would be an
Sorry, I didn't read carefully enough before and didn't realize this was still an open question before piling on as if it was agreed upon. When users add a schema to my internal schema store, I expect there to be a URI that they will use to retrieve or reference the schema later. If they don't provide a URI somehow, it should be a error. Assuming a base URI of something like It also occurs to me that values in the output format could be used by an application trying to extract information. The original value of keywords is not included in the output format, so if an application needs this information, it would need to retrieve that value using the "schemaLocation", but |
Beta Was this translation helpful? Give feedback.
-
A URI-reference of In other words,
While A schema resource without an identifier is not an error, it simply cannot be referenced except via a fragment-only reference of I have still not heard a reason why we can't do this [EDIT: "this" meaning require a default base URI that we specified, such as |
Beta Was this translation helpful? Give feedback.
-
That doesn't make sense. The URI resolution process should always produce a non-relative URI (or fragment-only). Even if it does result in a relative-reference, we still don't have something we can use as an identifier so we end up with an error case either way. However, I looked this up and the spec says that there is no resolution authoritative resolution mechanism for tags. Either way, we don't have a non-relative URI to use as an identifier. I looked into
I think we may be talking about slightly different things and it's my fault because I was using the wrong term. What we're really talking about is a default retrieval URI, which I agree is different than a default base URI. If we're just talking about a default base URI, it would only apply if there were no However, wasn't the point of a default base URI to ensure that all schemas have an identifier? Wouldn't this result in the root schema not having an identifier? Is there another problem we're trying to solve here that I missed? I don't see what problem having a default base URI solves. At this point, the only options I see that solve the problem as I understand it are to define a default retrieval URI at the spec level which needs to be compatible with |
Beta Was this translation helpful? Give feedback.
-
Thinking about this, supporting multiple output formats sounds like a real pain as an implementor. I'd like to consider this alternative:
|
Beta Was this translation helpful? Give feedback.
-
|
If that is the case, then I think it all belongs in Core. It sounds like there will be no further debate on that topic, but I feel that the discussion of the differing use cases is relevant to possible format restructuring. Should that be a new thread on this discussion? |
Beta Was this translation helpful? Give feedback.
-
|
I think we should revisit splitting output into its own spec once we're done with changes. At that point, we can ask the question of whether it's big enough that it bloats core and warrants its own spec. As it stands, I think it's a toss-up. |
Beta Was this translation helpful? Give feedback.
-
|
I don't think the primary argument for splitting it has anything to do with size (although that is a legitimate factor). The point is to decouple the output format from any specific version of JSON Schema. Assume I have a 2020-12 schema that references a 2019-09 schema and a draft-07 schema. 2019-09 and 2020-12 have slight differences in output format and draft-07 has no defined output format. Which format should my implementation use? Should it use the one for the root schema for everything? Should it switch between output formats when it switches schemas? What is expected for draft-07? Splitting into a separate spec removes all of these ambiguities and allows implementations to simply say, I support is version (or versions) of the output format and it's clear what should be implemented and what behavior is expected no matter what version JSON Schema the schema written in even if it's an older version that didn't define an output format. I'm very strongly in favor of this approach. |
Beta Was this translation helpful? Give feedback.
-
|
Splitting the output into its own spec also supports versioning the output. While it doesn't necessarily need to be versioned independently of the core spec, allowing it to do so is nice. Secondly, it permits implementations to update to the next core spec without requiring them to also update their output. With json-schema-org/json-schema-spec#1249 (based on this thread), we're making a substantial change to the structure of the output. While we don't expect this to be a continual practice, such a change would be easier to handle if the output update was separate from updating schema behaviors. |
Beta Was this translation helpful? Give feedback.
-
I think allowing the output format to be versioned independently is more than just nice, it's essential. The point is to decouple the output format from any specific version of JSON Schema. Using the same version names for the output format would signal a relationship to a JSON Schema version that doesn't exist. Even if we don't intend for there to be a relationship, it would confuse the community. |
Beta Was this translation helpful? Give feedback.
-
|
as described in #Proposal {
"valid": false,
"keyword": "minLength",
"keywordLocaation": "#/description",
"xxx": {
"received": 1,
"limit": 3
},
"schemaLocation": "https://example.com/mySchema#/description",
"instanceLocation": "",
"annotation": "description"
}Here |
Beta Was this translation helpful? Give feedback.
-
|
I think what we might do is encourage implementors to support localization and customization of error messages. Then we can add the things like keyword and whatever your I'm not sure whether augmenting the schema with the messages is the right approach, but I'm happy to be convinced. Mainly, we don't have a precedent for keywords that exist solely to be used by the implementation. It's annotative but not something that would be returned to the app. I suggest we start this requirement as a SHOULD and upgrade it to a MUST in later iterations. |
Beta Was this translation helpful? Give feedback.
-
|
If we were to do this, it would make sense to create a separate section at the top level of the schema for the messages, like |
Beta Was this translation helpful? Give feedback.
-
I wonder how this would work when I'm on the fence about including them in the schema itself. I'd need a really good reason to add that. I'm a fan of using If the spec declares error messages, it should only do so as defaults. They should be overridable by the user. Lastly, for localization, I think it's probably sufficient that
|
Beta Was this translation helpful? Give feedback.
-
I'm a little doubt about putting messages at the top level of the schema. For a complexed schema (nested, has many keywords, etc.), this could weaken the relation between messages and validation keywords, which lead to some difficulty in reading and maintenance the schema. |
Beta Was this translation helpful? Give feedback.
-
|
Maybe I've been thinking about this wrong from the start. What if we only have an output unit per schema/subschema instead of per keyword? The output unit would need to be adjusted to house errors & annotations from keywords. The detailed output would go from {
"valid": false,
"validationPath": "",
"schemaLocation": "https://example.com/polygon#",
"instanceLocation": "",
"nested": [
{
"valid": false,
"keyword": "$ref",
"dialect": "https://json-schema.org/draft/2020-12/vocab/core",
"validationPath": "/items/$ref",
"schemaLocation": "https://example.com/polygon#/$defs/point",
"instanceLocation": "/1",
"nested": [
{
"valid": false,
"keyword": "required",
"dialect": "https://json-schema.org/draft/2020-12/vocab/validation",
"validationPath": "/items/$ref/required",
"schemaLocation": "https://example.com/polygon#/$defs/point/required",
"instanceLocation": "/1",
"error": "Required property 'y' not found."
},
{
"valid": false,
"keyword": "additionalProperties",
"dialect": "https://json-schema.org/draft/2020-12/vocab/applicator",
"validationPath": "/items/$ref/additionalProperties",
"schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties",
"instanceLocation": "/1/z",
"error": "Additional property 'z' found but was invalid."
}
]
},
{
"valid": false,
"keyword": "minItems",
"dialect": "https://json-schema.org/draft/2020-12/vocab/validation",
"validationPath": "/minItems",
"schemaLocation": "/minItems",
"instanceLocation": "",
"error": "Expected at least 3 items but found 2"
}
]
}to just {
"valid": false,
"evaluationPath": "",
"schemaLocation": "https://example.com/polygon#",
"instanceLocation": "",
"errors": {
"minItems": "Expected at least 3 items but found 2"
},
"nested": [
{
"valid": false,
"evaluationPath": "/items/$ref",
"schemaLocation": "https://example.com/polygon#/$defs/point",
"instanceLocation": "/1",
"errors": {
"required": "Required property 'y' not found.",
"additionalProperties": "Additional property 'z' found but was invalid."
}
}
]
}This seems a LOT simpler, and all the information you need is still there.
For completeness, here's something of what a valid result would like with annotations: {
"valid": true,
"evaluationPath": "",
"schemaLocation": "https://example.com/polygon#",
"instanceLocation": "",
"annotations": {
"items": true
},
"nested": [
{
"valid": true,
"evaluationPath": "/items/$ref",
"schemaLocation": "https://example.com/polygon#/$defs/point",
"instanceLocation": "/1",
"annotations": {
"properties": [ "x", "y" ]
}
}
]
} |
Beta Was this translation helpful? Give feedback.
-
|
[NOTE: I'm going to put a brief comment here, but sometime in the next few days I will start a separate discussion about annotations and their uses that will go into a lot more context. For now, I just want to put this down as a marker for annotation-oriented requirements. I don't expect it to necessarily be convincing on its own.] This has good readability for errors, but for me with annotations, nested structures are not ideal. You have to make a choice regarding what structure you are following — instance, schema (lexical scope), or evaluation (dynamic scope) — and that choice will be right for some applications but wrong for others. This evaluation path-based structure is good for "how did I attach annotations", but much more complex to work with for "what annotations are attached to this instance location" or "what instance locations were annotated by this keyword." You can get all of that information, of course, but you have to walk a tree structure and process it into a different structure, and tree-walking is not the most straightforward way to process data. Per section 7.7.1 of the spec:
The easiest thing for me is a flat list of these 5-tuples (whether the 5-tuples are literal lists/tuples or objects, either is fine). I can sort the list by any of the fields to mimic any of the structures. I can filter the list by keyword. Given an instance or schema location, and can convert it to a JSON Pointer or URI and find it in the list. Of course, a flat list of 5-tuples with the annotation value replaced by errors is not good for human readability, which is important for errors. |
Beta Was this translation helpful? Give feedback.
-
|
(Ugh... this was supposed to be part of the previous thread...) For the above example, because the nesting is only one deep, the Schema {
"type": "object",
"title": "root",
"properties": {
"foo": {
"type": "object",
"title": "foo-title",
"properties": {
"foo-prop": {
"const": 1,
"title": "foo-prop-title"
}
}
},
"bar": {
"type": "object",
"title": "bar-title",
"properties": {
"foo-prop": {
"const": 2,
"title": "bar-prop-title"
}
}
}
}
}Instance {
"foo": {"foo-prop": 1},
"bar": {"bar-prop": 2}
}Detailed output {
"valid": true,
"evaluationPath": "",
"instanceLocation": "",
"annotations": {
"title": "root",
"properties": ["foo", "bar"]
},
"nested": [
{
"valid": true,
"evaluationPath": "/properties/foo",
"instanceLocation": "/foo",
"annotations": {
"title": "foo-title",
"properties": ["foo-prop"]
},
"nested": [
{
"valid": true,
"evaluationPath": "/properties/foo/properties/foo-prop",
"instanceLocation": "/foo/foo-prop",
"annotations": {
"title": "foo-prop-title"
}
}
]
},
{
"valid": true,
"evaluationPath": "/bar",
"instanceLocation": "/bar/bar-prop",
"annotations": {
"title": "bar-title",
"properties": ["bar-prop"]
},
"nested": [
{
"valid": true,
"evaluationPath": "/properties/bar/properties/bar-prop",
"instanceLocation": "/bar/bar-prop",
"annotations": {
"title": "bar-prop-title"
}
}
]
}
]
}Basic output (same, but flattened, wrapped into the {
"valid": true,
"nested": [
{
"valid": true,
"evaluationPath": "",
"instanceLocation": "",
"annotations": {
"title": "root",
"properties": ["foo", "bar"]
}
},
{
"valid": true,
"evaluationPath": "/properties/foo",
"instanceLocation": "/foo",
"annotations": {
"title": "foo-title",
"properties": ["foo-prop"]
}
},
{
"valid": true,
"evaluationPath": "/properties/foo/properties/foo-prop",
"instanceLocation": "/foo/foo-prop",
"annotations": {
"title": "foo-prop-title"
}
},
{
"valid": true,
"evaluationPath": "/bar",
"instanceLocation": "/bar/bar-prop",
"annotations": {
"title": "bar-title",
"properties": ["bar-prop"]
}
},
{
"valid": true,
"evaluationPath": "/properties/bar/properties/bar-prop",
"instanceLocation": "/bar/bar-prop",
"annotations": {
"title": "bar-prop-title"
}
}
]
}You can see that with the basic output, you can still do all of your sorting as needed. The only difference between this and the current output is that we don't have output units for keywords; the info is consolidated at the subschema level. I think this makes more sense. It also aligns with the idea that, upon validation failure, annotations are only discarded at the subschema boundary rather than by individual keywords, which is another discussion we've had recently (also prompted by @handrews). |
Beta Was this translation helpful? Give feedback.
-
|
It seems I missed the various |
Beta Was this translation helpful? Give feedback.
-
|
In writing this up and including passing examples with annotations, I'm discovering that it's probably going to be pretty rare that nodes could be collapsed to a condensed hierarchical format. I'm thinking of dropping the detailed format and just having the flat list (basic) and verbose (hierarchical). I also think this will reduce cognitive load on implementors to try and get the reduction logic right. |
Beta Was this translation helpful? Give feedback.
-
|
@gregsdennis that sounds like a good idea. I admit it took me a bit to really "get" the distinction between detailed and verbose. The different descriptions made sense, but I had to kind of work through it. It also occurs to me that while it makes sense to offer both for either type of outcome, verbose will probably be used more for errors, and basic more for annotations. Primarily because with annotations you are more likely to want them organized by the instance structure than the schema structure, but the schema structure makes more sense for errors. |
Beta Was this translation helpful? Give feedback.
-
I also have an instance structure proposed in the OP. Let's discuss that in a new thread, though. I'm putting up a PR that does the things in this thread shortly. |
Beta Was this translation helpful? Give feedback.
-
|
@TeCHiScy, I was re-reading json-schema-org/json-schema-spec#1241 and found
Do you feel the format described in this thread adequately provides this? (Specifically, the |
Beta Was this translation helpful? Give feedback.
-
|
Here's a minor point that may or may not need anything done about it. Technically, the instance location for a As I understand it, currently we just use Has this been a concern for anyone? If not, it might be a good idea to include a note acknowledging that for some keywords, the instance location is not identical to how the pointer resolves. Unless folks want to try to do something to express that with the relative pointer, but that adds some complications as it's only |
Beta Was this translation helpful? Give feedback.
-
|
This kind of thing hasn't been an issue for me. I think it's pretty well understood with just the pointer. It's good that you brought it up, though. I wonder if anyone knows of a user perspective on this. |
Beta Was this translation helpful? Give feedback.
-
|
Yeah, I can't say it's been a problem for me either, I just noticed the inconsistency. We can just leave it here to see if anyone else says anything, or I could split it out to a new discussion. I don't have strong feelings either way on this. |
Beta Was this translation helpful? Give feedback.
-
|
Preference (or maybe practical) question: In output, is it useful to have explicit errors from subschemas where the only failure is from a subschema? For example {
"type": "object",
"properties": {
"foo": { "type": "array", "items": { "type": "integer" } }
}
}
{ "foo": [ 1, 2, false, 4 ] }This will fail on I can see the boolean schema false needing to produce an error, but I'm having a hard time conceiving of another case where a schema could produce an error. |
Beta Was this translation helpful? Give feedback.
-
|
From json-schema-org/json-schema-spec#1249:
Basically, if you use the basic output format, it's most convenient if every This doesn't work if Whether schema resource roots have an empty fragment or no fragment is less important, but it's trivial to include an empty fragment in that case and then all of your Mandating JSON Pointer fragments is (as far as I can tell) an easy way to lock down a possible source of variance in our standard output. @gregsdennis let me know if you'd like me to make this its own discussion. I figured it should at least be mentioned here anyway. |
Beta Was this translation helpful? Give feedback.
-
|
I think most everything major that I currently want to address here is done. There are a few smaller things:
I think this leaves this discussion in a good place. I'm going to lock it and open issues for the things I've noted. Thanks, everyone, for all of the input! |
Beta Was this translation helpful? Give feedback.
-
The below is a summary of json-schema-org/json-schema-spec#973.
The topic has been moved here so that we can utilize threads to help more targeted discussions.
The working branch is draft-next-output.
Hey everyone. I've been reading through all of the comments in this and linked issues, compiling a list of topics.
It seems that we have consensus on these things:
errorstonested/subschemas/inner/details(other suggestions?)$falsein the location)validis required for each node.erroris not required but is declared as the designated place to put error messaging. Tooling that consumes this output should expect an error message here.These things still require decisions (but I've proposed some things):
absoluteKeywordLocationinstead ofkeywordLocationkeywordLocationcould bevalidationPathand optional (default off) to the end user; opens the door forabsoluteKeywordLocationto change toschemaLocation(for terseness); implementations SHOULD support an option mechanism which determines the inclusion ofvalidationPath.keywordto support renaming ☝️ (and maybedialect- import from #1065). Only makes sense when a keyword is present. For instance at the root or#/allOf/3there is no keyword, so these would be absent.validationPathandinstanceLocationcan be plain JSON Pointers and do not need to be URI-encodedbasicanddetailedformats? My users have said no. (verboseshould show everything.)detailedandverboseto*-by-schemaand add*-by-instance(or some other way to indicate both structure and quantity of info) to support instance-based structures (see below for examples)basicis a collection of terminal nodesdetailed-by-schemanot)detailed-by-instanceI'll discuss later.flagto be specified as "MUST" (is currently "SHOULD"); supporting at least one other format to be specified as "SHOULD".And this isn't directly about output, but supports it:
absoluteSchemaLocation/schemaLocation. This may be in the spec already, but I figured it's worth mentioning.Annotations
Annotations need to be part of the node, not rendered as child validation nodes. I don't think there's any argument here.
I've been thinking around this for a couple hours now, and it seems we have three orthogonal attributes that we need to consider.
1. Does the keyword provide validation?
Not all keywords provide validation. For example, the spec says nothing about validation for
titleanddescription.My implementation handles this by always passing validation for these keyword, which works to provide the correct pass/fail outcome, but it also means that they produce an output node. So I get something like this as a node:
{ "valid": true, "keywordLocaation": "#/description", "schemaLocation": "https://example.com/mySchema#/description", "instanceLocation": "", "annotation": "description" }Question: should pure-annotation keywords produce an output node or simply be listed in parent nodes?
I can see arguments for both sides, and I think I have a pretty easy tweak to my implementation that would hide these, so I'm not invested either way.
2./3. Does the keyword produce and/or collect annotations?
These are actually two different ideas, but I think I often conflate them, so I'm going to consider them distinct here.
A keyword can produce annotations, and it can propagate annotations from its children. Most keywords do one or the other, but some do both.
titleanddescriptiononly produce annotations.allOfwhich only propagate child annotations.propertiesboth produce (which of the listed properties are present) and propagate annotations.Regardless of how an implementation manages annotations internally, I believe it's worthwhile keeping these distinctions separate when reporting them to the user. It can be useful to know whether a keyword produced an annotation or is just passing a message.
I'd like to propose two more output node properties to cover each of these ideas:
annotationproperty. This is just the raw value of the annotation (e.g. a string fortitleor an array of strings forproperties).collectedAnnotationsproperty. This is an object where the key is the schema location (i.e. the value that would be inschemaLocation) of the keyword that produced it, and the value is the annotation itself.The downside to listing collected annotations is duplication of annotation values. But on the upside, you can:
Examples for existing output formats
These examples take the spec scenario and show what the output would look like if we changed all of this, including my suggestions on the open discussion topics.
For reference, here's the spec scenario:
Flag (no change) 🎉
{ "valid": true }Basic
Click to expand!
{ "valid": false, "validationPath": "", "schemaLocation": "https://example.com/polygon#", "instanceLocation": "", "nested": [ { "valid": false, "keyword": "required", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/required", "schemaLocation": "https://example.com/polygon#/$defs/point/required", "instanceLocation": "/1", "error": "Required property 'y' not found." }, { "valid": false, "keyword": "additionalProperties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/additionalProperties", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties", "instanceLocation": "/1/z", "error": "Additional property 'z' found but was invalid." }, { "valid": false, "keyword": "minItems", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/minItems", "schemaLocation": "/minItems", "instanceLocation": "", "error": "Expected at least 3 items but found 2" } ] }(I never really liked having a top-level node here, but I don't know how else to collect the nodes. I do like consistently having an object at the root, as opposed to an array.)
Detailed (schema-based)
Click to expand!
{ "valid": false, "validationPath": "", "schemaLocation": "https://example.com/polygon#", "instanceLocation": "", "nested": [ { "valid": false, "keyword": "$ref", "dialect": "https://json-schema.org/draft/2020-12/vocab/core", "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/$defs/point", "instanceLocation": "/1", "nested": [ { "valid": false, "keyword": "required", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/required", "schemaLocation": "https://example.com/polygon#/$defs/point/required", "instanceLocation": "/1", "error": "Required property 'y' not found." }, { "valid": false, "keyword": "additionalProperties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/additionalProperties", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties", "instanceLocation": "/1/z", "error": "Additional property 'z' found but was invalid." } ] }, { "valid": false, "keyword": "minItems", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/minItems", "schemaLocation": "/minItems", "instanceLocation": "", "error": "Expected at least 3 items but found 2" } ] }Verbose (schema-structured)
Click to expand! (this one's pretty big)
{ "result": { "valid": false, "validationPath": "", "schemaLocation": "https://example.com/polygon#", "instanceLocation": "", "nested": [ { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/type", "schemaLocation": "https://example.com/polygon#/type", "instanceLocation": "" }, { "valid": false, "keyword": "minItems", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/minItems", "schemaLocation": "https://example.com/polygon#/minItems", "instanceLocation": "", "error": "Value has fewer than 3 items" }, { "valid": false, "keyword": "items", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicators", "validationPath": "/items", "schemaLocation": "https://example.com/polygon#/items", "instanceLocation": "", "nested": [ { "valid": true, "keyword": "items", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items", "schemaLocation": "https://example.com/polygon#/items", "instanceLocation": "/0", "nested": [ { "valid": true, "keyword": "$ref", "dialect": "https://json-schema.org/draft/2020-12/vocab/core", "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/items/$ref", "instanceLocation": "/0", "nested": [ { "valid": true, "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/$defs/point", "instanceLocation": "/0", "nested": [ { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/type", "schemaLocation": "https://example.com/polygon#/$defs/point/type", "instanceLocation": "/0" }, { "valid": true, "keyword": "properties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/properties", "schemaLocation": "https://example.com/polygon#/$defs/point/properties", "instanceLocation": "/0", "annotation": [ "x", "y" ], "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties/x/description": "x coordinate", "https://example.com/polygon#/$defs/point/properties/y/description": "y coordinate" }, "nested": [ { "valid": true, "validationPath": "/items/$ref/properties/x", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x", "instanceLocation": "/0/x", "nested": [ { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/properties/x/type", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/type", "instanceLocation": "/0/x" }, { "valid": true, "keyword": "description", "dialect": "https://json-schema.org/draft/2020-12/vocab/meta-data", "validationPath": "/items/$ref/properties/x/description", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/description", "instanceLocation": "/0/x", "annotation": "x coordinate" } ] }, { "valid": true, "validationPath": "/items/$ref/properties/y", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/y", "instanceLocation": "/0/y", "nested": [ { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/properties/y/type", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/y/type", "instanceLocation": "/0/y" }, { "valid": true, "keyword": "description", "dialect": "https://json-schema.org/draft/2020-12/vocab/meta-data", "validationPath": "/items/$ref/properties/y/description", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/y/description", "instanceLocation": "/0/y", "annotation": "y coordinate" } ] } ] }, { "valid": true, "keyword": "additionalProperties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/additionalProperties", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties", "instanceLocation": "/0", "annotation": [], "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties": [ "x", "y" ] } }, { "valid": true, "keyword": "required", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/required", "schemaLocation": "https://example.com/polygon#/$defs/point/required", "instanceLocation": "/0", "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties": [ "x", "y" ], "https://example.com/polygon#/$defs/point/additionalProperties": [] } } ] } ] } ] }, { "valid": false, "keyword": "items", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items", "instanceLocation": "/1", "nested": [ { "valid": false, "keyword": "$ref", "dialect": "https://json-schema.org/draft/2020-12/vocab/core", "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/items/$ref", "instanceLocation": "/1", "nested": [ { "valid": false, "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/$defs/point", "instanceLocation": "/1", "nested": [ { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/type", "schemaLocation": "https://example.com/polygon#/$defs/point/type", "instanceLocation": "/1" }, { "valid": true, "keyword": "properties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/properties", "schemaLocation": "https://example.com/polygon#/$defs/point/properties", "instanceLocation": "/1", "annotation": [ "x" ], "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties/x/description": "x coordinate" }, "nested": [ { "valid": true, "validationPath": "/items/$ref/properties/x", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x", "instanceLocation": "/1/x", "nested": [ { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/properties/x/type", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/type", "instanceLocation": "/1/x" }, { "valid": true, "keyword": "description", "dialect": "https://json-schema.org/draft/2020-12/vocab/meta-data", "validationPath": "/items/$ref/properties/x/description", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/description", "instanceLocation": "/1/x", "annotation": "x coordinate" } ] } ] }, { "valid": false, "keyword": "additionalProperties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/additionalProperties", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties", "instanceLocation": "/1", "nested": [ { "valid": false, "validationPath": "/items/$ref/additionalProperties/$false", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties/$false", "instanceLocation": "/1/z", "error": "All values fail against the false schema" } ] }, { "valid": false, "keyword": "required", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/required", "schemaLocation": "https://example.com/polygon#/$defs/point/required", "instanceLocation": "/1", "error": "Required properties [y] were not present" } ] } ] } ] } ] } ] } }Note the inclusion of the annotations from the subschemas which passed validation and how they're no longer included once we move up through a subschema that failed validation.
Instance-based structure examples
I think I've been able to marry our two approaches. Considerations:
I do need to add a
resultsproperty to contain the validation results that pertain to each location, andnestedas an object instead of an array made more sense here.Verbose (instance-based)
Click to expand!
{ "valid": false, "validationPath": "", "schemaLocation": "https://example.com/polygon#", "instanceLocation": "", "results": [ { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "#/type", "schemaLocation": "https://example.com/polygon#/type" }, { "valid": false, "keyword": "minItems", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "#/minItems", "error": "Value has fewer than 3 items" }, { "valid": false, "keyword": "items", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicators", "validationPath": "#/items" } ], "nested": { "/0": { "valid": true, "results": [ { "valid": true, "keyword": "items", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items", "schemaLocation": "https://example.com/polygon#/items", }, { "valid": true, "keyword": "$ref", "dialect": "https://json-schema.org/draft/2020-12/vocab/core", "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/items/$ref", }, { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/type", "schemaLocation": "https://example.com/polygon#/$defs/point/type", }, { "valid": true, "keyword": "properties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/properties", "schemaLocation": "https://example.com/polygon#/$defs/point/properties", "annotation": [ "x", "y" ], "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties/x/description": "x coordinate", "https://example.com/polygon#/$defs/point/properties/y/description": "y coordinate" } }, { "valid": true, "keyword": "additionalProperties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/additionalProperties", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties", "annotation": [], "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties": [ "x", "y" ] } }, { "valid": true, "keyword": "required", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/required", "schemaLocation": "https://example.com/polygon#/$defs/point/required", "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties": [ "x", "y" ], "https://example.com/polygon#/$defs/point/additionalProperties": [] } } ], "nested": { "/0/x": { "valid": true, "results": [ { "valid": true, "validationPath": "/items/$ref/properties/x", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x", }, { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/properties/x/type", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/type", }, { "valid": true, "keyword": "description", "dialect": "https://json-schema.org/draft/2020-12/vocab/meta-data", "validationPath": "/items/$ref/properties/x/description", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/description", "annotation": "x coordinate" } ] }, "/0/y": { "valid": true, "results": [ { "valid": true, "validationPath": "/items/$ref/properties/y", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/y", }, { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/properties/y/type", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/y/type", }, { "valid": true, "keyword": "description", "dialect": "https://json-schema.org/draft/2020-12/vocab/meta-data", "validationPath": "/items/$ref/properties/y/description", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/y/description", "annotation": "y coordinate" } ] } } }, "/1": { "valid": false, "results": [ { "valid": false, "keyword": "items", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items", }, { "valid": false, "keyword": "$ref", "dialect": "https://json-schema.org/draft/2020-12/vocab/core", "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/items/$ref", }, { "valid": false, "validationPath": "/items/$ref", "schemaLocation": "https://example.com/polygon#/$defs/point", }, { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/type", "schemaLocation": "https://example.com/polygon#/$defs/point/type", }, { "valid": true, "keyword": "properties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/properties", "schemaLocation": "https://example.com/polygon#/$defs/point/properties", "annotation": [ "x" ], "collectedAnnotations": { "https://example.com/polygon#/$defs/point/properties/x/description": "x coordinate" } }, { "valid": false, "keyword": "additionalProperties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/additionalProperties", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties" }, { "valid": false, "keyword": "required", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/required", "schemaLocation": "https://example.com/polygon#/$defs/point/required", "error": "Required properties [y] were not present" } ], "nested": { "/1/x": { "valid": true, "results": [ { "valid": true, "validationPath": "/items/$ref/properties/x", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x", }, { "valid": true, "keyword": "type", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/properties/x/type", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/type", }, { "valid": true, "keyword": "description", "dialect": "https://json-schema.org/draft/2020-12/vocab/meta-data", "validationPath": "/items/$ref/properties/x/description", "schemaLocation": "https://example.com/polygon#/$defs/point/properties/x/description", "annotation": "x coordinate" } ] }, "/1/z": { "valid": false, "results": [ { "valid": false, "validationPath": "/items/$ref/additionalProperties/$false", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties/$false", "error": "All values fail against the false schema" } ] } } } } }Detailed (instance-based)
Initially I was only considering the verbose format for instance-based, but in building that example, I realized how to pare down the fluff.
The rules I'm following for this are:
validationPathis contained within another unit'svalidationPath, it (the first one) can be removed.This second rule removes pass-through nodes like the kind you'd get having just resolved a
$refand arriving at a new subschema. These nodes are just a summary of what's underneath and don't add much to the result.Click to expand!
{ "valid": false, "validationPath": "", "schemaLocation": "https://example.com/polygon#", "instanceLocation": "", "results": [ { "valid": false, "keyword": "minItems", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "#/minItems", "error": "Value has fewer than 3 items" } ], "nested": { "/1": { "valid": false, "results": [ { "valid": false, "keyword": "required", "dialect": "https://json-schema.org/draft/2020-12/vocab/validation", "validationPath": "/items/$ref/required", "schemaLocation": "https://example.com/polygon#/$defs/point/required", "error": "Required properties [y] were not present" } ], "nested": { "/1/z": { "valid": false, "results": [ { "valid": false, "keyword": "additionalProperties", "dialect": "https://json-schema.org/draft/2020-12/vocab/applicator", "validationPath": "/items/$ref/additionalProperties", "schemaLocation": "https://example.com/polygon#/$defs/point/additionalProperties/$false", "error": "All values fail against the false schema" } ] } } } } }Beta Was this translation helpful? Give feedback.
All reactions