Import an Existing Schema and Extend It

Goal: Import a JSON Schema or OpenAPI spec into OWB, review what was created, extend the model with new entity types, and export back out to the original format.

Prerequisites

A JSON Schema (.json) or OpenAPI 3.x spec (.yaml or .json) file on your machine
An OWB account and access to a workspace (personal or org)

Steps

1. Create a new model and open the import dialog

From the dashboard, click New model. On the creation dialog, click Import from file instead of choosing a template or blank model.

Alternatively, create a blank model first, then click the Import button (upload icon) in the workbench toolbar at any time.

2. Upload the file and review the import summary

In the import dialog, choose your format:

JSON Schema — for Draft 7 / 2019-09 / 2020-12 documents
OpenAPI — for OpenAPI 3.x specs (YAML or JSON); schemas are extracted from components/schemas
OWL/XML — for Protégé-generated ontology files

Click Choose file and select your document. The importer parses the file immediately and shows a preview:

Number of entity types to be created
Number of relationships detected from $ref properties
Any warnings (unsupported constructs, schema features that don't map cleanly)

Review the preview carefully. Warnings don't block the import but flag constructs that were simplified or skipped.

Click Import to apply.

3. Inspect the generated entity types

The sidebar now lists every entity type created from the schema. Click through each one to review:

Properties — check that data types mapped correctly (e.g. integer → Integer, string with enum → Enum)
Inheritance — allOf with a $ref is imported as a parent/child relationship; verify the hierarchy is correct
Descriptions — imported from description fields in the source schema

Fix any issues directly in the panel: rename entity types, adjust property types, set required flags that didn't carry over.

4. Add new entity types for domain concepts not in the source

Your existing schema rarely captures everything. Add the concepts missing from the import by clicking + Add entity type in the sidebar.

For example, if you imported an e-commerce OpenAPI spec that had Product and Order but not Warehouse or Supplier, add them now. Set their properties, descriptions, and any inheritance relationships.

5. Create relationships between imported and new entity types

Select a new entity type, go to its Relationships section, and click + Add from [name]. You can target any entity type — imported or new — as the relationship endpoint.

Set cardinality for every relationship. Validation will flag any missing cardinality before you export.

6. Run validation

Click Validate in the toolbar. Work through any flagged issues — common ones after import are:

Relationships with no cardinality set
Entity types referenced in relationships that weren't created (import warnings)
Duplicate property names inherited through a chain

The drawer shows 0 issues when the model is consistent.

7. Export back to the original format

Click Export in the toolbar. Choose the same format you imported from:

JSON Schema — produces a Draft 7 document with $defs for each entity type
OpenAPI — produces an OpenAPI 3.x spec with schemas in components/schemas

Download the file and compare it to your input. New entity types and relationships will appear; any simplifications the importer made will be visible here. This round-trip check confirms the model faithfully represents your original schema.

8. Export to an additional target format

While the export drawer is open, choose a second format to generate output for downstream use — for example:

Prisma for the application database layer
GraphQL SDL for an API schema
HTML Docs for stakeholder review

What happens next

Snapshot as the migration baseline — click + New snapshot in Version History and label it v1 import baseline before making further changes. This preserves a restore point for the pre-extension state.
Publish and share — see the Build Your First Model workflow for the publish and share steps.
Export to multiple stacks — see the Multi-Stack Export workflow.

Entity Types — inheritance, abstract types
Relationships — cardinality and relationship properties
Exports — all supported formats and their output shape
Snapshots — baseline snapshots before large changes