Field Naming Conventions

Field naming conventions in Seaography define how database schema elements—such as tables, columns, and relations—are mapped to GraphQL types and fields. The framework provides a flexible system that allows developers to choose between standard casing styles (Snake Case vs. Camel Case), handle pluralization for collections, and implement custom renaming logic through the functional API.

These conventions ensure that the generated GraphQL API remains consistent with Rust's ecosystem while meeting frontend expectations for GraphQL schema design. The system supports both automatic derivation from SeaORM entities and explicit overrides via configuration.

Sources: src/lib.rs:77-85, CHANGELOG.md:144-150

Casing Strategies

Seaography supports multiple casing strategies for fields and types. By default, the project is configured to use field-camel-case, but this can be toggled via feature flags or programmatically through the BuilderContext.

Supported Case Styles

• Camel Case (camelCase): The default convention for GraphQL fields, making the API idiomatic for most frontend consumers.
• Snake Case (snake_case): Often used to mirror the underlying Rust field names or database column names directly.

Sources: Cargo.toml:50-71, CHANGELOG.md:207-208

Naming Logic Flow

The following diagram illustrates how Seaography resolves names during schema generation:

The framework utilizes specialized function types for these transformations:

• SimpleNamingFn: Box<dyn Fn(&str) -> String + Sync + Send>
• ComplexNamingFn: Box<dyn Fn(&str, &str) -> String + Sync + Send>

Sources: src/lib.rs:240-241, examples/sea-draw/src/schema.rs:90-101

Singular and Plural Conventions

Seaography provides sophisticated handling for entity names to distinguish between single-record lookups and collection queries. This is particularly relevant when dealing with relations and connection nodes.

Pluralization Feature

The field-pluralize feature (backed by the pluralizer crate) allows the framework to automatically generate plural names for collection fields. For example, a staff entity might expose a staff field for plural access, while a singular relation might be suffixed to avoid collisions.

Name Collision Handling

When a name collision occurs between a plural collection and a singular relationship, Seaography applies a _single suffix to the singular field to ensure schema validity.

{
  stores {
    nodes {
      storeId
      staff_single { # singular with _single suffix due to name collision
        firstName
      }
    }
  }
}

Sources: CHANGELOG.md:103-119, Cargo.toml:65

Custom Field Renaming

Developers can override default naming conventions using the functional API. This is achieved by providing custom logic to the EntityObjectConfig within the BuilderContext.

Implementation Example

Custom naming functions can be used to enforce specific formatting, such as converting entity names to UpperCamelCase for types and snake_case for columns.

fn type_name(entity_name: &str) -> String {
    singular(entity_name).to_upper_camel_case()
}

fn column_name(_entity_name: &str, column_name: &str) -> String {
    column_name.to_snake_case()
}

// Configuration in BuilderContext
let mut context = BuilderContext {
    entity_object: EntityObjectConfig {
        type_name: Box::new(type_name),
        column_name: Box::new(column_name),
        basic_type_suffix: "Basic".into(),
    },
    ..Default::default()
};

Sources: examples/sea-draw/src/schema.rs:41-47, examples/sea-draw/src/schema.rs:90-101

Macro-Based Naming

For custom queries and mutations, Seaography uses derive macros that respect either the original Rust identifier or an explicitly provided name.

Custom Output Types

The #[derive(CustomOutputType)] macro allows for an optional output_type_name attribute. If omitted, the macro stringifies the Rust struct identifier.

#[derive(Clone, CustomOutputType)]
pub struct PurchaseOrder {
    pub po_number: String, // Stringified to "po_number" or camelCased based on config
}

In the underlying implementation, the macro uses stringify! on the identifier unless an override is provided via the Args structure.

Sources: macros/src/custom_output_type.rs:13-25, CHANGELOG.md:88-95

Metadata and Internal Naming

Seaography reserves specific naming patterns for internal metadata and utility queries to avoid conflict with user-defined entities.

• Schema Metadata: The query _sea_orm_entity_metadata is used to expose SeaORM schema information via GraphQL.
• Active Enums: Registered enums are processed through register_active_enums, which maintains the naming defined in the SeaORM entity files.
• Ignored Files: During generation, files like mod.rs, prelude.rs, and sea_orm_active_enums.rs are filtered out from entity processing to prevent naming conflicts in the QueryRoot.

Sources: CHANGELOG.md:163-164, generator/src/writer.rs:18-30

Conclusion

Seaography's field naming conventions provide a balance between automation and control. By leveraging feature flags for global casing preferences, pluralization logic for relations, and a functional API for granular overrides, the framework ensures that the resulting GraphQL schema is both predictable and customizable. This architecture allows developers to maintain a clean separation between database-level identifiers and the exposed GraphQL API.

Sources: src/lib.rs:77-85, examples/sea-draw/src/schema.rs:85-110