Using Builder intents

Intents enable validation, add required actions that are required by the C2PA specification, and help prevent invalid operations when using a Builder. Intents are about the operation (create, edit, update) executed on the source asset.

Why use intents?

Without intents, you have to manually construct the correct manifest structure: adding the required actions (c2pa.created or c2pa.opened as the first action per the specification), setting digital source types, managing ingredients, and linking actions to ingredients. Getting any of this wrong produces a non-compliant manifest.

With intents, the caller declares what is being done and Builder handles the rest.

For example, without intents you have to manually wire up actions and make sure ingredients are properly linked to actions. This is especially important for parentOf ingredient relationships with the c2pa.opened action.

#include "c2pa.hpp"

c2pa::Context context;
c2pa::Builder builder(context, R"({
    "assertions": [
        {
            "label": "c2pa.actions",
            "data": {
                "actions": [
                    {
                        "action": "c2pa.created",
                        "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia"
                    }
                ]
            }
        }
    ]
})");
builder.sign(source_path, output_path, signer);

But with intents, Builder generates the actions automatically; for example:

#include "c2pa.hpp"

c2pa::Context context;
c2pa::Builder builder(context, R"({})");
builder.set_intent(Create, TrainedAlgorithmicMedia);
builder.sign(source_path, output_path, signer);

Both of these code snippets produce the same signed manifest. But with intents, Builder validates the setup and fills in the required structure.

Setting the intent

You can set the intent on a Builder instance by:

• Using Context
• Using set_intent on the Builder

Don't set intent using the deprecated load_settings() function. For existing code, see Context and Settings - Migrating from deprecated APIs.

Using Context

Pass the intent through a Context object when creating a Builder. This keeps intent configuration alongside other builder settings such as claim_generator_info and thumbnail.

c2pa::Context context(R"({
    "version": 1,
    "builder": {
        "intent": {"Create": "digitalCapture"},
        "claim_generator_info": {"name": "My App", "version": "0.1.0"}
    }
})");

c2pa::Builder builder(context, R"({})");
builder.sign(source_path, output_path, signer);

You can reuse the same Context across multiple Builder instances, ensuring consistent configuration:

c2pa::Context context(R"({
    "version": 1,
    "builder": {
        "intent": "edit",
        "claim_generator_info": {"name": "Batch Editor"}
    }
})");

for (const auto& path : image_paths) {
    c2pa::Builder builder(context, R"({})");
    builder.sign(path, output_path(path), signer);
}

Using set_intent on Builder

Call set_intent directly on a Builder instance for one-off operations or when the intent is determined at runtime. For example:

c2pa::Context context;
c2pa::Builder builder(context, R"({})");
builder.set_intent(Create, TrainedAlgorithmicMedia);
builder.sign(source_path, output_path, signer);

Intent precedence

When an intent is configured in multiple places, the most specific setting takes precedence. If set_intent is called on a Builder instance, it takes precedence over all other sources.

How intents relate to the source stream

The intent operates on the source passed to sign(), not on any ingredient added via add_ingredient.

The following diagram shows what happens at sign time for each intent:

For Edit and Update intents, Builder looks at the source stream, and if no parentOf ingredient has been added manually, it automatically creates one from that stream (and adds the needed action). The source stream becomes the parent ingredient. If a parentOf ingredient has already been added manually (via add_ingredient), Builder uses that one instead and does not automatically create one from the source.

How intent relates to add_ingredient

The Builder intent controls what the Builder does with the source stream (source asset) at sign time. The add_ingredient method adds other ingredients explicitly. These are separate concerns.

Including the header

The C2paBuilderIntent and C2paDigitalSourceType enums are available through the c2pa.hpp header file:

#include "c2pa.hpp"

Enum values are in the global namespace:

• C2paBuilderIntent: Create, Edit, or Update
• C2paDigitalSourceType: Empty, DigitalCapture, TrainedAlgorithmicMedia, and so on...

Using set_intent

Use the Builder set_intent method to specify the intent:

void Builder::set_intent(
    C2paBuilderIntent intent,
    C2paDigitalSourceType digital_source_type = Empty
);

Where:

• intent is one of the intent types.
• digital_source_type is one of the C2paDigitalSourceType values values that describes how the asset was made. Required for the Create intent. Defaults to Empty.

Intent types

Intent types can be any C2paBuilderIntent values:

Intent	Operation	Parent ingredient	Auto-generated action
Create	Brand-new content	Must NOT have one.	c2pa.created
Edit	Modifying existing content	Automatically created from the source stream if not provided	c2pa.opened (linked to parent)
Update	Metadata-only changes	Automatically created from the source stream if not provided.	c2pa.opened (linked to parent)

C2paDigitalSourceType

Enum value	Description
Empty	No source type specified. The default value.
DigitalCapture	Captured from a real-world source using a digital device
TrainedAlgorithmicMedia	Created by a trained algorithm (e.g., generative AI)
DigitalCreation	Created digitally (e.g., drawing software)
CompositeWithTrainedAlgorithmicMedia	Composite that includes trained algorithmic media
AlgorithmicallyEnhanced	Enhanced by an algorithm
ScreenCapture	Captured from a screen
VirtualRecording	Recorded from a virtual environment
Composite	Composed from multiple sources
CompositeCapture	Composite of captured sources
CompositeSynthetic	Composite of synthetic sources
DataDrivenMedia	Generated from data
AlgorithmicMedia	Created by an algorithm
HumanEdits	Human-edited content
ComputationalCapture	Captured with computational processing
NegativeFilm	Scanned from negative film
PositiveFilm	Scanned from positive film
Print	Scanned from a print
TrainedAlgorithmicData	Data created by a trained algorithm

Choosing the right intent

Create intent

Use the Create intent when the asset has no prior history. A C2paDigitalSourceType is required to describe how the asset was produced. Builder will:

• Add a c2pa.created action with the specified digital source type.
• Reject the operation if a parentOf ingredient exists.

Example: New digital creation

Using Context:

c2pa::Context context(R"({
    "version": 1,
    "builder": {"intent": {"Create": "digitalCreation"}}
})");

c2pa::Builder builder(context, R"({})");
builder.sign(source_path, output_path, signer);

Using set_intent:

c2pa::Context context;
c2pa::Builder builder(context, R"({})");
builder.set_intent(Create, DigitalCreation);
builder.sign(source_path, output_path, signer);

Example: Marking AI-generated content

c2pa::Context context(R"({
    "version": 1,
    "builder": {"intent": {"Create": "trainedAlgorithmicMedia"}}
})");

c2pa::Builder builder(context, R"({})");
builder.sign(source_path, output_path, signer);

Example: Create with additional manifest metadata

A Context and a manifest definition can be combined. The Context handles the intent; the manifest definition provides additional metadata and assertions:

c2pa::Context context(R"({
    "version": 1,
    "builder": {
        "intent": {"Create": "digitalCapture"},
        "claim_generator_info": {"name": "an_app", "version": "0.1.0"}
    }
})");

std::string manifest_def = R"({
    "title": "My New Image",
    "assertions": [
        {
            "label": "cawg.training-mining",
            "data": {
                "entries": {
                    "cawg.ai_inference": {"use": "notAllowed"},
                    "cawg.ai_generative_training": {"use": "notAllowed"}
                }
            }
        }
    ]
})";

c2pa::Builder builder(context, manifest_def);
builder.sign(source_path, output_path, signer);

Edit intent

Use the Edit intent when an existing asset is modified. With this intent, Builder:

1. Checks if a parentOf ingredient has already been added. If not, it automatically creates one from the source stream passed to sign().
2. Adds a c2pa.opened action linked to the parent ingredient.

No digital_source_type parameter is needed.

Example: Editing an asset

Using Context:

c2pa::Context context(R"({
    "version": 1,
    "builder": {"intent": "edit"}
})");

c2pa::Builder builder(context, R"({})");
// The Builder reads "original.jpg" as the parent ingredient,
// then writes the new manifest into "edited.jpg"
builder.sign("original.jpg", "edited.jpg", signer);

Using set_intent:

c2pa::Context context;
c2pa::Builder builder(context, R"({})");
builder.set_intent(Edit);
builder.sign("original.jpg", "edited.jpg", signer);

The resulting manifest contains one ingredient with relationship: "parentOf" pointing to original.jpg and a c2pa.opened action referencing that ingredient. If the source file already has a C2PA manifest, the ingredient preserves the full provenance chain.

Example: Editing with a manually-added parent

To control the parent ingredient's metadata (for example, to set a title or use a different source), add it explicitly:

c2pa::Context context(R"({
    "version": 1,
    "builder": {"intent": "edit"}
})");

c2pa::Builder builder(context, R"({})");

std::ifstream original("original.jpg", std::ios::binary);
builder.add_ingredient(
    R"({"title": "Original Photo", "relationship": "parentOf"})",
    "image/jpeg",
    original
);

builder.sign("canvas.jpg", "edited.jpg", signer);

Example: Editing with additional component ingredients

A parent ingredient can be combined with component or input ingredients. The intent creates the c2pa.opened action for the parent; additional actions can reference components (componentOf) or inputs (inputTo):

c2pa::Context context(R"({
    "version": 1,
    "builder": {"intent": "edit"}
})");

std::string manifest_def = R"({
    "assertions": [
        {
            "label": "c2pa.actions.v2",
            "data": {
                "actions": [
                    {
                        "action": "c2pa.placed",
                        "parameters": {"ingredientIds": ["overlay_label"]}
                    }
                ]
            }
        }
    ]
})";

c2pa::Builder builder(context, manifest_def);

// The Builder auto-creates a parent from the source stream
// and generates a c2pa.opened action for it.

// Add a component ingredient manually.
std::ifstream overlay("overlay.png", std::ios::binary);
builder.add_ingredient(
    R"({
        "title": "overlay.png",
        "relationship": "componentOf",
        "label": "overlay_label"
    })",
    "image/png",
    overlay
);

builder.sign("original.jpg", "composite.jpg", signer);

Update intent

Use the Update intent for metadata-only changes where the asset content itself is not modified. This is a restricted form of the Edit intent that:

• Allows exactly one ingredient (the parent).
• Does not allow changes to the parent's hashed content.
• Produces a more compact manifest than Edit.

As with Edit intent, Builder automatically creates a parent ingredient from the source stream if one is not provided.

Example: Adding metadata to a signed asset

Using Context:

c2pa::Context context(R"({
    "version": 1,
    "builder": {"intent": "update"}
})");

c2pa::Builder builder(context, R"({})");
builder.sign("signed_asset.jpg", "updated_asset.jpg", signer);

Using set_intent:

c2pa::Context context;
c2pa::Builder builder(context, R"({})");
builder.set_intent(Update);
builder.sign("signed_asset.jpg", "updated_asset.jpg", signer);