Enums

FleetSync stores every enum as a short code: an integer for most enums, a two-letter string for a few such as Country. The API sends the same codes. This is different from standard GraphQL, where an enum value is sent as its name, for example INSTALLED.

The reasons are consistency and stability. The code is what FleetSync stores and what every FleetSync client uses, so the API cannot drift from the rest of the system. Codes also never change meaning, while a name may be renamed for clarity.

What you see on the wire

An enum field is a plain Int, or a plain String for string-coded enums. Responses contain the code:

{
  "data": {
    "getCars": {
      "items": [
        {
          "vin": "1HGCM82633A004352",
          "activePlate": { "status": 1 }
        }
      ]
    }
  }
}

Here 1 is the code of INSTALLED in the Plate2Ent_CarStatus enum. Arguments and input fields of enum type take the code as well. When you declare a variable for one, use Int or String as its type, because the live schema has no enum type to name:

query CarsInState($status: Int!) {
  ...
}

Reading the codes in the schema

The schema definition file that FleetSync shares with API customers is generated in a documentation mode. In this mode every coded enum appears as a GraphQL enum type, and each value carries its code as the value's description:

"This enum must be sent as its integer code value."
enum Plate2Ent_CarStatus {
  "1"
  INSTALLED
  "3"
  TEMP_REPLACED
  "2"
  UNINSTALLED
}

"This enum must be sent as its string code value."
enum Country {
  "US"
  US
  "CA"
  CANADA
}

Read it as a lookup table: send and receive the description, use the name in your own code. The codes are not sequential and their order carries no meaning.

The server itself does not know these enum types. It accepts and returns the same fields as plain Int or String, which is why variables must be declared with those types. The schema file is the only place where the names appear.

Encoded values

A few fields carry a whole JSON document inside a GraphQL String. FleetSync uses this for values that are more than a single code, for example the stage of a car, which can carry extra data such as the reason a car is in the shop. Such a field has a scalar type whose name ends in Encoded:

type Car {
  stage: CarStageEncoded!
}

The structure of the JSON is documented in the schema file too. Each Encoded scalar has a description that lists every variant of the value with its discriminator code and its fields. Nested types that are themselves discriminated, or that are enums, get their own paragraph. This is the entry for CarStageEncoded, copied from the schema file:

"""
JSON-encoded CarStage, sent as a String.

CarStage — JSON object with discriminator key "__t":
  -1 = Draft
  0 = Onboarding
  1 = Available
  2 = Rented { diamondRental: Boolean? }
  3 = Shop { reason: Shop.Reason }
  4 = Offboarding { offboardingId: ID<CarOffboardingEnt> }
  5 = Deployed
  6 = Retired { offboardingId: ID<CarOffboardingEnt> }
  7 = Transferring { transferId: ID<CarTransferEnt> }
  8 = Archived { reason: Archived.Reason }
  9 = IncompleteReturn

Shop.Reason — JSON object with discriminator key "__t":
  0 = Repair
  1 = Storage
  2 = DisposalHold

Archived.Reason — JSON object with discriminator key "__t":
  0 = Replaced { carId: ID<CarEnt> }
  1 = Canceled
"""
scalar CarStageEncoded

Read it as follows. The JSON is an object whose __t key holds the code of the variant. The other keys are the fields listed in braces after the variant name, and a variant without braces has no fields. A ? marks a field that can be null or absent, and ID<...> is an ID string like everywhere else in the API.

With that entry, a car in the shop for repair is returned as:

{
  "stage": "{\"__t\":3,\"reason\":{\"__t\":0}}"
}

__t: 3 is Shop, and its reason is a Shop.Reason object whose __t: 0 is Repair. A rented car looks like {"__t":2,"diamondRental":false}, and an available one is just {"__t":1}.

To read an encoded field, parse the string as JSON and switch on __t. Enums nested inside an encoded value follow the same code rule as everywhere else, and the schema entry lists their codes in the same way.

Recommendations

• Keep one mapping from code to name per enum in your integration, copied from the shared schema file, and reference names in your code rather than raw numbers.
• Treat a code you do not recognize as "unknown" instead of failing. FleetSync adds values over time, and existing codes keep their meaning.
• Do not depend on the order in which values are listed in the schema.