---
id: CON-PFM-MTD-004
name: Custom Object
feature: FEAT-PFM-MTD-04
product_area: platform
module: metadata
revision: 1
status: draft
product_intent: confirmed
implementation_evidence: observed
source_sha:
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
definition: >-
  A custom object defines an organization’s own record category, including its properties, naming, lifecycle,
  access and optional ownership and placement.
owned_by: MOD-PFM-MTD
synonyms:
  - custom record type
  - object definition
not_to_be_confused_with:
  - A custom record is one instance of the shared object definition.
  - A contact field extends an existing category instead of introducing another.
  - Legacy table-valued fields kept grids within a contact rather than separate records.
facets:
  - name: Status
    meaning: 'Draft, active and archived definition states with distinct operations.'
    used_for: 'Separating design, use and retirement.'
  - name: Naming and numbering
    meaning: Configured properties and a prefix used to derive record names and numbers.
    used_for: Making derived record identities recognizable.
  - name: Owner
    meaning: An eligible relationship type that supplies a single owner per record.
    used_for: 'Connecting owner pages, predicates and joined queries.'
  - name: Publication
    meaning: Availability of record publication states and public-read configuration.
    used_for: Supporting controlled publication of register entries.
  - name: Placement and custom apps
    meaning: 'Optional console app and group placement, including organization-defined apps.'
    used_for: Grouping the category with relevant console work.
  - name: Staff access
    meaning: Broad record grants or object-specific role reach.
    used_for: Restricting sensitive categories to suitable staff.
  - name: Portal access
    meaning: Configured member-operation predicates and eligibility references.
    used_for: Preparing operation-specific member access.
relationships:
  - to: CON-PFM-MTD-001
    statement: Draft and active custom objects participate in the shared category description.
    provenance: test
    source: >-
      services-platform:modules/metadata/tests/integration/services/describe/describe-custom-object.integration.spec.js#names
      the object as custom, with the labels of the tenant’s row
  - to: CON-PFM-MTD-002
    statement: Custom properties use the field model and its two-hundred-property boundary.
    provenance: test
    source: >-
      services-platform:modules/metadata/tests/integration/services/persistence/custom-fields.custom-objects.integration.spec.js#refuses
      the 201st property, archived ones counted, and creates nothing
  - to: CON-PFM-MTD-005
    statement: Records require an active object for ordinary writes and remain readable after object archival.
    provenance: test
    source: >-
      services-platform:modules/custom-objects/tests/e2e/custom-object-records.e2e.spec.js#refuses every write
      of it with 409 and changes nothing
  - to: CON-PFM-MTD-006
    statement: Ownership selects an endpoint-compatible type that stays protected while referenced.
    provenance: test
    source: >-
      services-platform:modules/associations/tests/integration/services/persistence/association-types.integration.spec.js#refuses
      deactivating the type of one object, naming it by its label and what to change first
lifecycle:
  - state: draft
    meaning: The category is being designed and ordinary record creation is unavailable.
    how_it_changes: Validated activation makes it active; creation and restoration produce a draft.
  - state: active
    meaning: The category supports record work and authorized entry points.
    how_it_changes: Administrator archival retires the category.
  - state: archived
    meaning: The retained category is unavailable for ordinary writing.
    how_it_changes: Restoration produces a draft requiring activation.
acted_on_by:
  - CAP-PFM-MTD-009
  - CAP-PFM-MTD-010
  - CAP-PFM-MTD-011
  - CAP-PFM-MTD-002
visible_to:
  - ACT-PFM-007
  - ACT-PFM-008
  - ACT-PFM-009
evidence:
  - >-
    services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/custom-objects.md §1 to §11 and §25;
    docs/proposals/custom-objects/09-decisions.md; docs/milestones/PLAT-M5-custom-records.md and
    plans/PLAT-M5-plan.md; modules/custom-objects/db/custom-objects.table.ts, custom-apps.table.ts;
    services/persistence/custom-objects.ts, custom-apps.ts; services/access/record-access.ts;
    placement-apps.ts.
  - >-
    react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/configuration/custom-objects/**;
    Playwright PLAT-M5-S01, S02, S10, S13, S14.
supersedes: []
---

# Custom Object

## What It Is

A custom object lets an organization describe things that do not fit a standard record category. A club can define Boats, a regulator can define Enforcement Actions and another organization can define its own register. The object is the shared definition; each boat or action is an individual custom record.

The definition brings together properties and operational settings. It chooses how records are named and numbered, whether publication is available, who may reach records and where staff find the category. Optional ownership describes a relationship to another record rather than a separate owner value embedded in every definition.

## Why It Matters

An organization needs a coherent register rather than an assortment of unrelated additional fields. A shared object definition gives its records a common structure and lifecycle, while scoping access can keep a sensitive register within an assigned role.

Separating design from activation lets administrators prepare properties before staff start keeping records. Retained archival protects established data when a register goes out of use. Those lifecycle choices also tell consumers whether configuration or record-writing work remains available.

## How It Works

An administrator creates a draft with durable identities. Definitions are versioned, count limits include retained objects and replacement cannot bypass lifecycle operations. Properties are added through the custom-field model, with a custom-object limit that includes archived properties.

Activation validates the naming property and reports definition problems together. A suitable naming property allows record names to be derived consistently. Activation also writes query recipes; the examined archive operation contains no matching recipe-retirement call, so query cleanup is not presented as established behavior.

Ownership must use a supported active relationship type ending at the custom object. Publication cannot be disabled while published records remain. Portal configuration is checked against workspace roles and eligibility bindings, but configured predicates and delivered portal screens are distinct evidence questions.

## What It Contains

Lifecycle status, naming and numbering, ownership, publication, app placement, staff access and portal access form the object’s main facets. A record category can be useful without app placement or ownership. Placement helps people find it, while ownership supplies a relationship that other views and predicates can use.

Staff access can admit broad record grants or require object-scoped role assignments. That distinction affects both direct requests and navigation. Portal settings describe operation predicates and public publication choices without proving a completed member-facing workflow.

## What It Is Related To

The metadata catalogue lists available custom objects beside registered categories and describes fixed record information followed by their properties. Custom fields define those properties; custom records hold the resulting values. Relationship types can supply ownership and other links.

Forms and layouts use the object’s purpose. Custom apps group placed objects in the console, while scoped access determines which entries a person can open. These connections remain independent enough that an unplaced object can still be reached through related-record work.

## What Needs Deciding

The product should decide how recipe retention follows object archival and how stored per-owner limits become enforceable behavior. Reset also needs careful product treatment because retained active definitions can lose their properties and data. The findings preserve these gaps so design does not infer enforcement from a stored setting or a successful lifecycle action.