# The editor's Library

Source: https://api-genie.dev/docs/reference/editor/library

The Library is the panel under the file list in the API Genie editor. It holds two kinds of
schemas, and you drag schemas between it and the spec:

- **My schemas**: schemas you keep. The editor keeps them outside your files (ADR-193): in the
  browser's storage for the site on the web, in the desktop app's own storage, and in the
  extension's global storage in VS Code.
- **Library folders**: folders of YAML or JSON files beside or above the spec folder, such as a
  `shared` repository checked out next to it. Their files open with the spec folder's. A `$ref`
  from the spec into them is a relative path, `../shared/errors.yaml#/Error`, which resolves,
  renames and inlines like a reference between two files of the spec folder.

Nothing about the Library is written to a spec. Where each library folder is gets kept per spec
folder by the host.

## Adding a library folder

| Host | How |
| --- | --- |
| Web | Type where the folder is, relative to the spec folder (`../shared`), then *Add library folder…* and pick it. After a reload, *Open* asks for access again. Needs the File System Access API. |
| Desktop | *Add a library folder…* and pick it; the editor works out its path. After a restart, *Open* shows the folder in the dialog to allow access again. |
| VS Code | List the folders in the `apigenie.editor.libraryFolders` setting, by their path from the workspace folder: `["../shared"]`. They open with the editor. |

A library folder sits at most 8 levels above the spec folder, never inside it. ✕ closes a library
folder and forgets it; it refuses while a file of the folder has unsaved changes.

A library file lists schemas at its top level, as a shared file of the spec folder does, or under
`components/schemas` when it is an OpenAPI or AsyncAPI file.

## Dragging a schema into the spec

What you drag:

- a row of My schemas;
- a schema of a library folder;
- a schema in the spec: a schema in the tree, the handle (⠿) of a row of the schema editor, the
  chip of a schema field.

Where you drop it, and what the editor asks when there is a choice:

| Dropped on | From My schemas | From a library folder |
| --- | --- | --- |
| A schema field (a request or response body, a parameter, a header, a message payload, `items`) | *Copy it here*, or *Add it as a component and refer to it* | *Refer to it in the library*, *Copy it here*, or *Copy it into the components and refer to it* |
| A row of the schema editor: an object takes it as a new property named after it, an array as its `items` | the same as a schema field | the same as a schema field |
| The `allOf`, `oneOf` or `anyOf` row of the schema editor | a new branch, with the same choices | a new branch, with the same choices |
| A spec, or its *Schemas*, in the tree | a new component, without asking | a copy in the components, without asking |

A schema of the spec dropped on a schema field offers *Refer to it* and *Copy it here*.

*Use* on a row of My schemas adds it to the components of the selected file, as dropping it on
that spec in the tree does. Escape, or a click outside the menu, cancels a drop. Each drop is one
step of Undo.

### What comes along with a copy

A schema that refers to other schemas brings them along: they are added to the components of the
spec, and its references point to them. A component of the spec with the same name and the same
content is used as it is; one with the same name and other content leaves the copy under the next
free name (`Category-2`), which the status bar reports. A schema that refers to itself becomes one
component.

A reference that leads nowhere in the editor (a URL, a broken `$ref`) is copied as written, and
the status bar reports it.

### Dialects

A copy is converted to the dialect of the file it lands in. What has no counterpart is kept as
written, and the status bar names it.

| From | To | Converted |
| --- | --- | --- |
| OpenAPI 3.0 | OpenAPI 3.1, AsyncAPI 3.0 | `nullable: true` to a `null` in `type` (or in `enum`, without `type`), boolean `exclusiveMinimum` and `exclusiveMaximum` to numbers, `example` to `examples` |
| OpenAPI 3.1, AsyncAPI 3.0 | OpenAPI 3.0 | a `type` list of one type and `null` to `nullable: true`, `const` to a one-value `enum`, numeric exclusive bounds to boolean ones, the first of `examples` to `example` |
| OpenAPI 3.1 | AsyncAPI 3.0 | `example` to `examples`; `$defs`, `prefixItems`, `unevaluatedProperties` and the other 2020-12 keywords stay, with a note |

The dialect of a library file is OpenAPI 3.0's when its schemas use `nullable` or boolean exclusive
bounds, and JSON Schema 2020-12's otherwise.

## Dragging a schema into the Library

| Dropped on | What happens |
| --- | --- |
| My schemas | A copy is kept, with the schemas it refers to, under the schema's name (`Order-2` when taken). *Keep … in my library* in the schema editor does the same. |
| A file of a library folder | *Copy it into* the file, or *Move it to* the file *and refer to it*: the schema leaves the spec, and a `$ref` to the library takes its place. A component that moves keeps its name and every reference to it follows. |

*Move* is refused while the schema refers to other schemas of the spec folder, since a library
file refers only to its own folder and to other library folders: copy those schemas to the
library first. The library file is saved into its library folder with the spec's files.

*Rename* and ✕ on a row of My schemas rename and delete it. The search box filters both parts of
the Library by name, and a click on a row shows its schema.
