Add Assertions

Learn how to specify assertions when signing

📘

C2PA Specification Support

Truepic tools are compatible with all versions of the C2PA specification for signing. However, we recommend using the latest standards whenever possible. Please note that not all Content Credentials displays are compatible with version 2.x of the specification. This guide primarily covers assertions that comply with C2PA 2.1 and above, and references deprecated 1.4 assertions where relevant.

Assertions are key pieces of information added to a media file to provide context about the content. They are the most important details provided by the integrator—information that our tools do not automatically add. These assertions are crucial for verifying the media’s history and authenticity.

Most of our products use JSON format for adding assertions when signing a media file. You can either pass a JSON file or add assertions inline; in both cases, the JSON structure remains the same. However, the C2PA library uses raw string literals with a JSON-like structure. Be sure to convert the assertions below before using them.

Schema

The basic schema of assertions can be visualized like this:

{
  "assertions": [
    {
      "label": "{VALUE}",
      "data": {
        "{KEY}": "{VALUE}"
      }
    }
  ]
}

The top level is an object with a single assertions key that contains an array of assertion objects. Each assertion object has a label key and a data key. The label value is a string that identifies the type of assertion. The data value is an object where each entry is a key (string) and value (any type) that's specific to the type of assertion. Most assertions have more than one data point, and you're not just limited to a single assertion. The assertions array can contain multiple assertion objects of varying or the same types.

The schema you input for assertions is different from the schema shown in the validation report. While your input follows a specific format, the validation report transforms this schema to include validation results and contextual information, ensuring compliance with expected standards and providing insights into the processed data.

Enable precise redaction

Assertions included in an asset’s manifest can be removed when that asset is used as an ingredient in another manifest. The C2PA specification allows for redaction to protect privacy, enhance security, ensure relevance, and comply with regulations by selectively removing sensitive or unnecessary information.

We strongly encourage formatting multiple assertions of the same type as separate objects to enable individual redaction later. This approach allows each assertion to be redacted independently based on its label. Combining all assertions into a single object necessitates redacting the entire object, which may result in the removal of information that is desired to be retained. Separating assertions provides more precise control over what remains visible and what is redacted.

// Facilitates precise redaction
{
  "assertions": [
    {
      "label": "c2pa.metadata",
      "data": {
        "exif:DateTimeOriginal": "2023:05:11 20:36:00",
        "exif:OffsetTimeOriginal": "-04:00",
        "exif:TimeZoneName": "America/New_York"
      }
    },
    {
      "label": "c2pa.metadata",
      "data": {
        "exif:GPSLatitude": "40.748817",
        "exif:GPSLongitude": "-73.985428"
      }
    },
    {
      "label": "c2pa.metadata",
      "data": {
        "tiff:Make": "Google",
        "tiff:Model": "Pixel 5a"
      }
    }
  ]
}
// Does not facilitate precise redaction
{
  "assertions": [
    {
      "label": "c2pa.metadata",
      "data": {
        "exif:DateTimeOriginal": "2023:05:11 20:36:00",
        "exif:OffsetTimeOriginal": "-04:00",
        "exif:TimeZoneName": "America/New_York",
        "exif:GPSLatitude": "40.748817",
        "exif:GPSLongitude": "-73.985428",
        "tiff:Make": "Google",
        "tiff:Model": "Pixel 5a"
      }
    }
  ]
}

Actions assertions

An actions assertion details changes and activities affecting the asset’s content. It includes a list of actions, each describing what happened to the asset, when it happened, and possibly additional details like the software used for the action. This helps to create a complete record of the asset's history.

The most common fields used in an action assertion are:

fieldtypedescription
actionstringOne of the C2PA-defined standard actions from the table below. Custom, entity namespaced actions are also supported.
descriptionstringA free-text description of what an action does. Be sure to include this with a custom action.
whenstringISO 8601 formatted date and time.
softwareAgentobjectThe software or hardware used to perform the action. This field is useful for when the softwareAgent is not the same program as the app. It is often used to disclose AI models. Takes two strings, name and version.
digitalSourceTypestringurl to one of the terms defined by the IPTC, from the table below.

Basic example:

{
  "assertions": [
    {
      "label": "c2pa.actions.v2",
      "data": {
        "actions": [
          {
            action: "c2pa.created",
            description: "Generated image via API",
            digitalSourceType: "http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia",  
            "softwareAgent": {
              "name": "Midjourney",
              "version": "6.1"
            },
            when: "2023-05-11T20:40:00Z"  
          }
        ]
      }
    }
  ]
}

Standard actions

ActionMeaningVisual/editorial change
c2pa.adjustedColorChanges to tone, saturation, etc.
Was previously called c2pa.color_adjustmentsin v2.0 and below.
Yes
c2pa.changedSpeedReduced or increased playback speed of a video or audio track.Yes
c2pa.convertedThe format of the asset was changed.No
c2pa.createdThe asset was first created.No
c2pa.croppedAreas of the asset’s editorial content were cropped out.Yes
c2pa.deletedAreas of the asset’s editorial content were deleted.Yes
c2pa.drawingChanges using drawing tools including brushes or eraser.Yes
c2pa.dubbedAudio content changes.Yes
c2pa.editedGeneralized actions that would be considered editorial transformations of the content.Yes
c2pa.edited.metadataModifications to a metadata assertion, but not the asset’s content.No
c2pa.enhancedNoise reduction, compression, or sharpening applied.Yes
c2pa.filteredChanges to appearance with applied filters, styles, etc.Yes
c2pa.openedAn existing asset was opened and is being set as the parent ingredient.No
c2pa.orientationChanges to the direction and position of content.Yes
c2pa.placedAdded or placed an ingredient into the asset.Yes
c2pa.publishedAsset is released to a wider audience.No
c2pa.redactedOne or more assertions were redacted.No
c2pa.removedAn ingredient was removed.Yes
c2pa.repackagedA conversion of one packaging or container format to another. Content is repackaged without transcoding. This action is considered as a non-editorial transformation of the parent ingredient.No
c2pa.resizedChanges to content dimensions and/or file size.No
c2pa.transcodedA conversion of one encoding to another, including resolution scaling, bitrate adjustment, and encoding format change. This action is considered a non-editorial transformation of the parent ingredient.No
c2pa.translatedChanges to the language of the content.False
c2pa.trimmedParts of the content were trimmed.True
c2pa.unknownSomething happened, but the signing tool cannot specify what.Yes
c2pa.watermarkedAn invisible watermark was inserted into the digital content for the purpose of creating a soft binding.No

IPTC digitalSourceType

(Optional) Add digitalSourceType to any action.

"digitalSourceType": "http://cv.iptc.org/newscodes/digitalsourcetype/NAME"

Be sure to prepend http://cv.iptc.org/newscodes/digitalsourcetype/ to any name below. The categorization column denotes which names map to a flag in a Content Credentials display.

NameIPTC DescriptionCategorization
trainedAlgorithmicMediaDigital media created algorithmically using a model derived from sampled contentAI-generated
algorithmicMediaMedia created purely by an algorithm not based on any sampled training data, e.g., an image created by software using a mathematical formulaAI-generated
compositeSyntheticMix or composite of several elements, at least one of which is syntheticAI-edited
compositeWithTrainedAlgorithmicMediaThe compositing of trained algorithmic media with some other media, such as with inpainting or outpainting operationsAI-edited
algorithmicallyEnhancedMinor augmentation or correction by algorithm. E.g., a photo that has been digitally enhanced using a mechanism such as Google Photos’ “de-noise” featureAI-edited
compositeCaptureMix or composite of several elements that are all captures of real life
dataDrivenMediaDigital media representation of data via human programming or creativity. Examples: A representation of a distant galaxy created by analyzing the outputs of a deep-space telescope (as opposed to a regular camera) or an infographic created using a computer drawing tool such as Adobe Illustrator or AutoCAD.
digitalArtMedia created by a human using digital tools
digitalCaptureThe digital media is captured from a real-life source using a digital camera or digital recording deviceCamera-captured
virtualRecordingLive recording of a virtual event based on synthetic and optionally captured elements
minorHumanEditsMinor augmentation or correction by a human, such as a digitally-retouched photo used in a magazine
negativeFilmThe digital image was digitized from a negative on film or any other transparent medium
positiveFilmThe digital image was digitized from a positive on a transparency or any other transparent medium
printThe digital image was digitized from an image printed on a non-transparent medium

Metadata assertions

Including metadata in an assertion means it’s important because it’s explicitly added to the C2PA manifest and signed. This allows the data to be verified and attributed securely. Unlike standard, unprotected metadata like EXIF, which can be easily altered or ignored, this approach ensures that the metadata is both protected and consistently processed through a common format.

Prior to the 1.4 specification, there were individual assertions for each metadata standard (e.g., IPTC, EXIF). There is now a single label, stds.metadata for C2PA 1.4, or c2pa.metadata for C2PA 2.0 and above, which simplifies things and allows the spec to support other metadata standards in the future without the need to create more assertions.

Refer to Appendix A: Implementation Details for c2pa.metadata for a full list of supported and partially supported schemas. A @context object within each assertion object should always be included, to provide the namespaces for the metadata standards being specified.

Here are several assertions, which use the 2.0 label, c2pa.metadata. For signing with the 1.4 spec, use stds.metadata for the label instead.

{
  "assertions": [
    {
      "label": "c2pa.metadata",
      "data": {
        "tiff:Model": "Pixel 4",
        "tiff:Make": "Google",
        "@context": {
          "tiff": "http://ns.adobe.com/tiff/1.0/"
        }
      }
    },
    {
      "label": "c2pa.metadata",
      "data": {
        "exif:DateTimeOriginal": "2024:08:14 17:00:08",
        "@context": {
          "exif": "http://ns.adobe.com/exif/1.0/"
        }
      }
    },
    {
      "label": "c2pa.metadata",
      "data": {
        "Iptc4xmpExt:DigitalSourceType": "https://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture",
        "@context": {
          "Iptc4xmpExt": "http://iptc.org/std/Iptc4xmpExt/2008-02-29/"
        }
      }
    },
    {
      "label": "c2pa.metadata",
      "data": {
        "exif:GPSLatitude": "40.748817",
        "exif:GPSLongitude": "-73.985428",
        "@context": {
          "exif": "http://ns.adobe.com/exif/1.0/"
        }
      }
    }
  ]
}

Custom assertions

Custom assertions allow you to include additional metadata or information that isn’t covered by the standard C2PA assertions. They can be useful for capturing specific details relevant to your application or use case, and for including proprietary or organization-specific information in the content credentials, such as custom tags, identifiers, or unique data formats. However, custom assertions are not validated against the C2PA specification and are not typically viewable in Content Credentials displays.

We recommend using labels in reverse domain name notation, such as com.truepic.libc2pa, or start with the organization’s name, like truepic.metadata.

{
  "assertions": [
    {
      "label": "truepic.custom",
      "data": {
        "photographer": "Joe Smith",
        "campaign_id": "1234567"
      }
    }
  ]
}

Creative work assertions

❗️

Deprecated

This assertion is deprecated in C2PA 1.4 and unsupported in 2.0+ and may not be viewable in future Content Credentials displays.

Schema.org's CreativeWork metadata standard allows a signer to include creative credits, such as naming individuals or organizations as creators, publishers, and more. However, the C2PA specification has evolved to exclude this type of opt-in, identity-based data because it is self-disclosed rather than programmatically collected by the signing system. As a result, we advise new implementers of our signing tools to avoid using this assertion.

{
  "assertions": [
    {
      "label": "stds.schema-org.CreativeWork",
      "data": {
        "@context": "https://schema.org",
        "@type": "CreativeWork",
        "author": [ // replace with other role
          {
            "@type": "Person", // "Organization" also supported
            "name": "Joe Demo"
          }
        ]
      }
    }
  ]
}

The full list of CreativeWork supported roles is: accountablePerson, author, character, contributor, copyrightHolder, creator, editor, funder, maintainer, producer, provider, publisher, publisherImprint, sdPublisher, sourceOrganization, sponsor, translator