Data formats

Data formats in Orbital

Data formats specify how Orbital should read and write data.

By default, Orbital assumes that data is provided as JSON. However, by adding a Data Format to a model, this can be modified to any type of serialization format.

API Specs and Message formats

Some API specs which define transport also have their own message format (eg., Protobuf). If that’s the case, you generally don’t need to do anything - Orbital applies the correct formats when parsing the API spec.

API SpecMessage FormatDocs
ProtobufProtobufProtobuf docs
OpenAPIJsonOpenAPI docs

Using message formats in Taxi

If you’re using Taxi to describe your API specs, you need to specify the data format that is used for reading/writing messages.

By default, messages are expected to be in JSON. Other formats can be specified using an annotation on the top level type.

For example:

import com.orbitalhq.formats.Xml

model Person {
  firstName : FirstName

You only need to apply the annotation to the top level entity.

Message formatAnnotationLinks
JsonNot needed - default format-
Xmlcom.orbitalhq.formats.XmlXml annotation docs
Csvcom.orbitalhq.formats.CsvCsv annotation docs
ProtobufNot supported in Taxi - Use a protobuf specFile an issue to request support
AvroNot supported directly in Taxi - Use an Avro specFile an issue to request support

Defining custom formats

Internally, Orbital uses a ModelFormatSpec to provide format-specific serialization & deserialization implementations.

While it is possible to define your own custom format, to load it into Orbital currently requires a custom build - available for Enterprise customers only.

Support for loading custom formats via Taxi projects is planned - Vote for this issue or reach out to us if you’d like to discuss getting this feature supported.

Pipeline specs