Skip to lesson

AnthropicClaude Certified Architect – Foundations2026-100 Prerequisites

Separate required fields from nullable values

Completed by the knowledge check

Learning objective

Define function-calling interfaces with JSON Schema types, required fields, and nullability.

Core idea

A function-calling interface is a contract for proposed arguments. A Claude user-defined tool carries a name, a description that says when the tool applies, and an input_schema, which Anthropic defines as a JSON Schema object.

Three questions stay separate: what type can a value have, must the property be present, and can its value be null? They are independent. A required property can accept null, and an optional property can reject null whenever it appears. Keeping them apart stops a missing argument from turning silently into a business decision.

How it works

{
  "name": "lookup_order",
  "description": "Look up an order in the authenticated customer's account before explaining refund eligibility. Does not change the order.",
  "input_schema": {
    "type": "object",
    "properties": {
      "order_id": { "type": "string" },
      "include_items": { "type": "boolean" },
      "reason": {
        "type": ["string", "null"],
        "description": "The customer's stated reason, or null if unknown."
      }
    },
    "required": ["order_id", "reason"],
    "additionalProperties": false
  }
}

lookup_order and its arguments are illustrative, not built-in tools.

Types. Use JSON Schema type names, not your implementation language’s. A JSON boolean is true, not the string "true"; an order reference that keeps its leading zeros is a string even though it contains digits.

Presence. JSON Schema’s properties describes a property when it appears; by default those properties are not required. The required array names the ones that must be present. Here order_id and reason must appear and include_items may be omitted. An object schema with properties but no required list accepts {}.

Nullability. JSON Schema has a null type, and type may be an array: ["string", "null"] accepts either, while a plain "string" rejects null. Presence is still decided by required.

ArgumentResult
order_id missing, or order_id: nullInvalid
reason missingInvalid, although it accepts null
reason: nullValid: the reason is explicitly unknown
extra refund_amountInvalid, because of additionalProperties: false

An optional nullable property therefore has three states — omitted, null, a value — and each needs a meaning before you expose it. By default JSON Schema allows properties the schema does not declare; additionalProperties: false turns an invented argument into a validation failure.

The schema describes shape only. Without strict: true, Anthropic warns that Claude might return incompatible types or omit required fields; 4.3.1 covers strict tool inputs. A valid object still does not prove the customer owns order_id, so authorization stays in the handler. Designing nullable fields and escape values so an extraction never has to invent a value is taught in 4.3.4.

Key distinctions and trade-offs

  • Declared versus required: properties constrains a value; required demands the key.
  • Null versus absent: null is a value; absence is a missing key. Neither is an empty string.
  • Valid versus authorized: a well-formed argument can still name an order the caller may not see.

Required nullable fields make “unknown” explicit at the cost of a larger payload. Optional fields keep requests compact but need a defined omission policy.

Architecture / decision scenario

The team proposes marking every field of lookup_order optional and having the handler turn missing fields into null. You require order_id as a non-null string so no lookup runs without a target, require reason as string-or-null so the model can say the reason is unknown, leave include_items optional with a documented default, and reject extras. A proposal of reason: null passes; omitting reason, sending include_items: "true" or adding refund_amount fails validation before the handler runs its ownership check.

Common exam traps

  • Assuming a property in properties is required.
  • Reading required as “not null”.
  • Equating a missing key, null and an empty string.
  • Sending string values for boolean arguments.
  • Assuming object schemas reject unknown properties by default.
  • Treating a valid argument shape as authorization.

What to remember

Types live in properties, presence in required, nullability in the type expression. Give omission and null a defined meaning, reject extras deliberately, and keep schema validation apart from authorization.

Knowledge check

References