Split Schema and Document paths and communicate both in errors.

[MathiasPius]

It might make sense to keep track of both the path within the document i.e. #.users[2].name as well as the path within the schema that it is getting validated against, and then communicate both of these when errors are encountered.

In a complex schema for example, you might have a schema which makes use of composition to reduce code duplication within the schema, which means that very deeply nested and branching schemas might result in dumb "validation failed" errors, which don't help in narrowing down the issue.

As an example, I was just trying to write a common sense example using password validation, where a schema like this one:

---
uri: must-contain-letter
schema:
  type: string
  pattern: .*[a-zA-Z].*

---
uri: must-contain-number
schema:
  type: string
  pattern: .*[0-9].*

---
uri: must-contain-letter-and-number
schema:
  allOf:
    - $ref: must-contain-letter
    - $ref: must-contain-number

---
uri: user-list
schema:
  type: array
  items:
    type: object
    items:
      username:
        type: string
      password:
        $ref: must-contain-letter-and-number

... Would be used to validate this file:

---
- username: mulder
  password: trustno1

- username: neo
  password: hunter2

- username: karen
  password: password

The schema would fail on karen, since her password does not contain any numbers, but the error produced does nothing to communicate this:

#[2].password: special requirements for field not met: supplied value does not match regex pattern for field

A better error message might be something along the lines of

#[2].password: special requirements for field not met: supplied value does not match regex pattern for field ($user-list.array.object.password.$must-contain-letter-and-number.allOf[1].$must-contain-number.string.pattern)

Although very verbose, it gives a clear idea of exactly which requirement failed.

Might be edge cases that are hard to name, such as in inversion of "not", or "oneOf" where validating multiple branches successfully is actually an error.

[MathiasPius]

This is further complicated by the fact that during Schema-loading, the path is used for tracking errors within the schema, not the end document.

I think it might make sense to split schema and validation errors into separate types.