Update to reflect the proper usage of $ref with #/$def/ JSON pointers

[cybtachyon]

As noted in json-schema-org/json-schema-spec#1097 - the docs should be updated to reflect the proper usage of $ref with #/$def/ JSON pointers (#/definitions/ in older spec drafts).

Right now, according to the Understanding JSON Schema site, only "complex schemas" use definitions for reuse, when in the real world I would suggest based on my own experience that most schemas are likely intended for re-use elsewhere in the system eventually.

we don't want to forbid $ref to properties, just like Python doesn't forbid calling leading single-leading-underscore names from outside of a class. It's not advised to do that, but sometimes you have to do ill-advised things. The spec shouldn't lock that down (but a linter should probably complain unless configured not to).

The documentation site should have a line something along the lines of:

While you can also $ref properties with a JSON pointer by doing "$ref": "otherSchema.json#/properties/link", you should avoid doing so and instead move the schema definition to the $defs reserved location to avoid issues with schema validation and references.

Before:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "category": "atom",
  "title": "Link",
  "entity": "link",
  "type": "object",
  "format": "grid",
  "properties": {
    "href": {
      "title": "URL",
      "type": "string",
      "format": "url",
      "options": {
        "grid_columns": 4
      }
    },
    "title": {
      "title": "Title attribute",
      "description": "Shown on mouseover.",
      "type": "string",
      "options": {
        "grid_columns": 4
      }
    }
  }
}

After:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "category": "atom",
  "title": "Link",
  "entity": "link",
  "type": "object",
  "format": "grid",
  "$defs": {
    "href": {
      "title": "URL",
      "type": "string",
      "format": "url",
      "options": {
        "grid_columns": 4
      }
    },
    "title": {
      "title": "Title attribute",
      "description": "Shown on mouseover.",
      "type": "string",
      "options": {
        "grid_columns": 4
      }
    }
  },
  "properties": {
    "href": { "$ref": "#/$defs/href" },
    "title": { "$ref": "#/$defs/title" }
  }
}

A second example just for completions sake:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Image embed",
  "description": "A method for displaying images",
  "category": "component",
  "type": "object",
  "format": "grid",
  "$defs": {
    "link": {
      "entity": "link",
      "type": "object",
      "format": "grid",
      "options": {
        "grid_columns": 6
      },
      "properties": {
        "href": {
          "$ref": "link.json#/href",
          "options": {
            "grid_columns": 3
          }
        },
        "title": {
          "$ref": "link.json#/title",
          "options": {
            "grid_columns": 3
          }
        }
      },
      "required": ["href"]
    }
  },
  "properties": {
    "link": { "$ref": "#/$defs/link"  }
  }
}

[jdesrosiers]

Thanks. I'll keep this in mind when I work on that section relatively soon.