InputObject

Some fields in GraphQL expect you to provide an input object rather than just simple scalar types. The cynic::InputObject trait is used to define an input object and the easiest way to define that trait is to derive it:


#![allow(unused)]
fn main() {
#[derive(cynic::InputObject, Clone, Debug)]
pub struct IssueOrder {
    pub direction: OrderDirection,
    pub field: IssueOrderField,
}
}

The derive will work on any struct that matches the format of the input object and it may contain scalar values or other InputObjects. See Field Naming below for how names are matched between GraphQL & Rust.

By default the field names are expected to match the GraphQL variants exactly, but this can be controlled with either the rename_all top level attribute or the rename attribute on individual fields.

If there are any fields in the struct that are not on the GraphQL input type the derive will emit errors. Any required fields that are on the GraphQL input type but not the rust struct will also error. Optional fields may be omitted without error. This maintains the same backwards compatibility guarantees as most GraphQL clients: adding a required field is a breaking change, but adding an optional field is not.

Currently any missing optional fields will not be serialized in queries, whereas optional fields that are present in the struct but set to None will be sent as null.

Field Naming

It's a common GraphQL convention for fields to be named in camelCase. To handle this smoothly, Cynic matches rust fields up to their equivalent camelCase GraphQL fields. This behaviour can be disabled by specifying a rename_all = "None" attribute, or customised via alternative rename_all values or individual rename attributes on the fields.

Struct Attributes

An InputObject can be configured with several attributes on the struct itself:

  • graphql_type = "AType" tells cynic which input object in the GraphQL schema this struct represents. The name of the struct is used if it is omitted.
  • require_all_fields can be provided when you want cynic to make sure your struct has all of the fields defined in the GraphQL schema.
  • rename_all="camelCase" tells cynic to rename all the rust field names with a particular rule to match their GraphQL counterparts. If not provided this defaults to camelCase to be consistent with GraphQL conventions.
  • schema tells cynic which schema to use to validate your InlineFragments. The schema you provide should have been registered in your build.rs. This is optional if you're using the schema that was registered as default, or if you're using schema_path instead.
  • schema_path sets a path to the GraphQL schema. This is only required if you're using a schema that wasn't registered in build.rs.
  • schema_module tells cynic where to find your schema module. This is optional and should only be needed if your schema module is not in scope or named schema.

Field Attributes

Each field can also have it's own attributes:

  • rename="someFieldName" can be used to map a field to a completely different GraphQL field name.
  • skip_serializing_if="path" can be used on optional fields to skip serializing them. By default an Option field will be sent as null to servers, but if you provide skip_serializing_if="Option::is_none" then the field will not be provided at all.