Orbital usesSemantic schemas to describe how data relates between systems. For OpenAPI, thismeans enriching return types and input parameters with metadata to describe them semantically.

To do this, we embed Taxi metadata within the OpenApi specs.

​

Adding Taxi annotations to OpenApi specs

Taxi annotations use a customx-taxi-type block within OpenApi specs.

Example:

x-taxi-type:# The name of the typename: com.acme.MyType# Optional.  Indicates if the type should be created if not already present.create:false

Thecreate element is optional, and overrides the default behaviour.

Ifcreate is set tofalse, then schemas which attempt to publish types that aren’t already defined on the schema serverare rejected as compilation errors.

This is to prevent accidental typos.

However, the default behaviour forcreate is different between response models and attribute types:

​

Describing response types

Response models returned from API calls can be enriched to include semantic metadata

​

Assigning Taxi type names to models

You can optionally define a custom type name for response types being published to Orbital.If omitted, then the type name is inferred from the rest of the schema

components:schemas:Pet:# Assign a Taxi type name to the model.# Optionalx-taxi-type:name: petstore.Pet# Everything else is standard OpenApi spec...allOf:-$ref:'#/components/schemas/NewPet'- required:

​

Adding type annotations to attributes

Enrich attributes with semantic type metadata

NewPet:required:- nameproperties:name:x-taxi-type:name: petstore.Nametype: stringtag:x-taxi-type:name: petstore.Tagtype: string

By default, it’s expected that types referred to inx-taxi-type within attributes have already been defined on the schema server, as part of yourcore taxonomy.

However, if you are intentionally publishing new types from your OpenApi spec, then setcreate totrue:

NewPet:required:- nameproperties:name:x-taxi-type:name: petstore.Name# petstore.Name will be created if not presentcreate:truetype: string

​

Describing service parameters

Inputs into services can also be enriched, to annotate the semantic data required.

Simply add ax-taxi-type annotation to each input, containing aname attribute with a reference to the name of the type from yourcore taxonomy

## ... OpenApi spec trimmed...paths:  /pets/{id}:get:description: Returns a user based on a single ID, if the user does not have access to the petoperationId: find pet by idparameters:-name: idin: pathdescription: ID of pet to fetchrequired:trueschema:type: integerformat: int64x-taxi-type:name: petstore.PetId# <-- Name of type from core taxonomy

​

Publishing OpenAPI specs to Orbital

Once you have added taxi annotations to your OpenApi spec, you’re ready to publish it to Orbital.

​

Different ways to publish OpenAPI specs

There are a few different ways to expose your OpenAPI spec to Orbital, each which suits different team workflows.

​

Guide: Importing OpenAPI projects via the UI

Navigate to/data-source-manager/add within your Orbital UI.

Next, select a project to import into, then choose “Swagger / Open API” from the data source dropdown.

• Either provide the OpenApi spec file directly, or enter a Url to load the spec from.
• Provide a default namespace. (eg:com.petflix.pets). Services from your OpenAPI spec are imported into this namespace
• If your OpenAPI spec doesn’t define a base url (ie.,:servers/url), then specify a Base url. All paths in the OpenApi spec are treated as relative to this path.
• Then click Configure

​

Preview your imported schema

Your imported OpenApi spec will be available for you to browse, to make sure everything looks correct.

Any types that have been defined ascreate: true within the Yaml spec should appear wihtin the Types section.

Services and operations should’ve been created for all endpoints within your OpenApi spec.

At this point, you can edit types (by clicking on thepencil icon next to the type name) to further refine your schema.Once you’re happy, click Save, and the OpenApi spec will be imported.