Tutorial content ideas for helping users migrate to OAS 3.1

[darrelmiller]

• Clarify which JSON Schema properties most normal people care about vs ones for metaschema writers.
• Describe what new capabilities JSON Schema 2019-09 brings to OAS users.

[handrews]

Primarily for meta-schema writers:

• $vocabulary
• $recursiveAnchor
• $recursiveRef

Note that the $recursive* keywords could have other uses, but in practice the need for them seems to be rare outside of meta-schemas.

---

Primarily for people packaging multiple schema resources in a single schema document:

• $id in subschemas

Primarily for people creating a library of schemas in one schema resource, where users of those schemas should not need to know the internal structure of the resource.

• $anchor

Note that these descriptions rely on the distinction between a schema resource and a schema document, which is new in draft 2019-09.

[handrews]

@darrelmiller should we transfer this to the learn.openapis.org repo?