openapi: 3.1.0
info:
  title: Filament Table State Standardization Contract
  version: 1.0.0
  description: |
    Page-level contract for standardized Filament list surfaces affected by Spec 125.
    This feature does not add public APIs. It formalizes the expected query-state
    parameters and page behaviors for resource, tenant-scoped, and system-scoped
    list surfaces that use native Filament tables.
paths:
  /admin/{listSlug}:
    get:
      summary: Render a standardized workspace-scoped Filament list surface
      operationId: getWorkspaceScopedListSurface
      tags:
        - Filament Table UX
      parameters:
        - $ref: '#/components/parameters/ListSlug'
        - $ref: '#/components/parameters/TableSearch'
        - $ref: '#/components/parameters/TableSortColumn'
        - $ref: '#/components/parameters/TableSortDirection'
        - $ref: '#/components/parameters/TableRecordsPerPage'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Standardized list page rendered successfully
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Actor is a member of the scope but lacks the required capability for the page or exposed action
        '404':
          description: Workspace scope is unavailable or the actor is not entitled to the requested scope
  /admin/t/{tenant}/{listSlug}:
    get:
      summary: Render a standardized tenant-scoped Filament list surface
      operationId: getTenantScopedListSurface
      tags:
        - Filament Table UX
      parameters:
        - name: tenant
          in: path
          required: true
          description: Tenant identifier resolved by the existing Filament tenant route binding
          schema:
            type: string
        - $ref: '#/components/parameters/ListSlug'
        - $ref: '#/components/parameters/TableSearch'
        - $ref: '#/components/parameters/TableSortColumn'
        - $ref: '#/components/parameters/TableSortDirection'
        - $ref: '#/components/parameters/TableRecordsPerPage'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Standardized tenant-scoped list page rendered successfully
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Tenant member lacks the capability required for the page or exposed action
        '404':
          description: Tenant or workspace context is unavailable or the actor is not entitled to the tenant scope
  /system/{listSlug}:
    get:
      summary: Render a standardized platform-scoped Filament list surface
      operationId: getSystemScopedListSurface
      tags:
        - Filament Table UX
      parameters:
        - $ref: '#/components/parameters/ListSlug'
        - $ref: '#/components/parameters/TableSearch'
        - $ref: '#/components/parameters/TableSortColumn'
        - $ref: '#/components/parameters/TableSortDirection'
        - $ref: '#/components/parameters/TableRecordsPerPage'
        - $ref: '#/components/parameters/Page'
      responses:
        '200':
          description: Standardized platform list page rendered successfully
          content:
            text/html:
              schema:
                type: string
        '403':
          description: Platform user lacks the capability required for the page or exposed action
        '404':
          description: The actor is not entitled to the platform scope
components:
  parameters:
    ListSlug:
      name: listSlug
      in: path
      required: true
      description: |
        Logical list-surface identifier. Examples include resource list pages,
        system directory tables, operations pages, or custom picker tables.
      schema:
        type: string
    TableSearch:
      name: tableSearch
      in: query
      required: false
      description: Free-text search across the table's approved searchable fields
      schema:
        type: string
    TableSortColumn:
      name: tableSortColumn
      in: query
      required: false
      description: Active sortable column for the table surface
      schema:
        type: string
    TableSortDirection:
      name: tableSortDirection
      in: query
      required: false
      description: Active table sort direction
      schema:
        type: string
        enum:
          - asc
          - desc
    TableRecordsPerPage:
      name: tableRecordsPerPage
      in: query
      required: false
      description: Selected page-size option from the surface's pagination profile
      schema:
        oneOf:
          - type: integer
            minimum: 5
          - type: string
            enum:
              - all
    Page:
      name: page
      in: query
      required: false
      description: Current paginator page for the table surface
      schema:
        type: integer
        minimum: 1
  schemas:
    StandardizedTableBehavior:
      type: object
      required:
        - defaultSort
        - emptyState
        - paginationProfile
      properties:
        defaultSort:
          type: object
          properties:
            column:
              type: string
            direction:
              type: string
              enum:
                - asc
                - desc
        persistence:
          type: object
          properties:
            search:
              type: boolean
            sort:
              type: boolean
            filters:
              type: boolean
        emptyState:
          type: object
          required:
            - heading
            - description
          properties:
            heading:
              type: string
            description:
              type: string
            hasAuthorizedAction:
              type: boolean
        paginationProfile:
          type: string
          enum:
            - resource
            - relation_manager
            - widget
            - picker
            - custom_page