--- id: CON-PFM-MTD-002 name: Custom Field feature: FEAT-PFM-MTD-02 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 field adds a workspace-defined value to an eligible record type, using a durable key, fixed value type and configurable presentation and validation. owned_by: MOD-PFM-MTD synonyms: - property (on a custom object) - custom field definition not_to_be_confused_with: - 'A record owner stores values, while this definition describes them.' - An application declares standard fields rather than workspace administrators. - Submission questions belong to their process’s content model. facets: - name: Key meaning: A permanent field identity whose grammar depends on the owning category. used_for: 'Maintaining references across APIs, queries, loads and templates.' - name: Data type and configuration meaning: An immutable value type with compatible settings that preserve existing data. used_for: Changing compatible settings without reinterpreting stored values. - name: Required level meaning: A requirement tier interpreted by the relevant writing channel. used_for: Applying requirements through the appropriate writing channel. - name: Field rules meaning: 'A complete set of conditional, default, uniqueness and audience settings.' used_for: 'Controlling conditions, defaults, uniqueness and readership.' - name: Place and group meaning: Ordering and grouping used to arrange generated presentations. used_for: Arranging generated forms and record presentations. - name: Archive meaning: A retained definition excluded from current use until restoration. used_for: Retiring information without destroying it. - name: Image and file fields meaning: Attachment values prepared through authorized staging and managed saving. used_for: Attaching pictures and documents to records. relationships: - to: CON-PFM-MTD-001 statement: An additional field belongs to a category permitted to support it. provenance: test source: >- services-platform:modules/metadata/tests/integration/services/registration/entity-capabilities.integration.spec.js#refuses a new custom field with the 400 problem - to: CON-PFM-MTD-004 statement: Custom-object properties use additional-field definitions with unsuffixed keys. provenance: test source: >- services-platform:modules/metadata/tests/integration/services/persistence/custom-fields.custom-objects.integration.spec.js#creates a property of an active custom object with a plain key - to: CON-PFM-MTD-005 statement: Custom-record writes validate values through their property definitions and rules. provenance: documented source: 'services-platform:docs/custom-objects.md#13. Records: the rules every write enforces' lifecycle: - state: live meaning: The definition participates in current descriptions and writes. how_it_changes: Administrator archival retires it. - state: archived meaning: Current descriptions omit the field while identity and values remain. how_it_changes: Restoration returns the definition to use. acted_on_by: - CAP-PFM-MTD-005 - CAP-PFM-MTD-006 - CAP-PFM-MTD-007 - CAP-PFM-MTD-002 visible_to: - ACT-PFM-007 - ACT-PFM-008 - ACT-PFM-009 evidence: - >- services-platform at ad3f6a6582843008ed0f5a17b131878d15829af1: docs/metadata.md ; docs/standards/custom-field-capability.md; docs/files.md; docs/assets.md; modules/metadata/db/custom-fields.table.ts, custom-field-rules.table.ts; services/persistence/custom-fields.ts; modules/files/**. - >- react-console at baf6dae382d6f41dce976c7f848667ccc37e076f: components/configuration/fields/**, components/configuration/custom-objects/object-properties-tab.tsx. supersedes: [] --- # Custom Field ## What It Is A custom field gives an organization a place to keep information that the standard record does not provide. On an existing record type it extends that category; on a custom object it is a property of the organization’s definition. The field describes a value rather than holding a particular record’s value itself. A field combines a stable identity with a value type, compatible configuration and presentation settings. Its rules can add conditional requirement, conditional visibility, uniqueness, a default or an audience restriction. Those choices remain distinguishable: a label helps a person recognize the information, while a validation rule determines whether a write is acceptable. ## Why It Matters Organizations need additional information without losing the ability to validate, search and understand it. A durable definition lets records, queries and forms refer to the same field even when administrators change its label or presentation. Protecting identity and type also prevents an administrative edit from silently reinterpreting existing values. Retirement matters as much as creation. Removing an obsolete question from current work should not destroy its stored information or allow its key to be reused for a different meaning. Archival provides that separation between current use and retained data. ## How It Works An administrator creates a field on a category that permits additional fields or on an available custom object. Platform checks the definition against its value type and rejects invalid combinations. A replacement preserves identity and type and checks whether configuration changes would narrow existing choices or precision. Rule replacement supplies the complete desired set. Omitted rule kinds are removed, and default staff exposure does not need an explicit stored rule. Conditions must use supported fields and fit the stored size boundary. Enabling uniqueness requires a checker and compatible existing data. Archival hides a field from current descriptions while retaining identity and values. Its own rules are removed. On custom objects, conditions that depend on the field can prevent archival until administrators resolve them. The registered-field path does not provide that same dependency safeguard, which remains a recorded discrepancy. ## What It Contains Identity, value type, compatible configuration, requirement level, field rules, ordering and grouping make up the definition. Attachments add a staging and save workflow: an authorized caller obtains a short-lived upload address, and the record owner prepares the managed file during saving. The staging address binds declared headers and size. Issuance is recorded, but that does not establish single-use consumption or prove that the requested field exists. Presentation settings and values also have separate lives: omitting position and group during replacement clears those settings without changing stored record values. ## What It Is Related To A record type decides whether additional fields are available. A custom object uses the same field model for its properties, and its records apply those properties and rules during writes. Forms consume descriptions and configuration; they do not become the owner of a field’s stored values. Search and query consumers can also depend on fields. Archival can request degradation and rebuilding outside the definition transaction, so completion of a definition change does not establish immediate completion of every search update. ## What Needs Deciding The product should resolve the difference between registered and custom-object dependency safeguards and define the intended boundary of field-count limits. The product should also decide what upload issuance promises beyond authorization and signing. Until those decisions are recorded, the findings preserve the implementation’s narrower behavior rather than presenting a universal guarantee.