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.

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

---

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.