Dynamic Import (JSON-LD)

JSON-LD Dynamic importer

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-LD 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.

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

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

Import JSON-LD modal

Note: we recommend importing to an empty space since the dynamic importer will consider everything as new and will only add the nodes, if you want to only update the schema using an external source, please refer to the Merge page.

Once everything is set, click on 'Next'. CoreModels will then scan and validate the JSON-LD schema, then open the import/export profile UI with the suggested transformation.

Here's how the profile looks like with the properties from the sample file

  1. The properties from the file (re-ordering those will affect the export process)

  2. Each property mapping

  3. Profile Settings

Coremodels will suggest the transformation based on the property name and type: Example1: if the property is called 'comment' and all the values in that property are found as a simple text, Coremodels will search for all existing mixins, if it finds an exact match, it will suggest it. Example2: if the scan determines that the property can be transformed into a relation (by determining that the type is an 'object array' - see 'Type' in the table below), Coremodels will also search the existing relation names and suggest it.

Note that you can instruct Coremodels to use the configuration from an old import profile, Coremodels will do so, but it will always create a new profile.

Import/Export Profile

The following table explains each input of the import/export profile.

Field
Description
Notes

Key

The name of each JSON key that was found in the JSON-LD source.

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'. an example from the sample file would be the 'rdfs:comment' property. But if the value is actually referring to another node in the graph, then we should set it as 'Relation' (ex: 'subClassOf' property).

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

Space -> special handler to control the space property name.

Transformation Value

The options for this field are controlled by the 'Transformed To' field, you can select the mixin/relation name here.

we recommend choosing or creating a mixin/relation that has the same name as the property so it would be easier for users to navigate through the model.

Export Format

CoreModels will identify each property's type according to the JSON-LD 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.

"prefix:key": null -> Null

"prefix:key": "myValue" -> Primitive

"prefix:key": ["myValue"] -> Primitive Array

"prefix:key" : {"@id":"myValue"} -> Object

"prefix:key": [{"@id":"myValue"}] -> Object Array

Default Value

This property provides a default value to used in the export when there's no value.

If we are exporting ‘rdfs:comment’ , and some nodes does not have any value in that mixin, the default value will be used from here (ex: "TBD").

You can also input as @@null to provide a null value.

Value Prefix

If a property has a value that consistently starts with the same prefix, you can provide this value in this field. Coremodels will ignore that prefix during the import process and re-add it during the export.

Is Reversed

A checkbox used to reverse the relations direction. An appropriate example for reversing the relation is domainIncludes from schema.org, since this relation (in the JSON-LD schema) is stored in the element but it's actually saying that the type should have this element. domainIncludes is suggested to be reversed by default in Coremodels.

Technically, if we have this: "@id": "bts:NodeA",

"rdfs:subClassOf":[{"@id" :"bts:NodeB"}]

the subclassOf relation is from NodeA to NodeB, but if you set 'Is Reversed' to true,

Node B will be a subclass of Node A in Coremodels.

  • 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.

  • CoreModels requires that the @id property exists and the "Transformed To" is set to mixin and the 'transformation value' is also set - this is used as an identifier for the merge importer.

  • Coremodels will also store all the values that are found under the @context in the JSON-LD namespaces grid (can be found from the features tray -> Taxonomies -> JSON-LD Namespaces)

Once all the transformations are set you can click on Proceed to start importing.

The task details screen will show up to show the progress of each step, then it will auto refresh the page when the import is done.

The tasks grid can be found from the upper right corner -> three-dot menu -> Tasks.

After all the Import is finished, you can check the Types, Elements, and Taxonomies in your space. Here is an example of the Types after importing the sample file.

Types Grid - after importing the sample JSON-LD file

See the Export (JSON-LD) guide to see how to export your schema as JSON-LD from CoreModels

@type property

'@type' is a special property that determines how a JSON-LD object is imported as either a type, element, or taxonomy in CoreModels.

This is based on how the schema.org importer is originally designed according to the rdfs definition.

  • If "@type" is set to "rdfs:Class", then CoreModels will consider it as a type.

    • { "@id": "sampleType1", "@type": "rdfs:class" }

  • If "@type" is set to "rdf:property", then it will be considered as an element.

    • { "@id": "sampleElement1", "@type": "rdf:property"}

  • If "@type" is set to "rdfs:Class" AND the "rdfs:subClassOf" has "schema:enumeration", then it's a taxonomy.

    • { "@id": "sampleTaxonomyParent", "@type": "rdfs:Class", "rdfs:subClassOf": [{ "@id" : "schema:enumeration" }],

  • If "@type" is set to any previous taxonomy, then it's a child of that taxonomy.

    • { "@id": "sampleTaxonomyChild", "@type": "sampleTaxonomyParent"}

  • if "@type" was not set, the default behaviour is for CoreModels to consider the object as a type.

Read more on the @type property in this page

Last updated