Type System
Define custom data structures, enumerations, and interfaces in Spectral.
Keywords
type- Define custom data structuresenum- Define enumerations with constrained valuesinterface- Define structural contracts (similar to types)
type Keyword
Define custom data structures with named fields and types.
Syntax
type TypeName {
fieldName: fieldType
anotherField: anotherType
}
Supported Field Types
| Type | Description | Example |
|---|---|---|
string | Text values | "hello" |
number | Numeric values | 42, 3.14 |
boolean | True/false values | true, false |
datetime | Date and time values | ISO 8601 format |
array | Collection of values | [1, 2, 3] |
map | Key-value pairs | {key: value} |
| Custom types | Reference other types | Product, Order |
| Enums | Constrained values | OrderStatus |
Examples
Basic Type Definition
type Product {
id: string
name: string
price: number
description: string
inStock: boolean
}
Type with Collections
type Order {
id: string
customerId: string
items: array
metadata: map
createdAt: datetime
}
Nested Types
type Address {
street: string
city: string
zipCode: string
country: string
}
type Customer {
id: string
name: string
email: string
shippingAddress: Address
billingAddress: Address
}
Type with Enum Reference
enum Priority {
low
medium
high
critical
}
type Task {
id: string
title: string
priority: Priority
dueDate: datetime
}
enum Keyword
Define enumerations for values that should be constrained to a specific set.
Syntax
enum EnumName {
value1
value2
value3
}
Examples
Order Status Enum
enum OrderStatus {
pending
processing
shipped
delivered
cancelled
refunded
}
User Roles
enum UserRole {
customer
seller
admin
support
moderator
}
Priority Levels
enum Priority {
low
medium
high
critical
}
Content Status
enum ContentStatus {
draft
review
approved
published
archived
}
interface Keyword
Define structural contracts similar to types (currently treated as aliases to types).
Syntax
interface InterfaceName {
fieldName: fieldType
}
Example
interface Identifiable {
id: string
createdAt: datetime
}
interface Addressable {
street: string
city: string
country: string
}
Complete Example
# E-commerce Product Catalog
enum ProductCategory {
electronics
clothing
books
home
toys
}
enum AvailabilityStatus {
in_stock
low_stock
out_of_stock
discontinued
}
type Price {
amount: number
currency: string
discount: number
}
type Product {
id: string
sku: string
name: string
description: string
category: ProductCategory
price: Price
stock: number
availability: AvailabilityStatus
tags: array
createdAt: datetime
updatedAt: datetime
}
type CartItem {
productId: string
quantity: number
price: Price
}
type ShoppingCart {
id: string
userId: string
items: array
total: Price
createdAt: datetime
}
Best Practices
Naming Conventions
- Use PascalCase for type and enum names:
Product,OrderStatus - Use camelCase for field names:
firstName,createdAt - Use lowercase for enum values:
pending,in_stock
Type Organization
- Group related types together in the same file
- Define enums before types that reference them
- Keep types focused - single responsibility
- Use descriptive names - avoid abbreviations
Field Types
- Choose appropriate types for data semantics
- Use enums for constrained values instead of strings
- Use datetime for timestamps, not strings
- Use custom types for complex nested structures
Example Organization
# User Management System
# Enums first
enum UserRole {
viewer
editor
admin
}
enum AccountStatus {
active
suspended
deleted
}
# Simple types
type Address {
street: string
city: string
country: string
}
# Complex types that reference others
type User {
id: string
email: string
role: UserRole
status: AccountStatus
address: Address
createdAt: datetime
}
Common Patterns
Timestamped Entities
type BaseEntity {
id: string
createdAt: datetime
updatedAt: datetime
}
Status Tracking
enum EntityStatus {
draft
active
archived
}
type StatusTrackingEntity {
id: string
status: EntityStatus
statusChangedAt: datetime
}
Metadata Pattern
type WithMetadata {
id: string
metadata: map
tags: array
}
Related Keywords
agent- Agents can work with typed datarole- Roles can have typed attributesworkflow- Workflows can reference types
Next Steps
- Learn about Agents that process typed data
- Explore Workflows with typed states
- See Complete Examples using types