AI disclosure: Drafted with AI assistance for Apiary. The library consortium, vendor files, and operational traces are synthetic, not production incidents.
A fictional network of tool libraries imports a nightly exchange file that describes which equipment is ready to lend. One sending library upgrades its exporter. It now marks certain workbenches as available only with a surface protector. The receiver has never heard of that field and reads the rest of the document. Its dashboard shows an extra workbench available, but nobody at that branch knows about the restriction. The JSON was readable. The catalog update was wrong. A different developer fixes this by rejecting the unsupported file, but writes only “invalid import” to a console that rotates overnight. Now the data isn't corrupted, yet the next morning the receiving branch still can't tell the sending branch which file failed or how to try again.
Rejecting unsupported input is only half a product decision. The other half is to make the rejection recoverable. A receiving service can produce a durable record stating what it received, which contract it could apply, what state it changed, and what someone should do next without storing every potentially sensitive detail everywhere. This is a guide to that record and how to work it, not to naming versions or negotiating versions generally.
Put the receipt before the dashboard badge
An intake dashboard tends to show one of three words: success, warning, or failure. Those can be useful summaries once people know what each word means. A receipt can establish the meaning. In the library example the receipt identifies the intake batch, the sending organization using an internal label, the format number the request declared, the specific supported set checked at that time, and an outcome of rejected before any catalog update. If the sender needs clarification, the receiving team can give them one stable reference. If the receiver later supports that format, a new run can link to the first receipt without editing yesterday's facts.
The first durable key should identify a specific intake event without having to examine its contents. A file name is often poor evidence. Suppliers can reuse weekly-catalog.json all year, case and path handling varies by storage system, and human operators sometimes change names for clarity. Use an intake identifier generated by your system. A checksum can be useful alongside it when you have a reliable copy of the exact input bytes, but a checksum of raw files is not a comparison of their business meaning. Add a space to JSON and you can get a different checksum with the same logical records. Conversely, two sides can agree they have the exact same bytes and still disagree about what they are permitted to do with an unfamiliar element.
The recipient should see how far processing went. “Received” need not mean “validated.” “Recognized format” need not mean “business rules passed.” “Validated” need not mean “applied.” The minimum receipt includes an explicit statement about application to the destination. Some systems process all rows together; others intentionally accept some rows and reject others. Both can be legitimate. Both are harder to operate when they reuse a single status message without listing the scope of the commit. If the importer is all-or-nothing, “0 of 284 rows applied” is a good line only if it can be derived from actual commit behavior. Do not fill it in because no success notification appeared.
When a worker is still handling the file, mark the attempt pending instead of guessing whether the next step will pass. When it is interrupted after writing, record an unknown outcome until reconciliation, not a rejection. An ingest ledger can and often should outlive a worker process that writes console messages. Treat the dashboard like the front door to those receipts, not a substitute for durable evidence.
Separate acknowledgment from eligibility and from applied state
When a file is copied to the intake bucket, the receiving service may know only that a particular object was observed and persisted in that location. Later stages turn the bytes into a parsed representation, validate the named contract, evaluate destination-specific rules and make a controlled change. Not every importer does those in distinct workers, but the evidence is different at each gate. If the UI says “received” after the copy, leave it at that. Don't let an ordinary transport receipt imply the destination now shows new results.
Design a record to handle skipped stages. When an importer rejects an unsupported declared format, it may not be able to say how many records were valid. A line “row count: 0” could be read as either a truly empty file or no parsed records observed, so explicitly say “row-level validation not reached.” A legitimate zero-result field deserves its own place. This distinction is particularly useful if a business alarm counts zero as an empty delivery. Neither alarm nor dashboard should learn that the file had no content when the only evidence is that format selection stopped it.
An application can know the validator succeeded yet hold publication for a separate reason. The file might use an identity namespace the local branch hasn't agreed to recognize, or it may be structurally valid but too old for the original update request. Record the next review separately from schema results. “Eligible for review; no changes applied” captures meaningful progress without asking someone to trust the last green indicator on the screen. Then attach the actual destination outcome once confirmed under the publication contract. If authorship or source authority matters, a structurally valid and correctly parsed record still needs to meet those separate requirements through the approved process.
Make the plain-language message precise enough for a sender to use. “Your latest upload was unsuccessful” may be all the application can say from a generic alert, but a next-step view can distinguish which artifact was observed and whether sharing a new version would help. If there are multiple files from the same sender, the exact attempt reference matters more than a filename truncated in the UI. To a customer, the last number is helpful only when somebody else can use it to identify the same event. Keep that retrieval route verifiable and limited to those permitted to see details.
Separate strict records from intentional extension points
Not every unknown field should be fatal. An optional UI color preference can carry less weight than new instructions about whether an item can be lent. That's why the decision can belong to a particular record or nested block, not a universal slogan such as “always ignore extras” or “reject every new property.” Deliberate extension points are useful where a producer needs room to attach data. They should be recognizable as extension points to readers of the contract and not interpreted as a new instruction to alter core state. A block like displayHints can tolerate named hints a particular renderer does not consume. A core allocation record should not silently accept additional fields that can change whether and when equipment is treated as lendable.
The JSON Schema object guide documents the distinction between naming known properties and controlling additional properties. Defining a list of properties does not on its own make an object closed. You can also design a schema that allows extra properties of a constrained kind. Composition can complicate closure: what counts as additional within a subschema can differ from what developers imagine when looking at the whole object, so check how closure works under your selected dialect. The 2020-12 JSON Schema core specification is a useful primary reference when checking applicators and evaluation. Test actual validator behavior with your real schema fragments instead of assuming two validator configurations interpret your intention alike.
Keep the schema dialect separate from the format version used in an exchange. The schema dialect says how to interpret the validation rules. A vendor file version says which set of business fields and semantics the sender believes it is exporting. An importer might use one schema dialect to define five business formats. Putting the same numeral in a database column called version for both concepts can make incidents painful to untangle. Receipts should include an identifier for the producer's declared format and for the rule set or importer release that made the decision. They answer different questions.
A field can also pass structural validation while being semantically unsupported. Suppose an older schema permits an open metadata object, and v4 producers add a condition that all readers are expected to enforce inside that open metadata object. The older importer can structurally read it yet is not qualified to install the record. That is a contract error. Either move such conditions into a declared and supported part of the record, or explicitly define a capability gate where the behavior is negotiated. Don't force staff to find a condition in raw files after a patron discovers the receiver ignored it.
Name the level where a batch contract permits partial progress
A segment might be a unit of work for one importer and merely a grouping hint for another. In an all-or-nothing exchange, a valid row count is diagnostic. It doesn't authorize applying those rows without the others. In a formally supported partial exchange, specify whether each valid row stands on its own or requires neighbors. A record with a safe displayed label can depend on a related restriction row or a matching station reference elsewhere in the batch. “Will apply whatever parses” is not an acceptable statement of that relationship. It hides the meaning under a count.
Decide what abandoned results look like in the supported workflow. A preflight may build a tentative plan and mark which rows would change, then discard it after a failure. No matter how precise the draft count looked, the receipt for that attempt should still say nothing was applied. A real partial application, if and only if the arrangement permits it, should identify its exact scope and who handles withheld records. In aggregate reporting give each class its own total, such as parsed, evaluated and applied. If counts use different eligibility sets, don't compare them without explaining the basis.
Use a case where the differences are easy to see. Two illustrative data rows might appear to describe one room and its public display schedule. The room row parses. The schedule row fails because a time-zone field was supplied with a meaning the receiver doesn't support. Splitting the batch into “one pass, one fail” may be useful for review, yet publishing a newly available room without its actual schedule could tell visitors they may use it when they can't. An all-or-nothing receipt states that neither became active while identifying the schedule row as the first obstacle. A partial contract could instead apply material that cannot imply availability and mark the rest held. Choose based on defined meaning, not on being able to return a greener dashboard.
If you can't express which dependencies were applied safely, choose a narrower acceptance policy until that contract is understood. This is not forever rejecting every error, and it needn't block ordinary remediation of the rejected inputs. It separates the upcoming data change from the receipt that tells people what has already happened. Staff can discuss a future migration without modifying the first receipt to sound as if the new policy was always in force.
Work a single batch through the rejection path
Say the sending branch exports 284 catalog records at 4 a.m. A header declares format 4. The receiver supports formats 2 and 3, and rules prohibit taking any rows from an unsupported file. The receiver can verify transport and storage succeeded, then reject at the format gate without claiming any row-level validation. The machine record identifies the attempt as intake-418, acknowledges receipt, states unsupported_format, records format 4 as observed and supported formats 2 and 3 as the checked set, and says the application stage was not reached. The visible note to the operator: “Catalog not updated. This file declares format 4; this importer currently accepts 2 or 3. Reference intake-418.”
An operator asks whether to resend in format 3. If the format 4 feature encodes a real lending restriction that can't be expressed in format 3, an automatic downgrade would reintroduce the original data loss. The person responsible for the export needs a specific compatibility option: either hold affected equipment back or add support on the receiver with an agreed mapping for the condition. There may be no harmless automatic workaround. That's why an operational next step can be “Contact your exchange coordinator with this receipt” rather than “Try the same file again.” A deterministic rejection is usually not fixed by hammering Retry.
Later the team deploys support for format 4. An authorized operator can replay the unchanged file if retention policy allows, or ask the sender to supply a new export if not. The receiver creates a second receipt referring to the first, with a new importer rule identifier and its own outcome. There is no need to turn the first red row green. Keeping both events answers an important question: was the catalog up to date between the first failure and the later application? A dashboard that edits the original event into “success” conceals that gap.
Replaying older material can undo newer information. If Thursday's file was rejected but Friday's succeeded, Thursday cannot always be applied on Saturday just because it validates now. Establish whether each file is a snapshot, delta, or initial state. Choose a replay policy appropriate to that semantics. A complete current snapshot may resolve a stale snapshot without replay. A missed delta may require sequencing or a correction batch from the sender. Do not let “the retry now worked” substitute for a decision about how versions of the data interact. Record the reason when a valid old file is intentionally not applied.
Another case: valid-looking material arrives ahead of its predecessor
Consider a fictional shared workshop that uses a small catalogue exchange for non-sensitive display inserts. Export 31 is the last applied version. An update numbered 33 arrives with a supported business format and every expected property. The receiver knows the export expresses changes relative to prior state, and 32 was never confirmed applied. The right conclusion is not “version unsupported” or “record invalid.” It's “valid format, waiting on predecessor; no new state activated.” A correctly drawn receipt makes this a sequencing issue rather than sending the producer off to change the schema.
A few hours later the publisher provides an independently authorized replacement snapshot numbered 34. The two systems have already agreed that a complete verified snapshot can establish a new starting point. The coordinator checks that this really is the complete snapshot for the intended scope and meets the destination's other conditions. Suppose this check succeeds and the snapshot is applied. Nothing requires the operator to replay 33 now just because the old blocker disappeared. The decision can instead be “attempt retained for evidence; superseded by the authorized full snapshot.” If a branch had only sent a partial snapshot, the same remedy would not necessarily work. State the scope of what was replaced.
The support conversation has a simple shape. Receipt 33 identifies the missing predecessor expected under that exchange; receipt 34 gives the separate verified outcome. A daily status message can now distinguish “catalogue restored from full snapshot” from “we replayed the backlog.” Those sentences imply different facts about what readers were seeing between deliveries. Preserve the actual sequence when a publisher might later need to explain why a display change did not appear that morning. Neither file has to stay forever simply to retain those few statements, provided the record and retention decisions meet the actual requirement.
Inject a duplicate in a training run. The second arrival can use the same intended version label while an authorized receipt still distinguishes separate attempts. Compare content identity only by a documented suitable mechanism when it matters. Matching one name isn't evidence of matching contents, and matching bytes needn't justify another application. Keep deliberate replays tied to the prior event with the reason and requested destination scope. Review the destination proof separately. This distinguishes replay approval from idempotency assumptions and from the broader question of whether replay would overwrite a newer result.
Retain enough to reconcile, not enough to become a second database
A failed file is not inherently less sensitive than a successful one. A user might include an unexpected field precisely because they made a configuration mistake. If your compact receipt previews the unexpected value, you could expose information your intake service wasn't designed to handle. Start with identifiers, stage names, bounded machine codes, and paths identifying fields where safe. A path in a dynamic map can itself contain a real name or account identifier. In such cases prefer a generic schema location over the raw key. If the original file is legitimately retained, use scoped access and a defined deletion period; if it isn't retained, say so on the receipt and give a route to request a fresh copy.
Don't put operational SQL, stack traces, or raw source material in a customer-facing failure response. One API convention for machine-readable problems is RFC 9457, Problem Details for HTTP APIs. It describes an error representation; it doesn't define your team's publish, storage, or import rules. You can offer a stable problem type and an occurrence identifier while retaining richer diagnostics for the team that actually resolves failed exchanges. Use the response convention that matches your application. An HTTP response alone is not your ledger, particularly when a batch arrives by file drop and there is no caller waiting to read a response.
Receipts have their own retention and scale tradeoffs. A daily file for each of 50 branches can generate thousands of records in a year without saving file payloads long term. Decide which time spans an operator is expected to audit and what constitutes the official record if two tools disagree. Native database records, periodically exported dashboards, and clipped chat logs are not interchangeable. A screenshot can show what someone saw on Tuesday; it doesn't prove the underlying insert was committed, and it may not expose later corrections. Give staff a durable read-only view that omits sensitive details by default.
Design the public error and the staff record as two views of the same event
A sender usually needs a reference and a useful correction route. A responsible importer developer may need a safe field path, the expected contract and a precise rejecting rule identifier. An operations supervisor may need to know which destination and date were affected. Giving each the entire failed payload doesn't make the record clearer. Give the event one identity and decide which fields can be seen by which authorized role. Use fixed message text or reviewed substitutions for the public problem detail rather than importing fragments of an unexpected field into an audience-facing error.
Consider whether each field is meaningful over time. A mutable “current importer” name may help dispatch but will not describe which version made yesterday's rejection. Store the version actually observed at evaluation and a separate reference for the current support owner. A generated problem instance can point to the immutable occurrence without implying that the public may retrieve internal logs. When the receiving view permits requests for help, explain which reference to include and what evidence not to send. A short controlled route is more useful than asking everyone to paste the whole file into any available chat.
A receipt doesn't need to be append-only in an absolute sense for every administrative change. It does need a durable way to preserve event history, audited corrections, and retention decisions under the governing policy. Suppose somebody entered the wrong branch label on a manual incident note. An authorized correction can update the display with a reason while retaining enough history to resolve earlier questions. Don't modify the disposition silently just because its old result looks awkward beside today's graph. If access controls or retention remove the underlying payload, state whether another verification artifact still supports the remaining receipt. Absence of a file is not proof that the original rejection never occurred.
Run a rehearsal where the same event is described on paper to three people. The sender should know whether a corrected export is helpful. The support person should identify the current destination and the scope of changes, if any. The developer should identify whether the fault was format, schema, ordering or application. If the three views disagree on observed facts, derive them from the same verified state. A consistent translation does not require all three people to see private details or internal code.
Test the interpretation at each boundary
Use separate fixtures instead of one file that fails in many ways. For the basic contract, send a known version with a valid record, the same record with an unknown core property, a record with a documented display extension, and a valid-looking record under an unsupported version header. Confirm that the approved cases pass, the core unknown follows the contract, and the unsupported header rejects before any misleading row-level conclusion. Inspect the final catalog as well as the receipt. A green parser result proves neither that rows were applied nor that the catalog respects the sender's intent.
Add a stale-order fixture: reject batch 418, accept a newer snapshot, then make 418 valid and attempt a replay. The receipt should preserve the original defect while the replay policy should preserve current state. Add a delivery fixture where the sender repeats a file with the same file name and different bytes; make sure support can find both receipts without confusing them. Add a crash fixture between record application and acknowledgment. Rather than expecting the log to tell the whole story, read the committed state and make sure your user-visible status does not invent certainty that the system lacks.
Finally test the human side with a mock incident. Give the operator today's receipt and yesterday's dashboard, but no logs or code. Can they find which team owns the next step, decide whether resending would help, and answer whether the destination was updated? If they can't, rewrite the receipt and clarify the workflow before adding another graph. Send the same exercise to the producer. A helpful message for the importer developer might be inscrutable to the person who can switch exporter settings. Barring operational constraints, let both parties copy one scenario reference into their own records instead of pasting the entire failed file.
Give the operator a comparison view that lines up the last applied snapshot and the pending correction without showing either file wholesale. The useful first screen might say that the last applied snapshot came from Export 20 and covers 281 items, the proposed correction applies to Export 19, and three candidates would affect records changed by Export 20. A count is not enough to authorize that correction; an operator still needs to see the exact conflict descriptions or hand the comparison to their coordinator. But this layout stops a reviewer from comparing names in two browser tabs and assuming the older valid file is safer because its preview has no red warnings. Make unverified counts visibly provisional when a preflight has not finished.
Ask the coordinator what the importer should do if the sending library acknowledges the problem but never sends a replacement. It might leave the old snapshot in place with an explicit age indicator; it might stop showing the affected availability after a locally approved freshness period. Those are different user experiences with different responsibilities. Neither belongs in the error handler as a magic default. Write down the chosen rule, connect it to the latest recorded good application, and test what happens when recovery subsequently succeeds. The receipt tells you when a cutoff may matter without pretending the importer has learned whether the actual equipment is still lendable.
One good measure of progress is time between a deterministic rejection and the operator identifying a viable next action, alongside counts of catalog changes that turned out to be incomplete. Another is whether a person investigating a later issue can reconstruct the state of the catalog for the time in question. Low measured failure numbers are not a success if the loader is silently dropping unfamiliar facts. High failure numbers may be acceptable briefly while a previously invisible mismatch is surfaced and corrected. Read the numbers through the actual failure classes and batch outcomes rather than treating “zero warnings” as the target.
The useful part of a rejection is not its red color. It is that the receiving system has refused to perform a change it cannot interpret, while leaving enough evidence for people to decide what happens next. A trustworthy importer can answer three questions without reopening an entire folder of old files: what contract did we see, what did we actually change, and how can we resolve the difference? If yours can't answer those yet, give it the receipt before you add another compatibility flag.
Test a negative result that surfaces some good evidence
A simulator can intentionally deliver a supported file whose preflight passes and whose publication never begins, without pointing to a live database. The receipt should expose the good work done before the stop while leaving the destination outcome unchanged. Next test one where no result is confirmed because contact with the destination was lost. The permanent record should not confuse unknown with “did not apply” or assume that an acknowledgment is interchangeable with a destination read. Reconcile with a clearly authorized source and attach that finding as a distinct event or verified note.
Test a replay from the human starting point as well. Show the operator an old rejected attempt from a sender whose recent files normally work. Ask them which exact representation the destination now uses and whether the original contents are still permissible to access under policy. If the record can't establish the application sequence or replay authority, do not reach for an imagined latest version. Request a new appropriate export or escalate through the exchange process. That action may cost a few minutes but avoids introducing a silent data correction whose provenance is worse than the original error.
Include a sample where two independently evaluated records disagree about a scope and the importer deliberately cannot select a winner. Choose what readable reason and next owner should appear. A default fallback that resolves the dispute by omitting the problematic property appears helpful only until an operator needs to reconstruct the decision. In the replay exercise, the best outcome can be “held for sender clarification” rather than “success after manual cleanup.” The controlled environment is designed to prove that uncertainty can survive a round trip without being patched away by a misleading status.
Lastly test evidence retention at the reporting boundary. The brief public error might continue to be available after detailed internals age out under approved policy. Verify that the surviving report still describes the stage, scope, confirmed effect and new action accurately. If a field says “full error available” after it has expired, replace that promise with a supported way to obtain a fresh receipt or appropriate evidence. A good rejection system is not obligated to keep every byte forever. It is obligated not to imply certainty its evidence no longer supports.
Plan a migration with evidence about what changed, not just a newer version label
Before making a new business format acceptable, identify a feature whose meaning might differ in the destination. A new code for an archived display item may influence whether it's findable at all. A new style hint might only affect a preview. Start by tracing two approved synthetic cases from the producer's statement through the validator into the final candidate result. The goal isn't just to see that the input is structurally valid: it's to specify which effects a successful import promises and where a disagreement must be held. Then a staff-facing receipt can accurately say the checked importer version understands the material changes instead of claiming a generic upgrade accepted everything.
A preview that receives the new representation can coexist with a previous live importer that doesn't. A team should not use the presence of a passing preview as permission to resend against live. Name the environment and ruleset the preview used and distinguish that validation from permission to activate. If necessary, give the producer an expected compatibility window that the responsible parties have actually agreed. When they haven't agreed to a particular date, don't communicate it as a deployment commitment. Retain the migration decision with the release so a support person can check which contract applies without having to interpret a new version string in a heated exchange.
Build a mixed-version fixture that contains only synthetic records. Include a documented core requirement formerly absent from the producer file, a supported explicit extension, and an old representation whose allowed translation is independently defined. The receipt for each run should make which cases were checked and what rules were used obvious. If a former name is an official alias under the accepted old format, handling it as such can work. Finding the same characters in a later format that intentionally changed the meaning is different. Keep the version and interpretation linked in test logs so a passing old right answer cannot accidentally certify the wrong new one.
A receiving service might be configured to recognize a new combination before the producer enables it. That does not establish that the new material has been received, let alone applied. In a controlled test, duplicate one day of entirely synthetic intake, use the old representation in one run and the new one in the other, and compare only intended relationships. If results diverge, explain the feature and expected outcome. If they agree on a sample, preserve only that claim; the validator cannot prove that contributors always use a human convention the contract never captured. Comparing candidates is useful without making one a proxy for the live authoritative state.
Have a separate post-release process for unexpected rejections. A short scan of fresh receipts can tell whether the examples missed a valid representation or a producer announced a version it did not actually ship. Do not fix a spike by disabling validation across all formats. First verify an exact synthetic reproduction when possible and ask the owner to decide the correct scope. A local receipt can remain useful during the investigation: record which attempts were held, which rules made that choice, and whether the dating or ordering of old files restricts later application. The change is trustworthy when you can explain why a rejected attempt stayed rejected, not only when the next upload turns green.
The migration review can also include a decline. If the proposed compatible representation omits an approved restriction the sender expected to preserve, document that no accepted transformation is available within current scope. Keeping the refusal visible lets an operator explain the delay without quietly giving the receiver a different catalog to work from. Authorizing an explicit reviewed mapping is a later decision. The original receipt shouldn't make that decision in advance.