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 Spec | Message Format | Docs |
---|---|---|
Protobuf | Protobuf | Protobuf docs |
OpenAPI | Json | OpenAPI docs |
SOAP | XML | SOAP docs |
Avro | Avro | Avro 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
@Xml
model Person {
firstName : FirstName
}
You only need to apply the annotation to the top level entity.
Message format | Annotation | Links |
---|---|---|
Json | Not needed - default format | - |
Xml | com.orbitalhq.formats.Xml | Xml annotation docs |
Csv | com.orbitalhq.formats.Csv | Csv annotation docs |
Protobuf | Not supported in Taxi - Use a protobuf spec | File an issue to request support |
Avro | Not supported directly in Taxi - Use an Avro spec | File 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.