Data Backend

Import into amplify/backend.ts:

Export Schema as ClientSchema<typeof schema> — without this export, frontend clients lose all type inference. Field types: a.string(), a.integer(), a.float(), a.boolean(), a.date(), a.datetime(), a.timestamp(), a.time(), a.email(), a.url(), a.phone(), a.ipAddress(), a.json(), a.id(), a.enum([...]). Chain .required() or .array() on any field; .default(value) on scalar fields only (not enums — see Pitfalls).

a.phone(): Only accepts E.164 format (+15551234567). Hyphens (+1-555-0101) and short formats are rejected.

Date/Time Field Formats

Pitfall: a.timestamp() is seconds, not milliseconds. Use Math.floor(Date.now() / 1000) when setting values from JavaScript.

Custom Identifiers

.identifier(['sku']) replaces the auto-generated id field entirely:

• All queries must use the custom identifier ({ sku: 'ABC123' })
• Duplicate values cause DynamoDB conditional check error
• The id field no longer exists on this model

Authorization Rules

Six strategies, applied per-model or per-field:

WARNING: In data authorization rules, allow.guest() is a method call (with parentheses). In storage access rules, allow.guest is a property (no parentheses). Mixing these up causes TypeScript errors.

Security note: allow.guest() and allow.publicApiKey() both permit unauthenticated access. Only use for intentionally public, non-sensitive data. Prefer allow.authenticated() or allow.owner() for sensitive resources. See Amplify authorization best practices (opens in a new tab) and Amazon Cognito Identity Pool security (opens in a new tab) for guidance on choosing the right authorization strategy.

Per-field authorization overrides model-level rules:

Multi-owner: Use allow.ownersDefinedIn('editors') with an editors: a.string().array() field to grant multiple users ownership. Dynamic groups: Use allow.groupsDefinedIn('teamGroups') with a string field to control access via group names stored on each record.

Authorization Rule Combining

When multiple rules are applied, the most permissive wins. You cannot use deny rules — if allow.authenticated() grants full CRUD, you cannot selectively deny delete for non-owners. Structure rules from most restrictive:

Pitfall: groupsDefinedIn('fieldName') automatically creates an implicit field on the model. Do NOT also declare that field explicitly — this causes: "Implicit field conflicts with explicit field definition."

Type system gap: The implicit field from groupsDefinedIn('fieldName') is NOT exposed in generated TypeScript client types. To set the field programmatically, use an untyped approach:

typescriptCopy

await client.graphql({
  query: mutations.updateProject,
  variables: { id: projectId, teamGroups: ['Admins', 'Editors'] },
});

Relationships

Three types — reference field types must match the related model’s identifier type.

Foreign key fields must use a.id(), not a.string(). Using a.string() causes silent relationship resolution failures.

The second argument to hasMany/belongsTo/hasOne is the foreign key field name. That field must be declared explicitly on the child model.

Declare both sides of every relationship — the parent model needs a.hasMany('Child', 'fkField') AND the child model needs a.belongsTo('Parent', 'fkField'). Omitting either side causes silent query failures (e.g., lazy-loading the relation returns undefined).

Deletion Behavior — No Referential Integrity

Deleting a parent record does NOT cascade to children and does NOT fail. Child records become orphaned silently — manually delete children first or implement a soft-delete pattern.

Self-Referential Models (Tree Structures)

Requires explicit FK field (parentId: a.id()). Works for trees, org charts, threaded comments.

Secondary Indexes

Indexes enable client.models.Todo.listByStatus({ status: 'active' }). Composite sort keys allow multi-field sorting within a partition. You SHOULD name the queryField descriptively — it becomes the typed client method name.

Enum Types

Define enums with a.enum() at the top level of a.schema(), then reference them in model fields with a.ref():

You can also use a.enum() inline on a model field:

⚠️ Pitfall: .default() does not work on a.enum() fields — default values are only supported on scalar types (a.string(), a.integer(), etc.). Applying .default() to an enum field silently fails at deployment.

.required() on enums: a.enum(['A','B']).required() does NOT work — .required() doesn’t exist on EnumType. Define the enum separately and use a.ref():

typescriptCopy

const Priority = a.enum(['low', 'medium', 'high']);
const schema = a.schema({
  Todo: a.model({
    priority: a.ref('Priority').required(), // ✅ Works
    // priority: Priority.required(),       // ❌ Fails
  })
});

Custom Types

Custom types group related fields into a reusable structure:

Use a.ref('TypeName') to reference custom types or enums in model fields.

Custom Queries and Mutations

Expose Lambda-backed operations through the schema:

The handler function name must match a defineFunction name imported into backend.ts.

Authorization Modes

Configure default and additional auth modes in defineData:

Starter template default (public access):

With auth (user-scoped access):

The defaultAuthorizationMode must match at least one strategy used in your model authorization() rules (e.g., userPool ↔ owner() / authenticated() / group(); apiKey ↔ publicApiKey(); iam ↔ guest()).

Guest access is enabled by default in Amplify Gen2 — see auth-backend.md for details and how to disable it.

Guest access configuration: see auth-backend.md § Guest Access.

Pitfalls

• Missing ClientSchema export: Without export type Schema = ClientSchema<typeof schema>, frontend generateClient<Schema>() has no type information and all operations are untyped.
• Auth mode conflict: Using allow.publicApiKey() in model rules but setting defaultAuthorizationMode: 'userPool' without adding apiKeyAuthorizationMode causes API key requests to be rejected.
• Per-field auth + .required(): Fields with owner-only authorization (allow.owner()) cannot be .required() — other users can’t provide a value on create. Make private fields optional.

Links

• Data Overview (opens in a new tab)
• Set Up Data (opens in a new tab)
• Data Modeling (opens in a new tab)
• Data Modeling — Relationships (opens in a new tab)
• Data Modeling — Add Fields (opens in a new tab)
• Customize Authorization (opens in a new tab)
• Connect to Existing Data Sources (opens in a new tab)