Skip to content
This repository was archived by the owner on Nov 3, 2023. It is now read-only.

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

Closed
cybtachyon opened this issue May 10, 2021 · 1 comment · Fixed by #162
Closed

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

cybtachyon opened this issue May 10, 2021 · 1 comment · Fixed by #162

Comments

@cybtachyon
Copy link

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
Copy link
Member

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

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

2 participants