Skip to content

Contract Extensions

This document defines Apistry-supported OpenAPI extensions (x-*).

Extensions are used to express semantics that cannot be represented using standard OpenAPI alone.

Design Principles

Extensions in Apistry: - are explicit - have well-defined scope - are enforced by the runtime where required - do not introduce hidden behavior

Unsupported extensions are ignored.

Authoring correctness is expected to be validated by tooling (linters), not duplicated at runtime.

x-context

Defines method-scoped rules for object schemas.

Supported Properties

  • required
  • prohibited

These rules apply only within the context of a specific operation.

x-primary-key

Marks a field as the primary identifier for a resource.

Rules: - must be unique - must be immutable - typically marked readOnly

x-insert and x-update (Server-Owned Fields)

The x-insert and x-update extensions define server-side value sources for server-owned fields.

They are not general mutation hooks.

x-query

Marks a field as queryable.

Rules: - only fields explicitly marked queryable may be filtered - prevents accidental full-document scanning

x-query-pattern

Defines how a field supports wildcard matching.

Examples: - prefix - suffix - contains

If omitted, wildcard queries are rejected.

x-soft-delete

Enables soft delete semantics for a resource.

Requirements: - a boolean or timestamp field must be designated - delete operations update the field instead of removing the record - query behavior must explicitly include or exclude soft-deleted records

Soft delete is opt-in and explicit.

Uniqueness rules (additive)

  • uniqueItems: true is the only schema-level mechanism Apistry uses to enforce uniqueness in arrays.
  • If uniqueItems is absent (or false), duplicates are allowed for primitive arrays.
  • For object arrays, Apistry does not infer duplicates without explicit alternate-key modeling.
  • Top-level uniqueness is typically enforced via database indexes (outside Apistry).

Soft delete on sub-resources (hard rule)

x-soft-delete MUST NOT be applied to sub-resources. Soft delete applies only to top-level resources (collections).

Applicability

  • x-insert and x-update are intended to be used only on fields marked readOnly: true
  • If applied to fields without readOnly: true, the extensions have no runtime effect

Such usage is considered an authoring error and should be flagged by a contract linter.

Lifecycle Semantics

  • x-insert is evaluated during resource creation (POST)
  • x-update is evaluated during resource updates (PATCH)
  • Values are generated after request validation and before persistence
  • Generated values apply only to server-owned (readOnly) fields

Client Interaction

  • If a client supplies a value for a field marked readOnly: true:
    • the value is removed from the incoming payload
    • the value is ignored
    • request processing continues

This prevents clients from influencing server-owned fields while preserving predictable runtime behavior.

Runtime vs Linting Responsibilities

Runtime behavior - ignores misplaced x-insert / x-update - strips client-supplied values for readOnly fields - applies server-generated values deterministically

Linting (future-provided) - flags x-insert / x-update on non-readOnly fields - flags malformed or missing server-owned field definitions - enforces authoring discipline prior to server startup

Apistry intentionally avoids duplicating linter logic at runtime.

Extension Enforcement

Extensions are: - validated at startup for structural correctness - ignored if unsupported - enforced consistently across operations where applicable

Invalid extension usage that affects runtime safety prevents server startup.

Summary

  • Extensions express intent, not logic
  • Server-owned fields are explicit
  • Misuse is ignored at runtime and flagged by linters
  • Behavior is deterministic and non-magical
  • Extensions never bypass lifecycle rules