atlassian-labs/json-schema-viewer

A JSON Schema Viewer for any JSON Schema on earth.

json-schema-viewer

Welcome to JSON Schema Viewer!

Try it out today at: https://json-schema.app

JSON Schema is awesome. It lets you define and validate the schema for your JSON object and is used to define many many JSON structures. For example schemas, please see: https://www.schemastore.org/json/

However, as great as the format is, without familiarity, it is often very difficult to read JSON Schema and understand exactly what JSON is allowed by the schema. Well, fear not! JSON Schema Viewer to the rescue: just paste a link to your JSON Schema and it will be rendered beautifully, comprehensively and with examples describing the JSON you should expect at evely level of the hierarchy.

Usage

To run this project locally:

1. Run yarn to install the dependencies.
2. (Optional, automatically runs on install) Run yarn gen-schema to generate source from schema.
3. Run yarn start to start Webpack Dev server

Now open: http://localhost:8080 to see the site and develop it live.

Deployment

To publish new SPA website resources to this AWS stack (this is the most common operation you will perform):

nix-shell -p awscli2
yarn build-and-upload

To deploy this project in a way that updates the AWS Configuration via Cloud Formation:

nix-shell -p awscli2
yarn build-and-deploy

Documentation

This project is a React SPA that is designed to be deployed to AWS CloudFront. It implements a Schema Explorer for JSON Schema and does not build an abstraction layer between JSON Schema and the UI layer. We currently support JSON Schema Draft 07 in the code.

Tests

There are currently no tests for this project. Instead, we use and browse the react storybooks to ensure that the schema is being rendered correctly.

Contributions

Contributions to json-schema-viewer are welcome! Please see CONTRIBUTING.md for details.

License

Copyright (c) 2021 Atlassian and others. Apache 2.0 licensed, see LICENSE file.

json-schema-viewer's Issues

Show "recently used" schemas in the header

The most recent 5-10 schemas should be saved somehow per user (maybe local storage) and then, when the user visits again, we can show them the schemas again in the header. This could be really useful.

(Should we show the example schemas in recently viewed? Probably)

Support for Draft 2020-12

JSON Schema has released Draft-08. This issue is a holding issue for support for Draft-08. This may end up being a lot of work and may need to be split into multiple issues.

Feature request : Publish dev friendly json-schema-viewer packages

Hello,

After reading #35, I am wondering if it wouldn't be a good opportunity to publish components that could used somewhere else such VS Code extension / CRA apps / Docusaurus / ...

Here is a basic proposal based on what I have a mind :

Split into several packages :

1. @atlassian/json-schema-viewer : Given a schema and a root component, it displays the schema in a human friendly way
2. @atlassian/json-schema-editor : Given a schema and a root component, it gives a playground for users
3. @atlassian/json-schema-faker-json / @atlassian/json-schema-faker-yaml (components for @atlassian/json-schema-viewer) : Generate fake data compliant to the current selected path. If some users only care for json or yaml, well, they have the choice
4. @atlassian/json-schema-toolbar : Given a schema, list all root definitions. When clicking to one item, we are redirected to the proper pages (thus a peer-dependancy with @atlassian/json-schema-viewer)

What do you think ?

Kind regards

External references as links

We should be able to load them by pointing at the url they refer to and converting their fragment.

Support external references ($ref)

Currently, JSON Schema Viewer does not support references to other JSON Schemas on the internet. We should update JSON Schema Viewer so that these references are supported and work as you would expect.

Not having this support breaks some JSON Schemas. For example: https://json.schemastore.org/swagger-2.0

Support "writeOnly" and "readOnly" fields.

The interesting there here is that it might justify the inclusion of a "settings" screen so that you can configure which setting you are using. And it should be clear in the UI that it is not a global setting, but instead it is per-schema and will be in a url param.

OSCAL schema is not loaded

The following schema is not loaded properly
https://raw.githubusercontent.com/usnistgov/OSCAL/main/json/schema/oscal_complete_schema.json

Support composite schemas with other fields

For example, a schema like: https://json.schemastore.org/package

It has an anyOf on the same level as the rest of the objects in the schema.

Show the underlying schema where applicable.

This was requested here: https://json-schema.slack.com/archives/C5CF75URH/p1611722218112300?thread_ts=1611718179.112200&cid=C5CF75URH

The reason given was:

I am seeing places where it doesn't show all the relevant validations, and falling back to viewing the plain schema might be helpful

However, hopefully, we can close the gap where the right validations are not shown and prevent the necessity for this.

Support YAML in the Monaco Editor

In this issue we would have to do two things:

1. Give the ability to set a property that changes the Schema Examples to be in YAML or JSON. (This would be encoded in the URL so that it would persist despite navigation attempts)
2. The ability to specify a default in the JSON Schema file so that we show the right example types by default.
3. Integrate a tool like https://github.com/pengx17/monaco-yaml so that we could get YAML validation in the Monaco editor.

We should try and perform the integration first to see if this is even possible.

Relative `$ref` not resolving

As per https://json-schema.org/understanding-json-schema/structuring.html#ref we have relative references that are not resolving.

Better display for enum based discriminations.

For example, the parameters object in OpenAPI uses properties with a single enum to decide which of them to select in an anyOf or oneOf. We should make the name choice in this situation smarter. For example:

The oneOf should be:

oneOf [in: path, in: query, in: header, in: cookie]

Which would read much more nicely.

Support rendering the meta schemas

There is:

• https://json-schema.org/draft-07/schema
• https://json-schema.org/draft-04/schema

Demo App not available

Seems that the demo app https://json-schema.app/ is offline. Is this temporary or is it not maintained anymore?

Starred Schemas

Similar to the "recently viewed" feature, we should have a feature that lets people "Star" or "Save" JSON Schemas that they want to be able to view later. This would mean that they could come back to the app and be able to load schemas that they like.

If you want this feature, please vote on it.

Until enough people vote on it, I'm going to wait before implementing it. No point building out a feature that "Recently viewed" already covers, or could cover adequately.

Add a contribute.json file

Implement and support a https://www.contributejson.org/schema file in this project.

VS Code Previewer for JSON Schema

There are several VS Code plugins that enable OpenAPI previews (like this one, which allows preview in ReDoc format) but there aren't any that allow preview for JSON Schema. This project is great at JSON schema preview, exactly what folks would need, except:

• It doesn't appear to be consumable as a library (npm install it, use it inside a plugin)
• The top navigation bar would need to be removed since folks wouldn't be uploading from inside VS Code

Has there been any thought around how this could be enhanced to allow easier integration with VS Code as a JSON schema previewer? (Or, better, has it already been done?)

Root definitions do not display details if not "type" == "object"

If a subschema has been defined that does not have an explicit or implicit type "object", the viewer shows only the description for that subschema when it is clicked in the "Root definitions" tree. It would be nice if the viewer was able to display subschemas of type "enum", "string", etc.

E.g. for this schema:

 {
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "id",
  "title": "Orso",
  "type": "object",
  "properties": {},
  "definitions": {
    "Polarization": {
      "title": "Polarization",
      "description": "The first symbol indicates the magnetisation direction of the incident beam (or o for unknown polarization).\n\nThe second symbol indicates the direction of the scattered beam (or o for unknown polarization).",
      "enum": [
        "unpolarized",
        "po",
        "mo",
        "op",
        "om",
        "mm",
        "mp",
        "pm",
        "pp"
      ]
    }
  }
}

The view when clicking on "Polarization" is this:

But I'd like it to be this:

Issue with Yarn startup for project

Hello!

I am having some trouble running yarn and getting set up for this project. My goal is to be able to at least run this locally and I keep getting the following errors:

find VS - missing any windows sdk

I was curious on the dependency for the windows sdk, is this a critical dependency for the react-spa? or is this something that I can potentially remove?

Any information would be appreciated, Thanks!

Support for merging property schema with single allOf subschema

Sometimes you need to define a type of field once, and add a default property that may be different whenever this type is used.
One way to achieve this is to follow the Factoring Schemas example in the Understanding JSON Schema book, except you use one allOf subschema instead of multiple ones.

For instance:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "One type, multiple uses",
  "description": "Demonstration of a use case where a type is defined once, and included multiple times",
  "type": "object",
  "properties": {
    "titleFiltering": {
      "default": "off",
      "allOf": [
        {
          "$ref": "#/definitions/FilterOptions"
        }
      ]
    },
    "subtitleFiltering": {
      "default": "off",
      "allOf": [
        {
          "$ref": "#/definitions/FilterOptions"
        }
      ]
    },
    "idFiltering": {
      "default": "if present",
      "allOf": [
        {
          "$ref": "#/definitions/FilterOptions"
        }
      ]
    }
  },
  "additionalProperties": false,
  "definitions": {
    "FilterOptions": {
      "title": "FilterOptions",
      "description": "Options for when filtering is done.",
      "enum": [
        "off",
        "if present",
        "required"
      ],
      "type": "string"
    }
  }
}

JSON Schema Viewer does not support this, and ignores the contents of the allOf property when documenting the properties. However, it is clearly being read, because the examples are all set to off, and the type is correctly identified as string:

I tried to test different ways of achieving this:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Testing singular allOf support",
  "description": "\"ref inside allOf\" and \"inline inside allOf\" should ideally give the same visual result as \"inline directly\", since they express the same thing. Note that \"ref directly\" is not a valid substitute, since the default value is missing.",
  "type": "object",
  "properties": {
    "inline directly": {
      "title": "FilterOptions",
      "description": "Options for how filtering is done.",
      "enum": [
        "off",
        "if present",
        "required"
      ],
      "type": "string",
      "default": "off"
    },
    "inline inside allOf": {
      "default": "off",
      "allOf": [
        {
          "title": "FilterOptions",
          "description": "Options for how filtering is done.",
          "enum": [
            "off",
            "if present",
            "required"
          ],
          "type": "string"
        }
      ]
    },
    "ref directly": {
      "default": "off",
      "$ref": "#/definitions/FilterOptions"
    },
    "ref inside allOf": {
      "default": "off",
      "allOf": [
        {
          "$ref": "#/definitions/FilterOptions"
        }
      ]
    }
  },
  "additionalProperties": false,
  "definitions": {
    "FilterOptions": {
      "title": "FilterOptions",
      "description": "Options for how filtering is done.",
      "enum": [
        "off",
        "if present",
        "required"
      ],
      "type": "string"
    }
  }
}

Result in JSON Schema Viewer:

"ref inside allOf" and "inline inside allOf" should ideally give the same visual result as "inline directly", since they express the same thing. If support for this was implemented, it would make JSON Schema Viewer more useful and reduce the need for repeating yourself. Pydantic outputs JSON Schema like this when a field is set to an enum and you define a default value for that enum (see pydantic/pydantic#2592 for an example).

Since it doesn't help to inline the $ref, the json-schema-ref-parser tool is not going to be of any help here on its own. The only workaround I can think of that would not involve changing JSON Schema Viewer, would be to add some post-processing to the JSON Schema that inlines the $ref and then identifies instances of allOf with a single subschema, and merged that subschema with the parent schema, eliminating the allOf.

Support: if-then-else in Draft-07 (conditionals)

Currently JSON Schema Conditionals are not supported by JSON Schema Viewer. This issue is to fix that: https://json-schema.org/understanding-json-schema/reference/conditionals.html

If you have an example of a JSON Schema you would like to be able to be viewable in JSON Schema Viewer that uses conditionals then please paste it here.

Does not support "const" keyword

Refer to https://json-schema.org/understanding-json-schema/reference/generic.html#constant-values

I am using the https://json-schema.app/ website. My json-schema contains enums and consts. The enums display correctly, but the const values are not displayed as expected. Const values were added in draft 6.

External Refs Resolution

Hi, given that external refs are not supported, i've tested out a local setup in which the only change im doing is adjusting the loadUrl functionality such that it utilises json-refs library. for which all references are resolved.

Old Code

 private loadUrl(url: string): void {
      fetch(url)
          .then(resp => resp.json())
          .then(schema => this.setState({ result: { schema, currentUrl: url } }))
          .catch(e => this.setState({ result: { currentUrl: url, schema: { message: e.message }}}));
   }

New Code

 private loadUrl(url: string): void {
      jsonRefs.resolveRefsAt(url).then((result) => 
         this.setState({ result: { schema: result.resolved as JsonSchema, currentUrl: url } })
      ).catch(e => this.setState({ result: { currentUrl: url, schema: { message: e.message }}})); 
  }

would such a PR be accepted?
maybe utilising a toggle in the homepage wether refs should be resolved or not, would switch between the two ?

Links are replacing `http` `$ref` values with `https`

Example:

HTML text of:

$ref: http://lvh.me:9876/address_schema.json

Has a link of:

http://lvh.me:8080/view/%23?url=https%3A%2F%2Flvh.me%3A9876%2Faddress_schema.json

Consider adding option to generate TypeScript typings for object type(s)

While playing with some external APIs the most annoying thing is to write types for it, or manually generating them from json-schema by external lib.

In lot of simple scenarios you'd like just to grab type for particular response for one endpoint.
From UI perspective, it could be just a button on object. Eventually - an option to generate all types based on json-schema (which might be simpler to be fair)

[ERR] Could not start server, fallback file not found

When attempting to run yarn http-serve this project as described in the README, on a Mac, I encountered...

$ http-server-spa dist index.html 8080
[ERR] Could not start server, fallback file not found
[TRY] http-server-spa <directory> <fallback> <port>
✨  Done in 0.34s.

yarn build resulted in

yarn run v1.22.19
$ rm -fr dist && webpack -c webpack.prod.js
Error: error:0308010C:digital envelope routines::unsupported
    at new Hash (node:internal/crypto/hash:67:19)
    at Object.createHash (node:crypto:135:10)
    at BulkUpdateDecorator.hashFactory (/Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/lib/util/createHash.js:138:18)
    at BulkUpdateDecorator.update (/Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/lib/util/createHash.js:44:50)
    at RawSource.updateHash (/Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/node_modules/webpack-sources/lib/RawSource.js:64:8)
    at NormalModule._initBuildHash (/Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/lib/NormalModule.js:752:17)
    at handleParseResult (/Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/lib/NormalModule.js:816:10)
    at /Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/lib/NormalModule.js:907:4
    at processResult (/Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/lib/NormalModule.js:639:11)
    at /Users/russellzarse/dev/tools/json-schema-viewer/node_modules/webpack/lib/NormalModule.js:691:5
^C

A quick search yielded This SO Post indicating this is a known issue web pack issue in NodeJS 17.

I use nodenv to manage NodeJS versioning. The following resolved the original issue.

nodenv install 16.15.1
nodenv local 16.15.1

Really great work btw, and thanks very much for open sourcing it.

Run instructions out of order

I believe the following two lines should be switched:

json-schema-viewer/README.md

Lines 22 to 23 in 8bf0f0a

	1. In one terminal, run `yarn http-serve`
	1. In another terminal, run `yarn build-dev --watch`

In a new build/run, the dist directory has not been created yet, so yarn http-serve will provide the following error and exit:

yarn run v1.22.19
$ http-server-spa dist index.html 8080
[ERR] Could not start server, fallback file not found
[TRY] http-server-spa <directory> <fallback> <port>

Make code editor resizable or soft-wrap

If the json in the editor has any reasonably long strings or has more than a few levels of depth the max width of 500px is not wide enough to accommodate seeing all of the data.

Please support a resizable editor element or implement an option to enable soft-wrapping of lines.

Allow people to paste in JSON Schemas that will be used for the remainder of the lifecycle of the app.

This was a request here: https://json-schema.slack.com/archives/C5CF75URH/p1612213784250100?thread_ts=1612208453.249400&cid=C5CF75URH

I suspect that the issue is that people want to be able to live edit their JSON Schema. The more I think about it, the more that I think that it would be better to have them upload the file somewhere that this tool can point to and just document that.

Support internal non-pointer references

According to 8.3.2, $ref might not be a JSON pointer, eg:

   {
       "$id": "http://example.net/root.json",
       "items": {
           "type": "array",
           "items": { "$ref": "#item" }
       },
       "definitions": {
           "single": {
               "$id": "#item",
               "type": "object",
               "additionalProperties": { "$ref": "other.json" }
           }
       }
   }

Currently, the schema viewer errors with Invalid JSON pointer. (it's trying to resolve #item as a JSON pointer, while in fact it's just an internal reference, pointing to http://example.net/root.json#item)

Warnings on External Links

People can add External Links to their JSON Schemas. Should I throw up a warning or some kind of indicator that they will leave the current site? Ask security minded people what they think.

Monaco Editor Integration

On the right-hand side of the JSON Schema Viewer it would be great to have the Monaco Editor integrated, with the automatic validation support. That way, we could let people edit and validate their objects live as they read the docs. That would be awesome.

Support for Dependencies in Draft-07

This would be to support dependencies in JSON Schema Viewer: https://json-schema.org/understanding-json-schema/reference/object.html#dependencies

If you have examples of using dependencies in a JSON Schema then please add that link to this issue.