Hybrid Enum Dictionary Structure

OwlFlow uses a Hybrid Enum approach for dictionary-backed fields (like Citizenship, Ethnicity, School Level, etc.). This provides strict GraphQL type safety for core data while maintaining compatibility with internal integer IDs and providing human-readable labels for the UI.

---

The Problem

Many dictionary fields in underlying systems use integer IDs (e.g., 1, 2, 3) for storage.

• IDs are opaque: An ID like 1 is meaningless without a separate lookup table.
• IDs are weak: In a GraphQL API, returning a generic Int or String for these fields loses type safety and the benefits of self-documentation.

The Solution

OwlFlow provides a more modern interface by bridging these fields using two primary components:

1. GraphQL Enums: Type-safe, SCREAMING_SNAKE_CASE values (e.g., US_CITIZEN) used for fields and inputs.
2. Display Mapping Query: A dictionaries query that maps these enums to their human-readable names and display order.

---

1. Schema Structure

Enums

All dictionary fields use specific enum types rather than generic strings. For example:

enum CitizenshipStatus {
  US_CITIZEN
  US_PERMANENT_RESIDENT
  US_TEMPORARY_RESIDENT
}

Display Items

The EnumDisplayItem type provides the necessary metadata for rendering UI components like dropdowns:

type EnumDisplayItem {
  value: String! # The enum value to send in mutations (e.g., "US_CITIZEN")
  name: String! # The human-readable label (e.g., "U.S. Citizen")
  order: Int # The preferred sort order for UI display
}

---

2. Usage Patterns

A. Populating Dropdowns

To build a select list in the UI, query the dictionary labels from the references namespace:

query GetCitizenshipOptions {
  references {
    dictionaries {
      citizenship {
        value
        name
        order
      }
    }
  }
}

B. Reading User Data

Fields on the Account or User types return the enum value directly. This allows your application to perform logic based on stable keys rather than volatile IDs or labels.

query GetMyProfile {
  me {
    citizenship # Returns "US_CITIZEN"
  }
}

C. Updating Profile Information

When updating a field, pass the enum value in the UpdateUserInput. The API will handle the translation to the backend.

mutation UpdateCitizenship($status: CitizenshipStatus!) {
  viewer {
    updateUser(input: { citizenship: $status }) {
      success
      user {
        citizenship
      }
    }
  }
}

# Variables:
# { "status": "US_CITIZEN" }

---

Available Dictionary Enums

The following fields currently follow this hybrid structure:

• citizenship (CitizenshipStatus)
• ethnicity (EthnicityType)
• careerGoal (CareerGoalType)
• militaryAffiliation (MilitaryAffiliationType)
• education.schoolLevel (SchoolLevelType)
• education.degree (DegreeField)
• education.degreeType (DegreeTypeEnum)