--- id: SVC-PFM-MTD-metadata title: Metadata Service Module product_area: platform module: metadata repository: services-platform source_module: modules/metadata revision: 1 status: draft design_intent: confirmed origin: services-platform:docs/metadata.md (final acceptance 2026-10-08); R2-ARCH-001 v1.0 (Andrew, 2026-10-19) and PLAT-M9 (Product Accepted 2026-10-19); R2-ARCH-002 v2.0 (Andrew, 2026-10-22) for the publication column implementation_evidence: observed inference: [] source_sha: services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1 react-console: baf6dae382d6f41dce976c7f848667ccc37e076f owns: - DOM-PFM-MTD-001 - DOM-PFM-MTD-002 does_not_own: - Native applications own their custom-property value rows. - Custom Objects owns local register entries and values. - Quick Search owns index configuration and rebuild execution. - The Data Job Engine serves and orchestrates field-load jobs. - Security supplies permission evaluation and role policy. operations: - operation_id: getMetadataHealth intent: Return the metadata build identity and health response. access: public permission: 'none: the shared health route (generated by the health-route factory as getHealth)' realises: [] published_to_submissions: 'not published: Operational health checks have no intake binding.' - operation_id: registerApplication intent: Apply an owner deployment’s complete record manifest, retaining omitted declarations as retired. access: internal permission: 'none: IAM invocation of platform_metadata_registration by an owner''s deploy role' realises: - CAP-PFM-MTD-001 - CAP-PFM-MTD-003 published_to_submissions: 'not published: Internal service collaboration has no Submissions entry point.' - operation_id: listFieldTypes intent: Return supported value types, display options and their compatibility. access: console permission: platform.metadata.read realises: - CAP-PFM-MTD-002 published_to_submissions: 'not published: This read has no Submissions binding.' - operation_id: listObjects intent: Return registered categories and local draft or active custom objects, optionally limited by capability. access: console permission: platform.metadata.read realises: - CAP-PFM-MTD-002 - CAP-PFM-MTD-003 published_to_submissions: 'not published: This read has no Submissions binding.' - operation_id: describeObject intent: Assemble the workspace’s current field and collection contract, incorporating local labels, properties and rules. access: console permission: platform.metadata.read realises: - CAP-PFM-MTD-002 - CAP-PFM-MTD-003 - CAP-PFM-MTD-004 published_to_submissions: 'not published: This read has no Submissions binding.' - operation_id: listCustomFields intent: Return local definitions for a category, with archived fields included only when requested. access: console permission: platform.custom-fields.read realises: - CAP-PFM-MTD-005 published_to_submissions: 'not published: This read has no Submissions binding.' - operation_id: createCustomField intent: Add a property definition to a category that permits custom fields. access: console permission: platform.custom-fields.create realises: - CAP-PFM-MTD-005 - CAP-PFM-MTD-003 published_to_submissions: 'not published: These configuration changes have no Submissions binding.' - operation_id: getCustomField intent: Return the selected local property definition. access: console permission: platform.custom-fields.read realises: - CAP-PFM-MTD-005 published_to_submissions: 'not published: This read has no Submissions binding.' - operation_id: updateCustomField intent: Replace mutable field settings at the loaded version while preserving its key, type and accepted value range. access: console permission: platform.custom-fields.update realises: - CAP-PFM-MTD-005 - CAP-PFM-MTD-003 published_to_submissions: 'not published: These configuration changes have no Submissions binding.' - operation_id: archiveCustomField intent: Retire current field use with rule removal and affected search-degradation requests. access: console permission: platform.custom-fields.delete realises: - CAP-PFM-MTD-005 - CAP-PFM-MTD-006 published_to_submissions: 'not published: These configuration changes have no Submissions binding.' - operation_id: restoreCustomField intent: Reopen a retained field under a currently eligible category, without restoring its removed rules. access: console permission: platform.custom-fields.delete realises: - CAP-PFM-MTD-005 published_to_submissions: 'not published: These configuration changes have no Submissions binding.' - operation_id: getCustomFieldRules intent: Return the complete rules and the default staff audience when no exposure is stored. access: console permission: platform.custom-fields.read realises: - CAP-PFM-MTD-006 published_to_submissions: 'not published: This read has no Submissions binding.' - operation_id: setCustomFieldRules intent: Save a complete validated rule set and rebuild value reservations when uniqueness is enabled. access: console permission: platform.custom-fields.update realises: - CAP-PFM-MTD-006 published_to_submissions: 'not published: These configuration changes have no Submissions binding.' - operation_id: setFieldLabel intent: Save the workspace’s presentation label for a live standard field. access: console permission: platform.field-labels.update realises: - CAP-PFM-MTD-004 published_to_submissions: 'not published: These configuration changes have no Submissions binding.' - operation_id: removeFieldLabel intent: Discard a local override so descriptions use the owner’s declared label. access: console permission: platform.field-labels.update realises: - CAP-PFM-MTD-004 published_to_submissions: 'not published: These configuration changes have no Submissions binding.' events: [] jobs: - name: Quick Search degradation after registration kind: After registration commits, degrade affected workspaces sequentially with at most one hundred rebuild starts. owner: Quick Search (called in process) - name: Quick Search rebuild after field archival kind: Start requested Step Functions search work after the field archive transaction. owner: Quick Search (called in process) integrations: - system: Owning macroservices' deploys (CRM first) direction: inbound contract: Owner deployment sends the shared metadata manifest by synchronous IAM invocation and receives acceptance details or refusal problems. - system: Owning macroservices' record writes direction: outbound contract: Record owners consume definition read interfaces inside their transaction and apply typed conversion and API-required validation. consistency: - rule: Application registration applies or rolls back the complete manifest. kind: transactional compensation: Rollback retains the preceding registration. - rule: Search rebuilding eventually removes indexed values of retired declarations. kind: eventual compensation: No compensation runs; failed or skipped workspaces require another rebuild. - rule: Field archival commits with its own rule removal and index-degradation records. kind: transactional compensation: Transaction rollback reverses all these records. - rule: A completed search rebuild excludes archived-field content. kind: eventual compensation: A failed post-commit start can leave a never-started job and the archived field unchanged; another rebuild is required. - rule: Unique-rule enabling and value-reservation rebuilding commit together. kind: transactional compensation: Failed duplicate validation preserves existing rules and reservations. - rule: Rule writes update the workspace’s query-description stamp atomically. kind: transactional compensation: A refused transaction applies neither rule nor stamp. evidence: - 'services-platform at ad3f6a65: modules/metadata/aws/api/metadata.routes.ts, metadata.schemas.ts, metadata-api-mapper.ts; aws/lambda/API.handler.ts, REGISTRATION.handler.ts; aws/logic/*.lambda.ts; services/**; capabilities/**; db/**; aws/platform.service.ts (METADATA_PERMISSIONS, CUSTOM_FIELDS_PERMISSIONS, FIELD_LABELS_PERMISSIONS); docs/metadata.md; docs/standards/custom-field-capability.md; docs/standards/submission-compatible-operations.md' - '@rhythmsoftware/macroservice-http 0.19.0 dist/health-route.js (the generated health operation name)' controls: [TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-CHG-001, TC-CHG-002, TC-CHG-003, TC-CHG-004, TC-CHG-005, TC-CHG-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-IAM-006, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-TEN-004, TC-VEN-001, TC-VEN-002, TC-VEN-003] --- # Metadata Service Module ## What This Service Is For Metadata provides a workspace-specific record description to forms, screens, queries and record owners. It stores registered declarations, local property definitions and rules, and standard-field label overrides. ## Boundary Record owners retain values and enforce their write obligations. Metadata reads capability declarations and checks the approved classification; Layouts, Custom Objects, Quick Search and Security retain their separate responsibilities. ## Operations in Words Deployment registration refreshes the catalogue. Read operations assemble type and field descriptions; configuration operations maintain properties, rules and local labels. The service has no published Submissions binding, and operation rows state the reason. ## Events and Jobs Metadata produces no business event. Retirement requests search degradation and rebuild work from Quick Search, whose job implementation is outside definition persistence. ## Consistency Guarantees Registration and individual resource writes are transactional. Definition and rule editor calls remain separate, whereas archival includes rule deletion and search-degradation records. Updating search documents follows commit and can fail independently.