Semantic Scalars

Semantic scalar types extend basic scalars (String, Int, Boolean) with domain-specific operators and automatic validation. This reference documents the available types, their operators, and validation rules.

What Are Semantic Scalars?

Semantic scalars are strongly-typed field values that understand their domain:

Basic scalar: email: String — just text, no validation
Semantic scalar: email: EmailAddress — validates format, enables domain filtering

When you use a semantic scalar, FraiseQL automatically generates:

GraphQL operators for filtering (see Rich Filters)
Validation rules to pre-validate parameters (see TOML Configuration)
SQL templates for database queries

Quick Reference

Type	Category	Use Case	Key Operators
Email	Contact	User emails	domainEq, domainIn, domainEndswith, localPartStartswith
PhoneNumber	Contact	Phone numbers	countryCodeEq, countryCodeIn, isValid, typeEq
URL	Contact	Web URLs	protocolEq, hostEq, pathStartswith
DomainName	Contact	Domain names	tldEq, tldIn
Hostname	Contact	Server hostnames	—
IBAN	Financial	Bank accounts	countryEq, checkDigitEq
CUSIP	Financial	US securities	—
ISIN	Financial	Int’l securities	—
SEDOL	Financial	UK securities	—
LEI	Financial	Legal entities	—
MIC	Financial	Exchanges	countryEq
CurrencyCode	Financial	ISO currencies	—
Money	Financial	Amounts	—
ExchangeCode	Financial	Stock symbols	—
ExchangeRate	Financial	Currency rates	withinRange
StockSymbol	Financial	Ticker symbols	eq
PostalCode	Location	Zip codes	—
Latitude	Location	Latitude coord	—
Longitude	Location	Longitude coord	—
Coordinates	Location	Lat/lng pairs	distanceWithin
Timezone	Location	IANA timezones	—
LocaleCode	Location	BCP47 locales	—
LanguageCode	Location	ISO639 codes	—
CountryCode	Location	ISO3166 codes	eq
Slug	Identifier	URL slugs	—
SemanticVersion	Identifier	SemVer (v1.2.3)	eq
HashSHA256	Identifier	SHA256 hashes	—
APIKey	Identifier	API credentials	—
LicensePlate	Identifier	Vehicle plates	—
VIN	Identifier	Vehicle numbers	wmiEq
TrackingNumber	Identifier	Shipment tracking	carrierEq
ContainerNumber	Identifier	Container IDs	ownerCodeEq
IPAddress	Network	IPv4/IPv6	versionEq
IPv4	Network	IPv4 only	—
IPv6	Network	IPv6 only	—
MACAddress	Network	MAC addresses	—
CIDR	Network	IP ranges	containsAddress
Port	Network	Port numbers	—
AirportCode	Transportation	Airport codes	—
PortCode	Transportation	Port codes	—
FlightNumber	Transportation	Flight numbers	—
Markdown	Content	Markdown text	—
HTML	Content	HTML markup	—
MimeType	Content	Content types	formatEq
Color	Content	Hex colors	formatEq
Image	Content	Image files	formatEq
File	Content	Attachments	—
DateRange	Ranges	Date intervals	overlaps
Duration	Ranges	ISO8601 durations	withinRange
Percentage	Ranges	0-100 values	—

Type Categories

Contact Information

EmailAddress

Email addresses with domain-specific operators.

GraphQL Type:

type User {
  email: EmailAddress!
}

input EmailAddressFilter {
  eq: String
  neq: String
  contains: String
  domainEq: String
  domainIn: [String!]
  domainEndswith: String
}

Python Decorator:

import fraiseql
from fraiseql.scalars import Email

@fraiseql.type
class User:
    email: Email

Operators:

eq — Exact email match
neq — Not equal
contains — Partial match (substring)
domainEq — Extract and match domain (e.g., “example.com”)
domainIn — Domain matches one of list
domainEndswith — Domain ends with (e.g., “*.company.com”)

Validation:

Format: RFC 5322 email format
Default rule: Pattern-based validation

Example Query:

query {
  users(where: { email: { domainEq: "company.com" } }) {
    id
    email
    name
  }
}

Database Support: ✅ PostgreSQL · ✅ MySQL · ✅ SQLite · ✅ SQL Server

PhoneNumber

International phone numbers with country code extraction.

Operators:

eq — Exact number match
countryCodeEq — Country code match (e.g., “+1” for US)
typeEq — Type match (mobile, fixed, voip, etc.)

Validation:

Format: E.164 international format
Country code validation

Example Query:

query {
  contacts(where: { phone: { countryCodeEq: "+1" } }) {
    id
    phone
  }
}

URL

Web URLs with protocol and domain matching.

Operators:

eq — Exact URL match
protocolEq — Protocol match (http, https, ftp)
domainEq — Domain extraction and match
pathContains — URL path substring

Validation:

Format: Valid HTTP/HTTPS/FTP URL
Protocol must be whitelisted

Example Query:

query {
  websites(where: { homepage: { protocolEq: "https" } }) {
    id
    homepage
  }
}

DomainName

Domain names (DNS).

Operators:

eq — Exact match
suffixEq — TLD match (e.g., “.com”)
level — Domain level depth (example.co.uk = level 3)

Validation:

Format: Valid domain name (DNS rules)
No IP addresses

Hostname

Server/network hostnames.

Operators:

eq — Exact hostname match
suffixEq — Suffix match (e.g., “.local”)

Validation:

Format: Valid hostname (alphanumeric + hyphen)

Financial

IBAN

International Bank Account Numbers.

Operators:

eq — Exact IBAN match
countryEq — Country code extraction
checksumValid — IBAN MOD-97 validation

Validation:

Format: Valid IBAN format per country
MOD-97 checksum validation
Length check per country

Example Query:

query {
  accounts(where: { iban: { countryEq: "DE" } }) {
    id
    iban
    currency
  }
}

CUSIP

Committee on Uniform Securities Identification Procedures (US securities).

Operators:

eq — Exact CUSIP
issuerEq — Issuer code extraction
typeEq — Security type

Validation:

Format: 9 alphanumeric characters
Check digit validation

ISIN

International Securities Identification Number.

Operators:

eq — Exact ISIN
countryEq — Country code extraction
typeEq — Security type

Validation:

Format: 12 alphanumeric characters
Check digit validation (Luhn algorithm)

SEDOL

Stock Exchange Daily Official List (UK/Irish securities).

Operators:

eq — Exact SEDOL
issuerEq — Issuer sector

Validation:

Format: 7 alphanumeric characters
Check digit validation

LEI

Legal Entity Identifier.

Operators:

eq — Exact LEI
countryEq — Jurisdiction extraction

Validation:

Format: 20 alphanumeric characters
Check digit validation

MIC

Market Identifier Code (ISO 10383).

Operators:

eq — Exact MIC
typeEq — Market type (XETR, XETRA, etc.)

Validation:

Format: 4 alphanumeric characters

CurrencyCode

ISO 4217 currency codes.

Operators:

eq — Exact code match (e.g., “USD”)
symbolEq — Currency symbol ($, €, etc.)
decimalPlacesEq — Decimal places (usually 2)

Validation:

Format: 3-letter ISO code
Must be valid currency

Example Query:

query {
  transactions(where: { currency: { symbolEq: "$" } }) {
    id
    amount
    currency
  }
}

Money

Monetary amounts with currency.

Operators:

eq — Exact amount
currencyEq — Currency match
amountGte / amountLte — Range queries

Validation:

Format: amount + 3-letter currency code
Positive amounts

ExchangeCode

Stock exchange codes.

Operators:

eq — Exact exchange code
typeEq — Exchange type

Validation:

Must be valid exchange identifier

ExchangeRate

Foreign exchange rates.

Operators:

eq — Exact rate
baseCurrencyEq — Base currency code
quoteCurrencyEq — Quote currency code

Validation:

Format: decimal number
Valid currency pairs

StockSymbol

Stock ticker symbols.

Operators:

eq — Exact ticker
exchangeEq — Exchange code match

Validation:

Format: 1-5 character symbol
Valid exchange

Location/Address

PostalCode

Postal codes, ZIP codes, etc.

Operators:

eq — Exact code
countryEq — Country code
formatEq — Format type (US=5 digits, UK=varied, etc.)

Validation:

Format varies by country
Country-specific validation

Example Query:

query {
  addresses(where: { zipCode: { countryEq: "US" } }) {
    id
    street
    zipCode
  }
}

Latitude

Geographic latitude (-90 to +90).

Operators:

eq — Exact latitude
rangeEq — In latitude range
hemisphereEq — North/South hemisphere

Validation:

Range: -90 to +90
Decimal precision

Longitude

Geographic longitude (-180 to +180).

Operators:

eq — Exact longitude
rangeEq — In longitude range

Validation:

Range: -180 to +180
Decimal precision

Coordinates

Latitude/longitude pairs for geospatial queries.

Operators:

eq — Exact location
distanceWithin — Distance from point in kilometers (uses PostGIS ST_DWithin)

Validation:

Valid latitude (-90 to +90)
Valid longitude (-180 to +180)

Example Query:

query {
  restaurants(where: {
    location: {
      distanceWithin: {
        latitude: 40.7128
        longitude: -74.0060
        radiusKm: 5
      }
    }
  }) {
    id
    name
    location { latitude longitude }
  }
}

Database Support:

PostgreSQL: Native PostGIS ST_DWithin

Timezone

IANA timezone identifiers.

Operators:

eq — Exact timezone
offsetEq — UTC offset (e.g., “UTC-5”)
dstAwareEq — Has daylight saving time

Validation:

Must be valid IANA timezone ID

Example Query:

query {
  users(where: { timezone: { offsetEq: "UTC-5" } }) {
    id
    name
    timezone
  }
}

LocaleCode

BCP 47 language locale codes (e.g., “en-US”, “fr-CA”).

Operators:

eq — Exact locale
languageEq — Language code (en, fr, de)
regionEq — Region code (US, CA, DE)

Validation:

Format: xx or xx-YY (language-COUNTRY)

LanguageCode

ISO 639 language codes (en, fr, de, etc.).

Operators:

eq — Exact code
scriptEq — Script type (Latin, Cyrillic, etc.)

Validation:

2-3 letter ISO 639 code

CountryCode

ISO 3166-1 alpha-2 country codes (US, GB, FR, etc.).

Operators:

eq — Exact country code match

Validation:

Must be 2-letter ISO code
Valid country

Example Query:

query {
  users(where: { country: { eq: "US" } }) {
    id
    name
    country
  }
}

Identifiers

Slug

URL-friendly slugs (lowercase, hyphens, no spaces).

Operators:

eq — Exact slug
contains — Partial match

Validation:

Format: [a-z0-9-]+
No spaces or special characters

Example Query:

query {
  articles(where: { slug: { eq: "getting-started" } }) {
    id
    title
    slug
  }
}

SemanticVersion

Semantic versioning (v1.2.3, 1.2.3-alpha, etc.).

Operators:

eq — Exact version

Validation:

Format: X.Y.Z or X.Y.Z-prerelease+build

HashSHA256

SHA-256 hashes (64 hex characters).

Operators:

eq — Exact hash
formatEq — Format (hex, base64)

Validation:

Format: 64 hexadecimal characters

APIKey

API authentication keys.

Operators:

eq — Exact key
prefixEq — Key prefix match
lengthEq — Length validation

Validation:

Length check
Character whitelist
Prefix validation

LicensePlate

Vehicle license plates.

Operators:

eq — Exact plate
countryEq — Country/region
typeEq — Plate type (standard, vanity, etc.)

Validation:

Format varies by country

VIN

Vehicle Identification Numbers.

Operators:

eq — Exact VIN
wmiEq — World Manufacturer ID (first 3 characters)
yearEq — Manufacturing year extraction

Validation:

Format: 17 characters
Check digit validation (Luhn algorithm)

Example Query:

query {
  vehicles(where: { vin: { wmiEq: "1G1" } }) {
    id
    brand
    vin
  }
}

TrackingNumber

Shipment tracking numbers.

Operators:

eq — Exact number
carrierEq — Carrier (UPS, FedEx, DHL, etc.)
typeEq — Type (standard, express, etc.)

Validation:

Format per carrier
Check digit validation

ContainerNumber

ISO 6346 shipping container numbers.

Operators:

eq — Exact container ID
ownerCodeEq — Owner company code

Validation:

Format: 11 alphanumeric characters
Check digit validation

Network

IPAddress

IPv4 or IPv6 addresses.

Operators:

eq — Exact IP
versionEq — IP version (4 or 6)
cidrContains — In CIDR range

Validation:

Valid IPv4 or IPv6 format

Example Query:

query {
  devices(where: { ipAddress: { versionEq: 4 } }) {
    id
    hostname
    ipAddress
  }
}

IPv4

IPv4 addresses only.

Operators:

eq — Exact IP
classEq — IP class (A, B, C, D, E)
isPrivateEq — Private IP range
cidrContains — In CIDR range

Validation:

Valid IPv4 format (x.x.x.x)

IPv6

IPv6 addresses only.

Operators:

eq — Exact IP
scopeEq — Scope (link-local, global, etc.)

Validation:

Valid IPv6 format

MACAddress

Media Access Control addresses.

Operators:

eq — Exact MAC
manufacturerEq — OUI manufacturer code

Validation:

Format: xx:xx:xx:xx:xx:xx or xx-xx-xx-xx-xx-xx

CIDR

Classless Inter-Domain Routing blocks.

Operators:

eq — Exact CIDR
containsAddress — IP in range
overlaps — CIDR overlap

Validation:

Valid CIDR notation (e.g., “192.168.0.0/24”)
IP version consistency

Example Query:

query {
  networks(where: { subnet: { containsAddress: "192.168.1.100" } }) {
    id
    subnet
  }
}

Port

Network port numbers (0-65535).

Operators:

eq — Exact port
serviceEq — Service name (HTTP, SSH, etc.)
isReservedEq — Well-known port (0-1023)

Validation:

Range: 0-65535
Known port validation (optional)

Transportation

AirportCode

IATA airport codes.

Operators:

eq — Exact code
countryEq — Country code
typeEq — Airport type

Validation:

Format: 3-letter IATA code

PortCode

UN/LOCODE port codes (5-character code).

Operators:

eq — Exact code
countryEq — Country code
regionEq — Region/state

Validation:

Format: 5-character code

FlightNumber

Airline flight numbers.

Operators:

eq — Exact number
carrierEq — Airline code
routeEq — Route (origin-destination)

Validation:

Format per airline

Content

Markdown

Markdown-formatted text content.

Operators:

eq — Exact content
contains — Substring match
headingCountEq — Number of headings
linkCountEq — Number of links

Validation:

Valid Markdown syntax

HTML

HTML markup content.

Operators:

eq — Exact content
contains — Substring match
tagEq — Contains specific tag
validEq — Well-formed HTML

Validation:

Valid HTML syntax (optional)

MimeType

MIME types (e.g., “application/json”).

Operators:

eq — Exact type
typeEq — Main type (application, text, image)
subtypeEq — Subtype (json, html, png)

Validation:

Valid MIME type format

Example Query:

query {
  files(where: { mimeType: { typeEq: "image" } }) {
    id
    filename
    mimeType
  }
}

Color

Hex color codes (#RRGGBB or #RGB).

Operators:

eq — Exact color
formatEq — Format (hex, rgb, hsl)

Validation:

Valid hex color format

Image

Image file content with metadata.

Operators:

eq — Exact image
formatEq — Image format (JPEG, PNG, WebP)

Validation:

Valid image format

File

File attachments and binary content.

Operators:

eq — Exact file
mimetypeEq — MIME type match
sizeRange — File size limits

Validation:

File type whitelist
Size limits

Ranges/Measurements

DateRange

Date intervals with start and end dates.

Operators:

eq — Exact range
overlaps — Overlaps with date range

Validation:

Start ≤ End
Valid ISO8601 dates

Example Query:

query {
  projects(where: {
    timeline: {
      overlaps: {
        start: "2024-06-01T00:00:00Z"
        end: "2024-08-31T23:59:59Z"
      }
    }
  }) {
    id
    name
  }
}

Duration

ISO 8601 durations (e.g., “P1Y2M3DT4H5M6S”).

Operators:

eq — Exact duration
withinRange — Duration within a range

Validation:

Valid ISO 8601 format

Percentage

Percentage values (0-100).

Operators:

eq — Exact percentage
rangeEq — In range
gte / lte — Greater/less than

Validation:

Range: 0-100
Optional decimal places

Example Query:

query {
  products(where: { discount: { gte: 10, lte: 50 } }) {
    id
    name
    price
    discount
  }
}

Integration with Rich Filters

All semantic scalar types work seamlessly with FraiseQL’s Rich Filters feature:

query {
  # Query using rich filter operators
  users(where: {
    email: { domainEq: "example.com" }
    location: { distanceWithin: { latitude: 40.7, longitude: -74.0, radiusKm: 5 } }
    country: { eq: "US" }
  }) {
    id
    email
    location { latitude longitude }
    country
  }
}

Validation Rules

Validation rules for semantic scalars are configured in TOML:

[fraiseql.validation]
# Email domain must be valid
email_domain_eq = { pattern = { pattern = "^[a-z0-9]([a-z0-9-]*\\.)*[a-z0-9]([a-z0-9-]*[a-z0-9])?$" } }

# Distance must be within valid range
distance_within_radius_km = { range = { min = 0, max = 40075 } }

# Country code must be valid ISO 3166-1
country_eq = { enum = { values = ["US", "CA", "GB", "FR", "DE"] } }

See TOML Configuration - Validation for complete validation documentation.

Next Steps

Rich Filters

Rich Filters — Learn how to use semantic scalars for filtering

TOML Configuration

TOML Configuration — Configure validation rules

Query Operators

Query Operators — Standard operators for all scalars