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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.appear.sh/explanations/importing-an-openapi-spec.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.