Published Updated

Treat a document metadata change as a release of a shared data contract. Identify the applications that write and read the field, introduce the replacement alongside the existing representation, migrate the affected records, and verify each consumer before retiring the old field.
Consider a field called vendor that contains supplier names. Replacing it with supplierId changes both the key and the meaning: a name must now resolve to a particular account in the ERP. Search filters, routing rules, access policies, reports, and exports may all depend on the earlier representation. An upload succeeding tells you little about whether those consumers still work.
Write down the business fact, owner, scope, data type, cardinality, allowed values, and treatment of missing or unknown data. Include whether a value is current reference data or a fact captured when the document was issued. A supplier's current display name and the name printed on an older invoice may both be useful; give them distinct meanings.
A contract includes the behaviour consumers rely on. Google's API compatibility guidance distinguishes source, wire, and semantic compatibility, and treats a rename as removal plus addition. Apply that reasoning to your own document integrations: the same JSON type can still carry a different business fact.
FormKiQ v1.19.2 also supports JSON attributes with nested-field predicates. Moving flat fields into a structured object changes the contract for existing consumers. Test the JSON paths and missing values explicitly. DynamoDB filters those properties after reading candidates; selected Enhanced Search capabilities index JSON in OpenSearch. Storing an object does not create a DynamoDB index for every nested property.
Keep a release record with the old and new definitions, affected sites or classifications, migration scope, owners, and acceptance criteria. A label such as “contract version 2” can identify this application agreement; it should not imply that every connected system automatically versions or migrates its schemas. For schema fundamentals, see document schemas and metadata validation.
| Proposed change | What to establish before rollout |
|---|---|
| Add an optional field | Check that writers may send it and readers tolerate its presence or absence. Keep existing behaviour for documents without a value. |
| Make a field required | Update active producers and resolve in-scope historical gaps before enforcing the rule. Define exceptions without inventing misleading default values. |
| Rename or split a field | Introduce the replacement, choose an authoritative writer and compatibility behaviour, migrate values, and obtain consumer acceptance before retirement. |
| Change a type or allowed values | Define explicit conversion and handling for rejected values. Check parsers, filters, routing, and reports against the proposed representation. |
| Change the business meaning | Use a distinct field or explicitly versioned contract. Preserve the earlier fact and explain how the new value was determined. |
Adding a field is a useful first step, but compatibility depends on the consumers. A strict schema may reject an unexpected key; a report may treat a missing identifier differently from an empty string. Include these behaviours in the acceptance tests.
Trace the field through intake forms, APIs, extraction mappings, administrator edits, rules, search filters, access decisions, scheduled reports, exports, and event payloads. Assign an owner to each dependency. Include infrequent jobs and older documents that appear only during a renewal, audit, or recovery operation.
Search needs its own check: a field can be written correctly while a saved query still uses the old key or an index has incomplete coverage. Record the affected query patterns and how their result identities will be compared. The composite-key and OpenSearch guide explains why query design belongs in that inventory.
Permit the new representation while supporting agreed existing writers and readers. Document precedence and reject conflicting inputs.
Convert historical values in controlled batches, resolve exceptions, update integrations, and compare results on mixed records.
Confirm consumer adoption and migration outcomes, end legacy writes, and approve the remaining retention or removal of old metadata.
Choose one component to own each business fact. If compatibility requires two representations, define how that owner derives and updates them. Two independent writers can produce conflicting values. Record failed updates and reconcile them before treating a document as migrated.
Set an intended transition window, then use evidence to close it. A calendar deadline alone cannot show that an old client has stopped sending the previous key. Measure old-key writes and reads where observable, inspect scheduled consumers, and obtain the owners' acceptance.
This fictional migration covers 12,000 supplier documents. The old vendor attribute contains free-form names. The new contract uses supplierId for the ERP account and supplierName for a defined display value. The names and counts below illustrate the process, not a reported migration result or performance target.
The ERP owns supplier identity. The integration resolves a legacy name using approved account data and business-unit context. “Cedar Supply” is ambiguous when it could identify two accounts. Those records enter a review queue instead of receiving a guessed identifier.
Allow the replacement fields before new producers send them. The configured integration looks up the ERP account and writes the selected identifier and display value. A legacy export keeps its documented name-based response during transition. Conflicting old/new inputs are rejected for correction under the agreed rule.
An initial pass resolves 11,400 documents, leaves 450 ambiguous matches, and identifies 150 with insufficient source data. The migration records document identity, earlier value, selected account, conversion-rule version, time, and result. It uses a controlled write window or supported concurrency check so a batch cannot silently overwrite a newer correction.
The initial totals account for all 12,000 documents, but 600 still need a decision. Reviewers resolve or explicitly exclude those cases under the migration scope. The team then tests search, routing, access, reports, and ERP exports on old, migrated, newly created, and corrected documents. Comparing returned document IDs catches errors that equal result counts would hide.
After the named consumers adopt the identifier and new writes conform, the owner ends legacy writes and retires the compatibility response. The release record preserves the earlier definition and conversion decisions. Original invoice content remains historical evidence; any removal of old metadata follows the applicable record policy and scope.
A fallback search can sometimes improve availability during migration, but an access rule needs an explicit authorisation decision. Test the intended allowed and denied document sets for missing, ambiguous, and conflicting values. Avoid turning “unknown supplier” into broad access or combining old and new rules in a way that expands permissions unexpectedly.
Keep a recovery path that can handle data already written under the new contract. Reverting application code alone may leave new values that an older consumer cannot interpret. Preserve the earlier representation where permitted, define reverse conversion only where it is meaningful, and plan forward repair for lossy or ambiguous transformations.
Before retrying a failed batch, identify which documents changed successfully and which changed again afterward. A repeatable migration should recognise completed work and route conflicts for review. Retain enough change evidence to explain the outcome without copying unnecessary sensitive values into general logs.
A metadata release is complete when the intended values are reconciled, important consumers use the agreed contract, and exceptions have an accountable outcome. Keep definitions, migration evidence, and recovery decisions together so the next field change can build on a known state.
The open-source foundation — API-first, deployable into your own AWS account, and free to use. Right for architecture validation and early implementation.
Production-ready editions for departments and complex workflows. Start with a Proof-of-Value deployment or go straight to production.
For governance-heavy environments with residency, sovereignty, assurance, and multi-jurisdiction requirements. Talk to us about the right deployment model.