Skip to main content

Using Builder intents

Intents enable validation, add actions required by the C2PA specification, and help prevent invalid operations when using a Builder. Intents are about the operation (create, edit, or 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 to do 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:

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 you determine the intent 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 you configure an intent in multiple places, the most specific setting takes precedence. Calling set_intent on a Builder instance 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. If the caller has not manually added a parentOf ingredient, Builder automatically creates one from that stream (and adds the needed action). The source stream becomes the parent ingredient. If the caller has already manually added a parentOf ingredient (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 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 types​

Intent types can be any C2paBuilderIntent values:

IntentOperationParent ingredientAuto-generated action
CreateBrand-new contentMust not have onec2pa.created
EditModifying existing contentAutomatically created from the source stream if not providedc2pa.opened (linked to parent)
UpdateMetadata-only changesAutomatically created from the source stream if not providedc2pa.opened (linked to parent)

C2paDigitalSourceType​

Enum valueDescription
EmptyNo source type specified. The default value.
DigitalCaptureCaptured from a real-world source using a digital device
TrainedAlgorithmicMediaCreated by a trained algorithm (e.g., generative AI)
DigitalCreationCreated digitally (e.g., drawing software)
CompositeWithTrainedAlgorithmicMediaComposite that includes trained algorithmic media
AlgorithmicallyEnhancedEnhanced by an algorithm
ScreenCaptureCaptured from a screen
VirtualRecordingRecorded from a virtual environment
CompositeComposed from multiple sources
CompositeCaptureComposite of captured sources
CompositeSyntheticComposite of synthetic sources
DataDrivenMediaGenerated from data
AlgorithmicMediaCreated by an algorithm
HumanEditsHuman-edited content
ComputationalCaptureCaptured with computational processing
NegativeFilmScanned from negative film
PositiveFilmScanned from positive film
PrintScanned from a print
TrainedAlgorithmicDataData created by a trained algorithm

Choosing the right intent​

Create intent​

Use the Create intent when the asset has no prior history. Specify a C2paDigitalSourceType 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 you modify an existing asset. With this intent, Builder:

  1. Checks whether the caller has already added a parentOf ingredient. 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 does not change. 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 the Edit intent, Builder automatically creates a parent ingredient from the source stream if the caller has not provided one.

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);