Contracts — Aquilia Documentation
Comprehensive guide and documentation for Contracts in the Aquilia framework. View API reference, examples, and implementation patterns.
import useTheme from '../../../context/ThemeContext' import CodeBlock from '../../../components/CodeBlock' import Link from 'react-router-dom' import ArrowRight, Layers, Database, Shield, GitBranch, Eye, FileCheck from 'lucide-react' import NextSteps from '../../../components/NextSteps' export function ContractsOverview() const theme = useTheme() const isDark = theme === 'dark' const boxClass = `p-6 rounded-2xl border $ isDark ? 'bg-[#0A0A0A] border-white/10' : 'bg-white border-gray-200' ` return ( Data Layer / Contracts Contracts Contracts are Aquilia's first-class data contract system. They declare the exact shape of data flowing between your Models and the outside world — handling inbound validation, outbound serialization, relational views, projections, OpenAPI schema generation, and deep integration with DI, auth, and sessions. /* Philosophy */ Philosophy Unlike traditional serializers that treat validation and serialization as separate concerns, Contracts unify the entire data lifecycle into a single, declarative contract. Every Contract defines: [ icon: , title: 'Cast', desc: 'Inbound type coercion — raw JSON values become typed Python objects' , icon: , title: 'Seal', desc: 'Validation pipeline — field-level, cross-field, and async validation' , icon: , title: 'Imprint', desc: 'Write-back — validated data writes directly to Model instances' , icon: , title: 'Mold', desc: 'Outbound shaping — Model data transforms for API responses' , icon: , title: 'Lens', desc: 'Relational views — depth-controlled nested relationship rendering' , icon: , title: 'Projection', desc: 'Named field subsets — different views of the same data' , ].map((item, i) => ( item.icon item.title item.desc )) /* Contract Architecture Diagram */ Contract Lifecycle /* Terminology */ Terminology Term Description [ term: 'Contract', desc: 'A declarative data contract bound to a Model (or standalone)' , term: 'Facet', desc: 'A field-level primitive — the atomic unit of a Contract (like TextFacet, IntFacet)' , term: 'Cast', desc: 'Inbound type coercion (str → int, ISO string → datetime, etc.)' , term: 'Seal', desc: 'Validation — field-level constraints, cross-field rules, async checks' , term: 'Imprint', desc: 'Write validated data onto a Model instance (create or update)' , term: 'Mold', desc: 'Outbound transformation — shape data for API response' , term: 'Lens', desc: 'A Facet that renders a related object through another Contract' , term: 'Projection', desc: 'A named subset of fields — different views of the same Contract' , term: 'Spec', desc: 'Inner class (like Meta) that configures model binding, field selection, projections' , ].map((row, i) => ( row.term row.desc )) /* Quick Start */ Quick Start Define a Contract with explicit Facet declarations or use type annotations with the Field descriptor. Style 1: Explicit Facets item.desc )) )
Go to Homepage