Writing assertions and actions

Overview

Assertions provide information about when, where, and how an asset was created or transformed.

The JSON manifest contains an assertions array, whose elements are AssertionDefinition objects. An AssertionDefinition object has two required properties: label, a string, and data, which can contain arbitrary information. When reading an assertion, there are two optional properties, kind and instance.

The standard form of an assertion in a JSON manifest is:

"assertions": [
  ...
  {
    "label": "Label string",
    "data": { 
      // Arbitrary data in JSON-LD format .. 
    },
    "kind": "Json" // Optional: one of “Cbor”,  “Json”, “Binary”, or “Uri”
    "instance" : 0 // Optional and rarely used
  },
  ...
]

info

Every manifest has to start with either an opened or created action, which has to be the first action in the manifest. Each of these actions need to have an associated ingredient.

Changes from earlier releases

Changes include:

Old training and data mining assertions c2pa.data_mining, c2pa.ai_training, c2pa.ai_generative_training, and c2pa.ai_inference have been replaced by CAWG training and data mining assertions
SoftwareAgent is a ClaimGeneratorInfo structure instead of a string.
Ingredients are now V3 ingredients

C2PA standard assertions

The C2PA Technical Specification defines a set of standard assertions and their corresponding labels. In addition, you can define custom assertions for your specific application.

The following table summarizes some of the most important standard assertions.

Assertion	Label	Description
Content bindings	`c2pa.hash.*`, `c2pa.soft-binding`, etc.	Uniquely identify portions of an asset and bind the assertion to it, for example using cryptographic hashes.
Actions (v2)	`c2pa.actions.v2`	Creation, edits, and other actions on an asset, such as cropping, color or contrast adjustment, and so on.

note

The CAI SDK handles assertions for thumbnails, content bindings, and ingredients, so normally you don't need to think about them.

Content bindings

Content bindings are standard assertions such as c2pa.hash.boxes and c2pa.hash.data that uniquely identify portions of an asset. For more information on content bindings, see the C2PA Technical Specification.

note

The CAI SDK writes content bindings assertions, so normally you don't need to write them, just read them.

For example, the c2pa.hash.data assertion shown in the detailed manifest example specifies an exclusion hash:

"assertions": [
  ...
  "c2pa.hash.data": {
    "alg": "sha256",
    "exclusions": [
      {
        "length": 51179,
        "start": 20
      }
    ],
    "hash": "DcGR4k9M6aLXXCeDii4tSdX45rrIM5HSr1Wy/czQ6ro=",
    "name": "jumbf manifest",
    "pad": "<omitted>"
  },
  ...
]

Actions

An action is an assertion that provides information about creation, edits, and other things that have occurred to an asset. In the manifest, an actions assertion is an array of AssertionDefinition objects.

info

Every manifest has to start with either an c2pa.opened or c2pa.created action, which has to be the first action in the manifest. Each of these actions need to have an associated ingredient.

For example:

...
"assertions": [
  {
    "label": "c2pa.actions.v2",
    "data": {
      "actions": [
        {
          "action": "c2pa.created",
          "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",
          "softwareAgent": "Adobe Firefly"
        }
      ]
    }
  }
],
...

Each object in the actions array has the following standard properties.

Property	Required?	Description	Example
`action`	Yes	The action name. See Action names.	`c2pa.created`
`digitalSourceType`	No	A URL identifying a IPTC term. See Digital source type.	`http://cv.iptc.org/newscodes/` `digitalsourcetype/digitalCapture`
`softwareAgent`	No	The software or hardware used to perform the action.	`"Adobe Firefly"`
`parameters`	No	Additional information describing the action; see Parameters	Reference to ingredients in the `ingredientIds` array.
`parameters`	No	Additional information describing the action; see Parameters	Reference to ingredients in the `ingredientIds` array.

V2 actions

The C2PA Technical Specification describes expanded v2 actions. V1 actions have a label of c2pa.actions v2 actions have a label of c2pa.actions.v2. Actions are modelled after XMP ResourceEvents, but with a number of C2PA-specific adjustments.

V1 actions are fully specified in the actions array. However, a v2 action may either be fully specified in an element of the actions array or it may be derived from an element in the templates array with the same action name.

The CAI APIs can read all v2 actions and write **most** v2 actions. What v2 actions can it NOT write? We should document that.

Action names

The value of the action property must be either one of the pre-defined standard C2PA action strings of the form c2pa.* or a custom action name. The set of standard C2PA actions includes fundamental ones as c2pa.created for when an asset is first created, and others (c2pa.cropped, c2pa.resized, and so on) for when an asset's content is modified in some way.

For the complete list of standard actions, see the C2PA Technical Specification.

Digital source type

Use the digitalSourceType property to specify how an asset was created or modified, for example "digital capture", "digitized from negative," or "trained algorithmic media."

The value of digitalSourceType is one of the URLs specified by the International Press Telecommunications Council (IPTC) NewsCodes Digital Source Type scheme of the form http://cv.iptc.org/newscodes/digitalsourcetype/<CODE>, where <CODE> is one of the codes shown in the following table.

Code	Description
algorithmicallyEnhanced	Minor augmentation or correction by algorithm.
algorithmicMedia	Media created purely by an algorithm not based on any sampled training data, e.g. an image created by software using a mathematical formula.
composite	Mix or composite of several elements, any of which may or may not be generative AI.
compositeCapture	Mix or composite of several elements that are all captures of real life.
compositeSynthetic	Mix or composite of several elements, at least one of which is synthetic.
compositeWithTrainedAlgorithmicMedia	The compositing of trained algorithmic media with some other media, such as with inpainting or outpainting operations.
dataDrivenMedia	Digital media representation of data via human programming or creativity.
digitalCreation	Media created by a human using non-generative tools. Use instead of retired digitalArt code.
digitalCapture	The digital media is captured from a real-life source using a digital camera or digital recording device.
humanEdits	Augmentation, correction or enhancement by one or more humans using non-generative tools. Use instead of retired minorHumanEdits code.
negativeFilm	The digital image was digitized from a negative on film or any other transparent medium.
positiveFilm	The digital image was digitized from a positive on a transparency or any other transparent medium.
print	The digital image was digitized from an image printed on a non-transparent medium.
screenCapture	A capture of the contents of the screen of a computer or mobile device.
trainedAlgorithmicMedia	Digital media created algorithmically using a model derived from sampled content.
virtualRecording	Live recording of virtual event based on synthetic and optionally captured elements.

note

This table is provided for convenience. For the authoritative list, see the IPTC NewsCodes Digital Source Type scheme (controlled vocabulary).

Generative AI action

To specify that an asset was created using generative AI, use the c2pa.created action with digitalSourceType that's one of:

trainedAlgorithmicMedia for an asset created by generative AI tools.
compositeWithTrainedAlgorithmicMedia for an asset that contains one or more elements that were created by generative AI tools.

For other possible values of digitalSourceType, see Digital source type.

"assertions": [
...
  {
    "label": "c2pa.actions.v2",
    "data": {
      "actions": [
        {
          "action": "c2pa.created",
          "digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",
          "softwareAgent": "<TOOL_NAME>"
        }
      ]
    }
  }
...
]

Where <TOOL_NAME> is the name of the generative AI tool or service.

Parameters

The parameters property can contain any data that provide more details on the action, for example:

"actions": [
  {
    "action": "c2pa.color_adjustments",
    "parameters": {
      "com.adobe.acr": "Contrast2012",
      "com.adobe.acr.value": "26"
    }
  },
  ...
]

When creating an actions assertion that has an associated ingredient, the parameters object must include a ingredientIds property with an array of one or more instance_id values from ingredients. This is how you associate an action with one or more ingredients. When creating an actions assertion that has an associated ingredient, the parameters object must include a ingredientIds property with an array of one or more instance_id values from ingredients. This is how you associate an action with one or more ingredients.

info

The C2PA specification requires that a c2pa.transcoded, c2pa.repackaged, c2pa.opened, or a c2pa.placed action have one or more associated ingredients, so it is very important to add the ingredientIds parameter with a matching ingredient. The C2PA specification requires that a c2pa.transcoded, c2pa.repackaged, c2pa.opened, or a c2pa.placed action have one or more associated ingredients, so it is very important to add the ingredientIds parameter with a matching ingredient.

For example:

"actions": [
  {
    "action": "c2pa.opened",
    "parameters": {
      "ingredientIds": [
      "ingredientIds": [
        "xmp.iid:813ee422-9736-4cdc-9be6-4e35ed8e41cb"
      ]
    }
  },
  ...

note

The old ingredientId field is deprecated.

For more information on action parameters, see the C2PA Technical Specification.

The instance_id property

When defining/writing a manifest, the instance_id property identifies an ingredient used in an action.

Any c2pa.opened or c2pa.placed action must have an associated ingredient identified by the ingredientIds parameters field of the action with an array of ingredient instance_id values.

"ingredients": [
  {
    ...
    "instance_id": "<String-instance-ID-of-ingredient>",
    "relationship": "parentOf",
    "label": "c2pa.ingredient.v3"
  },
  ...
],
"actions": [
  {
    "action": "c2pa.*",
    "parameters": {
      "ingredientIds": [
      "ingredientIds": [
        "<String-instance-ID-of-ingredient>"
      ],
    }
  },
  ...
]

For example, the following action identifies that the c2pa.opened action was performed on the ingredient with ID xmp.iid:3250038a-22ca-459b-8392-de275f8b155c:

"ingredients": [
  {
    "title": "crater-lake.jpeg",
    "format": "image/jpeg",
    "instance_id": "xmp.iid:7f136ee1-6e84-4d80-9de3-e1180ef2b690",
    "relationship": "parentOf",
    "label": "c2pa.ingredient.v3"
  }
],
"assertions": [
  {
    "label": "c2pa.actions.v2",
    "data": {
      "actions": [
      {
        "action": "c2pa.opened",
        "parameters": {
          "org.cai.ingredientIds": [
            "xmp.iid:7f136ee1-6e84-4d80-9de3-e1180ef2b690"
          ],
          "ingredients": [
            {
              "url": "self#jumbf=c2pa.assertions/c2pa.ingredient.v3",
              "hash": "yb/F7GBepYRyaFM16gzj6t84CKDTnBxhnLqYjnB0iX0="
            }
          ]
        }
      },
      ...
      ]
    }
  }
]

CAWG metadata assertions

Starting with version 2.2, the C2PA specification provides for a category of metadata assertions with a standardized serialization that replace the old Exif, IPTC, and Creative Work assertions in prior versions of the specification.

Use CAWG metadata assertions to include metadata from metadata standards such as XMP, IPTC, and Exif in a manifest. For more information, see the CAWG Metadatda Assertion technical specification.

Metadata assertions must include one or more @context properties in the data object, as explained in the JSON-LD specification. Follow the examples shown in each section.

Assertion	Label	Description
Exif information	`stds.exif`	Camera information such as maker, lens stored in Exchangeable image file format (Exif).
IPTC photo and video metadata	`stds.iptc`	Properties from the IPTC Photo and Video Metadata Standards, describing for example ownership, rights, and other metadata about a image or video asset.
Training and data mining	`cawg.training-mining`	Whether the creator/owner of an asset grants permission to use it for data mining or AI/ML training. NOTE: Previously, this assertion's label was `c2pa.training-mining`.

Exif assertion

Exchangeable image file (Exif) format is a standard for storing technical metadata in image files of JPEG, TIFF, PNG, and other formats. Most digital cameras (including smartphones), scanners and other digital capture devices use Exif to store information such as device make and model, shutter speed, ISO number, date and time of capture, location, and so on. For more information on Exif, see the Exif specification.

Use an Exif assertion to add Exif information to the asset in a way that can be validated cryptographically. An Exif assertion has the label stds.exif.

Here is a simple example:

"assertions": [
  ...
  {
    "label": "stds.exif",
    "data": {
      "@context" : {
        "exif": "http://ns.adobe.com/exif/1.0/"
      },
      "exif:GPSVersionID": "2.2.0.0",
      "exif:GPSLatitude": "39,21.102N",
      "exif:GPSLongitude": "74,26.5737W",
      "exif:GPSAltitudeRef": 0,
      "exif:GPSAltitude": "100963/29890",
      "exif:GPSTimeStamp": "2019-09-22T18:22:57Z"
    }
  }
  ...
]

IPTC metadata assertion

An International Press Telecommunications Council (IPTC) metadata assertion represents properties from the IPTC Photo Metadata Standard and Video Metadata Standard that describe ownership, rights, and descriptive metadata about an asset.

An IPTC assertion has the label stds.iptc and is stored in JSON-LD format using the XMP field names and structures specified in the IPTC standards.

Earlier versions of the C2PA specification defined the stds.iptc.photo-metadata label for IPTC photo metadata; starting with version 1.3, the C2PA specification defines the stds.iptc assertion that includes video metadata as well.

note

Do not use the IPTC plus:DataMining property to indicate whether permission is granted to use an asset in data mining or AI/ML training. Instead use the CAWG training and data mining assertion.

For a summary reference to IPTC metadata properties, see IPTC properties.

CAWG training and data mining assertion

Assertions with the cawg.training-mining label provide information about whether an asset with C2PA metadata may be used as part of a data mining or AI/ML (artificial intelligence / machine learning) workflows, including whether permission is granted to use an asset in ML training or inference.

note

Training and data mining assertions formerly had c2pa.* labels. See Legacy training and data mining assertion for more information.

Entry Key	Whether permission is granted...	Possible values of `use` property
`cawg.data_mining`	To extract text or data from the asset for purposes of determining "patterns, trends and correlations," including images containing text, where the text could be extracted via OCR.	`allowed`, `notAllowed`, or `constrained`
`cawg.ai_inference`	To use the asset as input to a trained AI/ML model for the purposes of inferring a result. Sometimes referred to as the "do not infer" assertion.	`allowed`, `notAllowed`, or `constrained`
`cawg.ai_generative_training`	To use the asset as training data for a generative AI/ML model that could produce derivative assets. Sometimes referred to as the "do not train" assertion.	`allowed`, `notAllowed`, or `constrained`
`cawg.ai_training`	To use the asset to train non-generative AI/ML models, such as those used for classification, object detection, and so on.	`allowed`, `notAllowed`, or `constrained`

The value of each of these properties is an object with a use property that can have one of these values:

allowed: Permission is granted for this type of use.
notAllowed: Permission is NOT granted for this type of use.
constrained: Permission is not unconditionally granted for this use. You can provide more details (such as contact information) in the constraints_info text property.

For more information, see the CAWG Training and Data Mining Assertion technical specification.

For example:

"assertions": [
  ...
  {
    "label": "cawg.training-mining",
    "data": {
      "entries": {
        "cawg.ai_generative_training": { "use": "notAllowed" },
        "cawg.ai_inference": { "use": "notAllowed" },
        "cawg.ai_training": { "use": "notAllowed" },
        "cawg.data_mining": { 
          "use": "constrained",
          "constraint_info" : "Contact foo@bar.com for more information."
        } 
      }
    }
  }
  ...
]

Custom assertions

In addition to the C2PA standard assertions, you can also define custom assertions if the standard assertions don't cover your specific needs. A custom assertion has a label string with reverse domain name notation syntax, for example com.adobe.product-foo.bar.

For example:

"assertions": [
  ...
  {
    "label": "com.mycompany.myproduct",
    "data": {
      "git_hash": "023bb51",
      "lib_name": "Our C2PA C++ Library",
      "lib_version": "2.5.1",
      "target_spec_version": "1.2"
    },
    "kind": "Json"
  },
  ...
]

Overview​

Changes from earlier releases​

C2PA standard assertions​

Content bindings​

Actions​

V2 actions​

Action names​

Digital source type​

Generative AI action​

Parameters​

The instance_id property​

CAWG metadata assertions​

Exif assertion​

IPTC metadata assertion​

CAWG training and data mining assertion​

Custom assertions​

Overview

Changes from earlier releases

C2PA standard assertions

Content bindings

Actions

V2 actions

Action names

Digital source type

Generative AI action

Parameters

The instance_id property

CAWG metadata assertions

Exif assertion

IPTC metadata assertion

CAWG training and data mining assertion

Custom assertions