Configuration

Representations configure root keys, metadata, abstract declarations, and adapter options.

Metadata

Documentation for export generation is added with metadata:

class InvoiceRepresentation < Apiwork::Representation::Base
  description "A customer invoice with line items and payment tracking"
  example { id: 1, number: "INV-2024-001", status: "sent" }
end

Method	Purpose
description	Human-readable text shown in OpenAPI, TypeScript, and Zod exports
example	Example value shown in generated exports

These appear on the generated response type for this representation.

Deprecation

deprecated! marks a representation as deprecated:

class LegacyInvoiceRepresentation < Apiwork::Representation::Base
  deprecated!
end

The representation and its generated types are marked as deprecated in all exports. Deprecated representations continue to function at runtime.

Abstract Representations

abstract! marks a representation as abstract when it should not be used directly:

class ApplicationRepresentation < Apiwork::Representation::Base
  abstract!
end

class InvoiceRepresentation < ApplicationRepresentation
  attribute :id
  attribute :number
end

Abstract representations are not registered with the adapter and do not generate types. They exist as base classes for shared configuration.

Apiwork also marks representations as abstract automatically when they serve as the base class in a Single Table Inheritance hierarchy.

Root Key

By default, representations detect the JSON root key from the model name:

class PostRepresentation < Apiwork::Representation::Base
  model Post
end

# Response: { "post": {...} } or { "posts": [...] }

Custom keys override the default:

class PostRepresentation < Apiwork::Representation::Base
  root :article
  # Response: { "article": {...} } or { "articles": [...] }
end

Both singular and plural can be specified:

class PersonRepresentation < Apiwork::Representation::Base
  root :person, :people
end

Adapter Configuration

Adapters may provide configuration options that can be set at the API or representation level. Representations can override API-level adapter settings.

class ActivityRepresentation < Apiwork::Representation::Base
  adapter do
    # Adapter-specific options
  end
end

Settings resolve in this order (first defined wins):

1. Representation adapter block — most specific
2. API definition adapter block — API-wide defaults
3. Adapter defaults — built-in fallbacks

If using the Standard Adapter, pagination strategies are configured with the adapter block. See pagination for available options.

See also

• Representation::Base reference — all representation methods and options