sourcemeta/alterschema

Support transforming Draft3 schemas

jviotti opened this issue · 6 comments

jviotti commented

To support upgrading arbitrary draft 3 schemas, we need to define rules to upgrade draft 3 to draft 4.

jviotti commented

I have almost zero experience with draft3, so I'll be pasting my findings here so anybody can correct me if I'm getting any of it wrong.

jviotti commented

One key piece of Alterschema is teaching the tool how to "walk" over all the subschemas of a given schema by definition all possible applicator keywords. From skimming https://datatracker.ietf.org/doc/html/draft-zyp-json-schema-03, all the keywords that take subschemas in some way are:

  • properties
  • patternProperties
  • additionalProperties
  • items
  • additionalItems
  • dependencies
  • extends

See #86 for my initial definition take.

jviotti commented

As per the rules, these are my findings so far (I'll be updating this comment with new findings):

  • type supports any, which was removed in Draft4. We should take care of it both on the string and array form of type (#89)
  • Draft3 has disallow, which was removed in Draft4
  • Draft3 has divisibleBy, which I presume must be reworked as multipleOf (#90)
  • Draft3 has extends, which was removed in Draft4
  • The format keyword has some differences. Also, it seems that format was optional in draft3
    • date, time, utc-millisec, regex, color, style and phone were removed in draft4
    • ip-address was renamed to ipv4
    • host-name was renamed to hostname
  • The required keyword use to be a boolean at the property level
jeremyfiel commented

I'm going to mix in a bit of draft 2 and 3 references to build a timeline of some of the keywords.

I'm no expert, so please correct me if i'm wrong.

  • optional keyword accepts boolean in draft 2, replaced by required in draft 3, required updated to accept array of properties in draft 04
  • maxDecimal in draft 2 replaced by divisibleBy in draft 3 and replaced again by multipleOf in draft-04
  • maximumCanEqual in draft 2 accepts boolean, replaced by exclusiveMaximum in draft 3, boolean
  • minimumCanEqual in draft 2 accepts boolean, replaced by exclusiveMinimum in draft 3, boolean
  • uniqueItems added in draft 2 accepts boolean
  • additionalItems added to type: array in draft 3, accepts boolean or schema
  • alternate removed in draft 3
  • patternProperties added in draft 3, expects regex
  • id added in draft 3, expects uri
  • $ref added in draft 3, expects uri
  • $schema added in draft 3, expects uri
  • requires replaced with dependencies in draft 3
 **Dependencies**
  Two types available: 
  Simple Dependency  If the dependency value is a string, then the
  instance object MUST have a property with the same name as the
  dependency value.  If the dependency value is an array of strings,
  then the instance object MUST have a property with the same name
  as each string in the dependency value's array.

  Schema Dependency  If the dependency value is a schema, then the
  instance object MUST be valid against the schema
  • ❤️1
jeremyfiel commented

@jviotti You mentioned other work on adjacent projects would support this work, has there been any movement on those projects?

jviotti commented

@jeremyfiel Yes, there is! I'm implementing some dialect-agnostic JSON Schema foundations here: https://www.jsontoolkit.org. The idea is for that project to eventually replace the engine we have here, so we can:

  • Better traverse schemas in a dialect agnostic way, even schemas embedding schemas of different dialects
  • Perform schema bundling
  • Allow for more expressive rules that can handle some edge cases from Draft 3 that are not representable right now
  • etc

Feel free to watch that repo. Definitely not forgetting about this issue. I promise it will be fixed once those things are in place.