Dynamic (JSON Schema)

Step By Step Guide

(First make sure to create a space so we can import our file into it - as this is a pre-request for any import operation)

Create Space Modal

From the upper right corner, click on the three-dot menu and select 'Plugins' and click 'Open' next to the JSON-Schema Importer to open the import modal.

UI Guide: Plugins

Once the modal shows up, you can give a name for the import, this will be used in the logs and as a name for the import/export profile.

The name of the chosen profile will also be used in suggesting the default mixin name where new columns would be added.

If the profile name is 'JSON Schema profile', the auto generated mixin will be 'JSON Schema profile-mixin'

The 'In Space' field is required, you must create a space to be able to select it here.

Click on 'Create Profile' to advance into the profile page.

JSON Schema profile - first step

The top bar is for the profile settings (1)

(2) Add Data Source

You need to provide one or more JSON Schema files that will be scanned and validated. These files will form the basis of your import profile.

You can either add the Schema URL or upload a file (with the .json extension), or even connect your account to github and fetch the file from there. We will use a simple example, you can use this url.

Once added, the file will appear in the list (4) with its type and status.

Alternatively you can use the Crawl URL feature (3) where you can provide a url, and it will scan for all JSON links and automatically add it to the list.

You can also provide a github folder url in the Crawl URL feature (3) and it will automatically add the files in that directory

Once the schema files are added click to scan the files (5), this will start a two phases scans

  1. First, it will scan for used references that are included in $ref and automatically add them in the list. If any new reference is added you will get a prompt in order to continue or review the list.

  2. Second, CoreModels will scan the files and detect all the JSON Schema (and non-JSON Schema) keywords that have been used in your schema.

JSON Schema Profile preview

The profile shows all the found keywords that are used in your schema, $id, $anchor, $ref etc..

Some keys will have some disabled fields because they have some special handling in CoreModels to align with how they are used. You will find below a table for each option:

Input
Description
Notes

Key

The name of each JSON key that was found in the JSON Schema sources.

it may be followed by a hint, if the key was a special JSON Schema key.

Transformed to

This field controls the options found in 'transformation value'. In simple terms, when a field is storing regular text values, we choose 'mixin' or 'new mixin'. an example from the sample file would be the '$id' property.

But if the value is actually referring to another node in the graph, then we should set it as 'Relation' (ex: 'properties' key).

None -> do not import.

Mixin -> the values will be stored as text, allows choosing mixins under 'transformation value' column.

New Mixin -> the values will be stored as text, allows entering the new mixin name.

Relation -> the values will point to other nodes, allows choosing relations under 'transformation value' column (if the importer finds a relation to a non-existing node, it will automatically create it).

Relation -> the values will point to other nodes, allows entering the new relation name

Export Format

CoreModels will identify each property's type according to the JSON Schema values that were found for this property. changing this has no impact during the import but it's stored to preserve how each property should look like in the export.

"key": null -> Null

"key": true -> Boolean

"key": 12 -> number

"key": "myValue" -> String

"key" : {"innerKey":"innerValue"} -> Object

"key": ['val1', 'val2'] -> Array

CoreModels treats object schemas as types, while all other schemas are considered elements. A schema is identified as a type if either:

  • The value of the type keyword is set to "object", or

  • The schema defines a properties keyword.

By clicking the proceed button with the import, CoreModels will validate and show any necessary notification, then prompt the user in order to continue, and show the tasks UI where it will start the import process.

  • Coremodels will ignore the following:

    • Any property that has 'Transformed To' set as “null”.

    • Any property that has a 'Transformed to' set to mixins or relation but does not have a value under 'transformation value'.

    • Any property that does not have a key (if the key was removed from the profile).

  • CoreModels will validate against the case of having two properties with the same transformation value.

Once it's done, CoreModels will auto refresh the page.

We can now navigate to the Types Grid tab and see the schema. The sample we used should show the following.

JSON Schema Sample file import result - Types Grid
JSON Schema Sample file import result - card preview

Next, let's configure the grids to show the mixins and the rules that were added along with the schema.

JSON Schema Sample file import result - grid configuration

Open the 'configuration' side panel (1), and configure the grid to show 'JSON Schema Rules' and the 'JSON Schema profile-mixin' or the profile, you can then explore the added elements, and find the metadata or the validation rules for your schema.

CoreModels has a special UI for 'Combination' and 'Conditional' keywords, such as anyOf, allOf, oneOf, not, if, else, then. All of them can be managed using the 'JSON Schema Rules' mixin, it provides a powerful UI - the 'Rule Builder' - where you can view and edit the rules.

JSON Schema Sample file import result - rules viewer

Now that you have imported your schema, let's see how to export it or synchronize it from github using the merge feature, or push the changes from CoreModels to the github repository Push To Github (JSON Schema).

Last updated