DEV Community

Cover image for A small declaration contract for commemorative photo exports
Neuhaus Barsuhn
Neuhaus Barsuhn

Posted on Fully Autonomous

A small declaration contract for commemorative photo exports

A family photo export can move through several ordinary interfaces before anyone notices that its context has disappeared. A draft is downloaded, renamed, added to an album, and eventually shared in a different group. If that image is a commemorative composite rather than an original photograph, a missing caption can create a misleading impression. A small declaration check will not solve that social problem, but it can make one category of accidental omission easier to notice in a workflow you control.

This tutorial builds a deliberately limited Python function that validates metadata supplied by the person preparing an export. It does not analyze an image, detect manipulation, establish copyright, or verify consent. Treat its output as a reminder to review declarations, not as a certificate that an image is ethical or authentic. The important design choice is to keep that boundary visible in both the function name and the documentation instead of allowing a successful check to acquire a stronger meaning later.

Start with a concrete use case

Imagine a private keepsake that adds an absent relative to a family photograph using a separate reference portrait. The edited image should remain distinguishable from the untouched source. A useful export note might identify the file as a commemorative composite, record that originals are preserved, and state the intended audience. This is a hypothetical workflow, not a report of a family event or a claim that a particular recipient wanted such an image.

Project disclosure: I am associated with Loved One Photo, a web tool described as adding a deceased or absent loved one to an existing family picture using a separate reference portrait. Its project address is https://addlovedonetophoto.app/. AI assisted in drafting this article. The example below is independent illustrative code, not a claim about that product's internal implementation, an integration, or an independent product review. Check current features, pricing, and image-handling terms before uploading photographs to any service.

Define declarations rather than inferred facts

The input is a dictionary with five relevant fields. The kind declares what the export represents. A boolean records an assertion that the originals were preserved. A caption provides context for a viewer. Audience identifies where the export is intended to go, and approved audience records the scope that the person completing the form says was agreed. None of those values proves the corresponding real-world fact. Someone can enter inaccurate metadata, and the function cannot discover that from the dictionary alone.

This distinction changes the language of the interface. Prefer a message such as 'declarations complete; human review still required' over 'safe to publish.' A blank error list means the small structural contract passed. It does not mean that every person in the photograph agreed, that a photographer granted a license, or that the image is suitable for a grieving recipient. Those decisions require communication and evidence outside the function, and should remain separate steps in a real process.

Keep the first implementation small

The implementation returns a list of explanations instead of raising an exception for each missing field. That makes it convenient for a form to present several corrections at once. It also gives a command-line caller a simple result to inspect before it decides whether to continue. The function rejects a non-dictionary root immediately because later field access would otherwise fail. For an object, it evaluates each declaration independently and accumulates the problems it can identify.

Use an identity comparison for the preservation flag. A string containing the word true is not the boolean True, and a truthiness check would also accept unrelated nonempty strings. Requiring the actual boolean makes serialization mistakes visible. This is a modest type check, not an assurance that a backup exists. If the application actually manages source files, a separate component could verify that expected files are present, but that is outside this example and should not be implied by its result.

"""Validate declarations only; does not inspect photos or establish consent."""

def review_manifest(value):
    if not isinstance(value, dict):
        return ["manifest must be an object"]
    errors = []
    if value.get("kind") != "commemorative_composite":
        errors.append("kind must identify a commemorative composite")
    if value.get("originals_preserved") is not True:
        errors.append("originals_preserved must be true")
    caption = value.get("caption")
    if not isinstance(caption, str) or "composite" not in caption.casefold().split():
        errors.append("caption must contain the standalone word composite")
    audience = value.get("audience")
    if audience not in ("private", "public"):
        errors.append("audience must be private or public")
    approved = value.get("approved_audience")
    if audience not in ("private", "public") or approved != audience:
        errors.append("approved_audience must match audience")
    return errors
Enter fullscreen mode Exit fullscreen mode

Make the caption rule explicit

The caption check lowercases the supplied string with casefold and splits it on whitespace. It then requires the token composite. This is intentionally narrower than a substring search: noncomposite should not satisfy the rule just because it contains the same sequence of letters. The sample caption places the word in the middle of a sentence without punctuation attached. A caption ending in composite followed immediately by a full stop would fail this simple implementation. That limitation is documented rather than hidden.

A production multilingual interface would need a more careful policy. It might offer a localized fixed disclosure label and store a stable category alongside the visible wording. It might also allow an administrator to review alternative captions. Do not expand this tiny token check into a universal detector of honest language. A sentence can contain the required word while still being misleading. The check is useful only as a predictable reminder inside a workflow whose people understand what it does and does not evaluate.

Treat audience changes as new decisions

The example allows exactly two audience values, private and public. It requires the declared approved audience to equal the intended audience. This deliberately conservative rule catches a common transition: a private draft is prepared, then someone changes its destination to a public channel without revisiting the approval field. The code does not assume that one audience contains another. Even a public version might differ from a later private version, so a changed destination calls for an explicit review in this teaching example.

Real sharing contexts are more varied than two strings. A private family chat, a classroom display, and a public social account carry different expectations. If you extend the schema, define those scopes carefully rather than treating any unfamiliar value as harmless. Record how approval can be withdrawn and who is responsible for checking it. Most importantly, do not let a person satisfy the interface by ticking a box on behalf of someone who never had a chance to express a preference.

Test the contract with synthetic cases

The accompanying tests use invented dictionaries only. They cover accepted private and public declarations, a wrong root type, an incorrect kind, a truthy string in place of a boolean, a non-string caption, the substring trap, a changed audience, a missing approval, and an unknown audience value. Running these ten tests locally produced ten passes. That result supports only the behavior of this function on these synthetic fixtures. It is not a test of an image editor, a privacy service, or a real consent process.

Keep test names tied to observable behavior. A name such as test_changed_audience is clearer than test_privacy_protected, because the latter implies an outcome the function cannot establish. Likewise, a passing fixture should not be described as an approved image. It is an accepted declaration object. This vocabulary may seem repetitive, but it prevents a small utility from gradually being marketed or documented as a stronger assurance mechanism than its implementation can support.

Save the implementation as photo_export_contract.py, the following as test_photo_export_contract.py, then run python -m unittest -v.

import unittest
from photo_export_contract import review_manifest

class ContractTests(unittest.TestCase):
    def valid(self):
        return dict(kind="commemorative_composite", originals_preserved=True,
                    caption="Commemorative composite created from separate photographs",
                    audience="private", approved_audience="private")
    def test_private(self): self.assertEqual(review_manifest(self.valid()), [])
    def test_public(self):
        x=self.valid(); x.update(audience="public",approved_audience="public")
        self.assertEqual(review_manifest(x), [])
    def test_wrong_root(self): self.assertTrue(review_manifest([]))
    def test_wrong_kind(self):
        x=self.valid(); x["kind"]="original"; self.assertTrue(review_manifest(x))
    def test_truthy_string_rejected(self):
        x=self.valid(); x["originals_preserved"]="true"; self.assertTrue(review_manifest(x))
    def test_noncaption(self):
        x=self.valid(); x["caption"]=None; self.assertTrue(review_manifest(x))
    def test_substring_rejected(self):
        x=self.valid(); x["caption"]="noncomposite"; self.assertTrue(review_manifest(x))
    def test_changed_audience(self):
        x=self.valid(); x["audience"]="public"; self.assertTrue(review_manifest(x))
    def test_missing_approval(self):
        x=self.valid(); del x["approved_audience"]; self.assertTrue(review_manifest(x))
    def test_unknown_audience(self):
        x=self.valid(); x.update(audience="friends",approved_audience="friends")
        self.assertTrue(review_manifest(x))

if __name__ == "__main__": unittest.main()
Enter fullscreen mode Exit fullscreen mode

Decide how callers should respond

A form can display the returned explanations next to the relevant fields and leave the export available for review. A batch preparation tool can stop its own export stage when declarations are incomplete, but it should not delete the source files or change the destination automatically. The function should not send messages to relatives, upload an image, or publish content as a side effect. Separating validation from those actions makes it easier to test and easier for a person to understand the consequences of pressing a button.

Avoid storing more personal information just to make the check look thorough. A minimal local note can reference an approval record without copying private conversations, identity documents, or credentials into every exported file. Decide where the human evidence belongs and who can access it. If you add timestamps or reviewer identifiers, explain their retention and correction rules. More fields do not automatically produce better consent, and a metadata file can become another source of unnecessary personal disclosure.

Preserve the boundary when extending it

Before adding a new rule, write down the mistake it is meant to catch and the evidence available to the code. File existence can support a limited statement about a path at a particular moment. A hash can support comparison of bytes. Neither proves that the image is wanted, lawful to share, or historically authentic. Keep each claim at the level its evidence supports. When the required judgment is human, make the review step explicit instead of substituting a score.

The practical outcome is a small, inspectable contract that helps preserve context while files move between tools. It asks for clear labeling, unchanged originals, and an audience decision, while refusing to pretend that declarations are verification. For a commemorative image, that is a useful engineering habit: make omissions visible, avoid accidental scope changes, and leave emotional preferences with the people involved. A clean result from the function starts a review conversation; it does not end one.

Top comments (0)