# Importing an OpenAPI spec

## **OpenAPI Import Overview**

When you upload an OpenAPI specification to Appear, the system parses and stores your spec in a structured domain model. The goal is to remain as close to the original spec as possible, while providing a consistent output format for downstream tooling.

* **Storage:** Imported data is stored in its original shape. Nested objects are preserved without modification.
* **Validation:** Appear attempts to recover from minor issues, but invalid specifications may fail to process. You can further validate your specification post import.
* **Transactions:** Imports are transactional. If any step fails, no changes are saved.
* **Output version:** Regardless of the uploaded version, Appear normalizes output to **OpenAPI 3.1**.

***

## **Schema to Domain Model Mapping**

Below is a reference of how core OpenAPI objects are mapped inside Appear.

<table><thead><tr><th width="147.484375">OpenAPI Object</th><th width="313.40234375">Mapping in Appear</th><th>Notes</th></tr></thead><tbody><tr><td><strong>Info</strong></td><td><code>title → service.name</code><br><code>summary → service.summary</code><br><code>description → service.description</code><br><code>termsOfService, contact, license, version → service.metadata</code></td><td><code>x-*</code> extensions stored as metadata</td></tr><tr><td><strong>Servers</strong></td><td>Fully supported, including variables</td><td></td></tr><tr><td><strong>Components</strong></td><td><code>schemas → resources</code><br><code>requestBodies → requests</code><br><code>pathItems → paths</code></td><td><code>links</code> and <code>callbacks</code> not supported</td></tr><tr><td><strong>Paths</strong></td><td>Each path creates a new <code>path</code> object</td><td><code>x-*</code> extensions not supported</td></tr><tr><td><strong>Operations</strong></td><td>All properties supported</td><td><code>callbacks</code> not supported</td></tr><tr><td><strong>Parameters</strong></td><td>Fully supported</td><td></td></tr><tr><td><strong>Request Body</strong></td><td>Creates <code>request</code> object with schema, examples, encodings</td><td>If <code>required: false</code>, an alternate request with empty body is created</td></tr><tr><td><strong>Responses</strong></td><td>Each response mapped to <code>response</code> object keyed by status code</td><td><code>links</code> not supported</td></tr><tr><td><strong>Headers</strong></td><td>Fully supported</td><td></td></tr><tr><td><strong>Examples</strong></td><td>Fully supported</td><td></td></tr><tr><td><strong>Tags</strong></td><td>Inline tags are supported; tag metadata is not</td><td></td></tr><tr><td><strong>References</strong></td><td>Always embedded in parent</td><td></td></tr><tr><td><strong>Schemas</strong></td><td>Saved as <code>resource.schema</code></td><td>Supports discriminators, examples, and <code>x-*</code> extensions</td></tr></tbody></table>

***

## **Unsupported Features**

Currently not supported (will be ignored if present in your spec):

* `links` (Response/Components/Link objects)
* `callbacks` (Operation/Components/Callback objects)
* `tag metadata` (only inline tags are preserved)
* `x-*` extensions in `Paths` and some nested objects

***

## **Notes & Limitations**

* Example values from `example` and `examples` are merged.
* Encoding properties and custom `x-*` values are preserved as metadata where supported.
* Future updates will expand support for currently unsupported objects.