Struct FieldDefinition 

pub struct FieldDefinition {
    pub name: FieldName,
    pub field_type: FieldType,
    pub nullable: bool,
    pub description: Option<String>,
    pub default_value: Option<GraphQLValue>,
    pub vector_config: Option<VectorConfig>,
    pub alias: Option<String>,
    pub deprecation: Option<DeprecationInfo>,
    pub requires_scope: Option<String>,
    pub on_deny: FieldDenyPolicy,
    pub encryption: Option<FieldEncryptionConfig>,
}

A field within a GraphQL type.

This represents a single field definition after compilation from authoring-language decorators. All data is Rust-owned.

JSONB Architecture Note

FraiseQL stores all field data in a JSONB column (typically data). The name field corresponds to the key in the JSONB object. SQL columns are only used for WHERE clause filtering, not data retrieval.

Example

use fraiseql_core::schema::{FieldDefinition, FieldDenyPolicy, FieldType};

let field = FieldDefinition {
    name: "email".into(),
    field_type: FieldType::String,
    nullable: true,
    description: Some("User's email address".to_string()),
    default_value: None,
    vector_config: None,
    alias: None,
    deprecation: None,
    requires_scope: None,
    on_deny: FieldDenyPolicy::default(),
    encryption: None,
};

Fields

name: FieldName

Field name - the key in the JSONB data column (e.g., “email”).

field_type: FieldType

Field type.

nullable: bool

Is this field nullable?

description: Option<String>

Optional description (from docstring).

default_value: Option<GraphQLValue>

Default value.

vector_config: Option<VectorConfig>

Vector configuration (for pgvector fields). Only present when field_type is Vector.

alias: Option<String>

GraphQL alias for this field (output key name in response). When set, the field value from JSONB key name is output under this alias. Example: { writer: author { name } } - reads JSONB key “author”, outputs as “writer”

deprecation: Option<DeprecationInfo>

Deprecation information (from @deprecated directive). When set, the field is marked as deprecated in the schema.

requires_scope: Option<String>

Scope required to access this field (field-level access control).

When set, users must have this scope in their JWT to query this field. The runtime FieldFilter validates these requirements.

Example

use fraiseql_core::schema::{FieldDefinition, FieldDenyPolicy, FieldType};

let field = FieldDefinition {
    name: "salary".into(),
    field_type: FieldType::Int,
    nullable: false,
    description: None,
    default_value: None,
    vector_config: None,
    alias: None,
    deprecation: None,
    requires_scope: Some("read:Employee.salary".to_string()),
    on_deny: FieldDenyPolicy::Reject,
    encryption: None,
};

on_deny: FieldDenyPolicy

Policy when a user lacks the required scope for this field.

• Reject (default): the entire query fails with a FORBIDDEN error.
• Mask: the query succeeds but this field returns null.

encryption: Option<FieldEncryptionConfig>

Encryption configuration for this field.

When set, the field’s value is transparently encrypted before being stored in the database and decrypted when read back. Encryption uses the key referenced by key_reference (fetched from the secrets manager) with the specified algorithm.

Implementations

impl FieldDefinition

pub fn new(name: impl Into<String>, field_type: FieldType) -> Self

Create a new required field.

pub fn nullable(name: impl Into<String>, field_type: FieldType) -> Self

Create a new nullable field.

pub fn vector(name: impl Into<String>, config: VectorConfig) -> Self

Create a new vector field.

Example

use fraiseql_core::schema::{FieldDefinition, VectorConfig};

let embedding = FieldDefinition::vector("embedding", VectorConfig::openai());

pub fn with_requires_scope(self, scope: impl Into<String>) -> Self

Add a scope requirement to the field (field-level access control).

Example

use fraiseql_core::schema::{FieldDefinition, FieldType};

let salary = FieldDefinition::new("salary", FieldType::Int)
    .with_requires_scope("read:Employee.salary");

pub const fn with_on_deny(self, policy: FieldDenyPolicy) -> Self

Set the deny policy for when a user lacks the required scope.

pub fn with_description(self, desc: impl Into<String>) -> Self

Add description to field.

pub fn with_default(self, value: GraphQLValue) -> Self

Add default value to field.

pub const fn with_vector_config(self, config: VectorConfig) -> Self

Add vector configuration to field.

pub fn with_alias(self, alias: impl Into<String>) -> Self

Set a GraphQL alias for this field (output key name in response).

The alias determines the key name in the JSON response, while name remains the JSONB key where data is read from.

Example

use fraiseql_core::schema::{FieldDefinition, FieldType};

// JSONB key "author" will be output as "writer" in the response
let field = FieldDefinition::new("author", FieldType::Object("User".to_string()))
    .with_alias("writer");
assert_eq!(field.output_name(), "writer");
assert_eq!(field.name, "author"); // JSONB key unchanged

pub fn output_name(&self) -> &str

Get the output name for this field (alias if set, otherwise name).

This is the key name that appears in the GraphQL JSON response.

pub fn jsonb_key(&self) -> &str

Get the JSONB key name for this field.

This is always name, regardless of alias. Used for:

• Reading data from JSONB column
• Building WHERE clause paths

pub const fn has_alias(&self) -> bool

Check if this field has an alias.

pub const fn is_vector(&self) -> bool

Check if this is a vector field.

pub fn deprecated(self, reason: Option<String>) -> Self

Mark this field as deprecated.

Example

use fraiseql_core::schema::{FieldDefinition, FieldType};

let field = FieldDefinition::new("oldId", FieldType::Int)
    .deprecated(Some("Use 'id' instead".to_string()));
assert!(field.is_deprecated());

pub const fn is_deprecated(&self) -> bool

Check if this field is deprecated.

pub fn deprecation_reason(&self) -> Option<&str>

Get the deprecation reason if deprecated.

pub fn with_encryption(self, config: FieldEncryptionConfig) -> Self

Add encryption configuration to this field.

pub const fn is_encrypted(&self) -> bool

Check if this field is encrypted.

pub fn is_primary_key(&self) -> bool

Whether this field is a primary key (name starts with “pk_” or equals “id”).

Trait Implementations

impl Clone for FieldDefinition

fn clone(&self) -> FieldDefinition

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for FieldDefinition

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for FieldDefinition

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl PartialEq for FieldDefinition

fn eq(&self, other: &FieldDefinition) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for FieldDefinition

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for FieldDefinition