From 6e753dc21dc0fcb96629c83f811ff6eecd4c819f Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 29 May 2025 13:24:18 -0700 Subject: [PATCH 01/21] Add legacy manifests page --- docs/manifest/assertions-actions.md | 187 ++++++++++++++-------------- docs/manifest/ingredients.md | 14 ++- docs/manifest/legacy-assertions.md | 20 +++ sidebars.js | 4 + 4 files changed, 129 insertions(+), 96 deletions(-) create mode 100644 docs/manifest/legacy-assertions.md diff --git a/docs/manifest/assertions-actions.md b/docs/manifest/assertions-actions.md index e1f2dae..8c8c769 100644 --- a/docs/manifest/assertions-actions.md +++ b/docs/manifest/assertions-actions.md @@ -3,11 +3,11 @@ id: assertions-actions title: Assertions and actions --- -## Assertions +## Overview -Assertions provide information about when, where, and how an asset was created or transformed. +Assertions provide information about when, where, and how an asset was created or transformed. -In the JSON manifest, each assertion is specified by a [ManifestAssertion](../manifest/manifest-ref.mdx#manifestassertion) object. All the assertions in the manifest are in the `assertions` array. A ManifestAssertion object has two required properties, `label`, a string, and `data`, which can contain arbitrary information; and two optional properties, `kind` and `instance`. +In the JSON manifest, each assertion is specified by a [AssertionDefinition](./json-ref/manifest-def.mdx#assertiondefinition) object. All the assertions in the manifest are in the `assertions` array. A ManifestAssertion object has two required properties, `label`, a string, and `data`, which can contain arbitrary information; and two optional properties, `kind` and `instance`. The standard form of an assertion in a JSON manifest is: @@ -26,75 +26,18 @@ The standard form of an assertion in a JSON manifest is: ] ``` -**Metadata assertions** +## CAWG metadata assertions -_Metadata assertions_ include -- [Creative work](#creative-work-assertion) -- [Exchangeable image file (Exif) information](#exif-assertion) -- [IPTC photo and video metadata](#iptc-metadata-assertion) +Use _CAWG metadata assertions_ to include metadata from metadata standards such as XMP, IPTC, and Exif in a manifest. Metadata assertions must include one or more `@context` properties in the `data` object, as explained in the [JSON-LD](https://www.w3.org/TR/json-ld/#the-context) specification. Follow the examples shown in each section. -### C2PA standard assertions - -The C2PA Technical Specification defines a [set of standard assertions](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_standard_c2pa_assertion_summary) and their corresponding labels. In addition, you can define [custom assertions](#custom-assertions) for your specific application. - -The following table summarizes some of the most important standard assertions. - | Assertion | Label | Description | |-----------|-------|-------------| -| [Actions](#actions) | `c2pa.actions` | Creation, edits, and other actions on an asset, such as cropping, color or contrast adjustment, and so on. | -| ["Do not train"](#do-not-train-assertion) | `c2pa.training-mining` | Whether the creator/owner of an asset grants permission to use it for data mining or AI/ML training. | | [Creative work](#creative-work-assertion) | `stds.schema-org.CreativeWork` | Indicates the asset is the product of creative effort. | | [Exif information](#exif-assertion) | `stds.exif` | Camera information such as maker, lens stored in Exchangeable image file format (Exif). | -| [Content bindings](#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. | | [IPTC photo and video metadata](#iptc-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. | - -:::note -The CAI SDK handles assertions for thumbnails, content bindings, and ingredients, so normally you don't need to think about them. -::: - -### Do not train assertion - -Assertions with the `c2pa.training-mining` label indicate whether permission is granted to use an asset in data mining, machine learning (ML) training, or inference. The latter is sometimes referred to as the "do not infer" assertion. - -| Entry Key | Whether permission is granted... | Possible values of `use` property | -|-----------|-------------|-------------| -| `c2pa.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` | -| `c2pa.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` | -| `c2pa.ai_generative_training` | To use the asset as training data for a generative AI/ML model that could produce derivative assets. | `allowed`,
`notAllowed`,
or `constrained` | -| `c2pa.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` | - -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 [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_training_and_data_mining). - -For example: - -```json -"assertions": [ - ... - { - "label": "c2pa.training-mining", - "data": { - "entries": { - "c2pa.ai_generative_training": { "use": "notAllowed" }, - "c2pa.ai_inference": { "use": "notAllowed" }, - "c2pa.ai_training": { "use": "notAllowed" }, - "c2pa.data_mining": { - "use": "constrained", - "constraint_info" : "Contact foo@bar.com for more information." - } - } - } - } - ... -] -``` +| [Training and data mining](#do-not-train-assertion) | `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`. | ### Creative work assertion @@ -215,6 +158,63 @@ For example: ] ``` +### 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. + +| 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 [C2PA Technical Specification](https://cawg.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_training_and_data_mining). + +For example: + +```json +"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." + } + } + } + } + ... +] +``` + +## C2PA standard assertions + +The C2PA Technical Specification defines a [set of standard assertions](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_standard_c2pa_assertion_summary) and their corresponding labels. In addition, you can define [custom assertions](#custom-assertions) for your specific application. + +The following table summarizes some of the most important standard assertions. + +| Assertion | Label | Description | +|-----------|-------|-------------| +| [Content bindings](#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](#actions) | `c2pa.actions` | 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](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_binding_to_content). @@ -244,32 +244,9 @@ For example, the `c2pa.hash.data` assertion shown in the [detailed manifest exam ] ``` -### 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](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) syntax, for example `com.adobe.product-foo.bar`. - -For example: - -```json -"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" - }, - ... -] -``` - ## 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 [ManifestAssertion](manifest-ref.mdx#manifestassertion) objects. For example: +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](json-ref/manifest-def.mdx#assertiondefinition) objects. For example: ```json ... @@ -301,18 +278,17 @@ Each object in the `actions` array has the following standard properties. ### Action names -The value of the `action` property must be either one of the pre-defined [standard C2PA action strings](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_actions) 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](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_actions). +The value of the `action` property must be either one of the pre-defined [standard C2PA action strings](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) 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](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions). ### 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](https://cv.iptc.org/newscodes/digitalsourcetype/) of the form `http://cv.iptc.org/newscodes/digitalsourcetype/negativeFilm/`, where `` is one of the codes shown in the following table. +The value of `digitalSourceType` is one of the URLs specified by the International Press Telecommunications Council (IPTC) [NewsCodes Digital Source Type scheme](https://cv.iptc.org/newscodes/digitalsourcetype/) of the form `http://cv.iptc.org/newscodes/digitalsourcetype/`, where `` is one of the codes shown in the following table. -| Code | Description | +| 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. | @@ -321,7 +297,7 @@ The value of `digitalSourceType` is one of the URLs specified by the Internation | 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. | +| 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. | @@ -468,4 +444,27 @@ For example, the following action identifies that the `c2pa.opened` action was p This documentation covers C2PA v1 actions. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_actions) also describes expanded v2 actions. V1 actions are fully specified in the actions array. However, a v2 action may either be specified by an element of the actions array or from an element in the templates array with the same action name. -There are some additional differences between v1 and v2 actions, for example in v2, `softwareAgent` is a [ClaimGeneratorInfo](../manifest/manifest-ref.mdx#claimgeneratorinfo) structure instead of a string. The CAI APIs can read all v2 actions and write most v2 actions. +There are some additional differences between v1 and v2 actions, for example in v2, `softwareAgent` is a [ClaimGeneratorInfo](json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. The CAI APIs can read all v2 actions and write most v2 actions. + +## 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](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) syntax, for example `com.adobe.product-foo.bar`. + +For example: + +```json +"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" + }, + ... +] +``` diff --git a/docs/manifest/ingredients.md b/docs/manifest/ingredients.md index 8bfde32..769bdc6 100644 --- a/docs/manifest/ingredients.md +++ b/docs/manifest/ingredients.md @@ -3,10 +3,20 @@ id: ingredients title: Ingredients --- +
+ +`digitalSourceType` is now required on every ingredient, previously it was not. + +
+ ## Overview Digital assets are often not created entirely from scratch, but instead created from one or more existing assets, for example placing an image into a layer in Photoshop. Such constituent assets are called _ingredients_. +
+This should now cover v2 ingredients, right? +
+ This documentation covers C2PA v1 ingredients. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_ingredient) also describes improved v2 ingredients. :::note @@ -15,9 +25,9 @@ The C2PA Technical Specification describes _ingredient assertions_ but the CAI S ## Ingredient objects -Each ingredient used to create an asset is listed in the [JSON manifest](manifest-ref.mdx) `ingredients` array. When an ingredient itself has Content Credentials, those manifests are included in the composed asset's manifest store to keep the provenance data intact. +The `ingredients` array contains an element for each ingredient used to create an asset. When an ingredient itself has Content Credentials, those manifests are included in the composed asset's manifest store to keep the provenance data intact. -The `ingredients` array contains an [ingredient object](manifest-ref.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. +The `ingredients` array contains an [ingredient object](json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. Other important properties of the ingredient object include: - `format`: MIME type of the source file. diff --git a/docs/manifest/legacy-assertions.md b/docs/manifest/legacy-assertions.md new file mode 100644 index 0000000..61f90fb --- /dev/null +++ b/docs/manifest/legacy-assertions.md @@ -0,0 +1,20 @@ +--- +id: legacy-manifests +title: Reading old manifest data +--- + +The latest C2PA technical specification is [version 2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html). CAI recommends that applications: +- Write manifest data that conforms to this version. +- Read and validate manifest data from content credentials from applications that implemented earlier versions of the C2PA technical specification. This ensures that your application is "backward-compatible" and can still validate assets that had claims written in the past. + + +
+ +`c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. + +`SoftwareAgent` is now a structure + +`digitalSourceType` is now required on every ingredient, previously it was not. + +For READING old claims (only) … v1 actions and ingredients +
diff --git a/sidebars.js b/sidebars.js index 88bd062..40b3635 100644 --- a/sidebars.js +++ b/sidebars.js @@ -49,6 +49,10 @@ const sidebars = { type: 'doc', id: 'manifest/cawg-id', }, + { + type: 'doc', + id: 'manifest/legacy-manifests', + }, { type: 'doc', id: 'manifest/manifest-examples', From 9150115ed5297ec04a0260a69b87f29cebb93065 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 2 Jun 2025 11:15:24 -0400 Subject: [PATCH 02/21] reorg and add notes --- docs/manifest/assertions-actions.md | 24 +++++++++++++++++------- 1 file changed, 17 insertions(+), 7 deletions(-) diff --git a/docs/manifest/assertions-actions.md b/docs/manifest/assertions-actions.md index 8c8c769..8896cc7 100644 --- a/docs/manifest/assertions-actions.md +++ b/docs/manifest/assertions-actions.md @@ -206,6 +206,10 @@ The C2PA Technical Specification defines a [set of standard assertions](https:// The following table summarizes some of the most important standard assertions. +
+What other c2pa std assertions should we call out? +
+ | Assertion | Label | Description | |-----------|-------|-------------| | [Content bindings](#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. | @@ -244,7 +248,7 @@ For example, the `c2pa.hash.data` assertion shown in the [detailed manifest exam ] ``` -## Actions +### 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](json-ref/manifest-def.mdx#assertiondefinition) objects. For example: @@ -276,13 +280,13 @@ Each object in the `actions` array has the following standard properties. | `softwareAgent` | No | The software or hardware used to perform the action. | `"Adobe Firefly"` | | `parameters` | No | Additional information describing the action; see [Parameters](#parameters) | Reference to ingredients in the `org.cai.ingredientIds` array. | -### Action names +#### Action names The value of the `action` property must be either one of the pre-defined [standard C2PA action strings](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) 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](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions). -### Digital source type +#### 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." @@ -311,7 +315,7 @@ The value of `digitalSourceType` is one of the URLs specified by the Internation This table is provided for convenience. For the authoritative list, see the [IPTC NewsCodes Digital Source Type scheme (controlled vocabulary)](https://cv.iptc.org/newscodes/digitalsourcetype/). ::: -### Generative AI action +#### 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. @@ -340,7 +344,7 @@ For other possible values of `digitalSourceType`, see [Digital source type](#dig Where `` is the name of the generative AI tool or service. -### Parameters +#### Parameters The `parameters` property can contain any data that provide more details on the action, for example: @@ -384,7 +388,7 @@ The old `ingredientId` field is deprecated. For more information on action parameters, see the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_parameters). -### The instance_id property +#### The instance_id property When defining/writing a manifest, the `instance_id` property identifies an ingredient used in an action. @@ -440,7 +444,13 @@ For example, the following action identifies that the `c2pa.opened` action was p ... ``` -### V2 actions +#### V2 actions + +
+ +Should this now be only for v2 actions, and then move info on v1 actions to [Reading old manifest data](legacy-manifests)? + +
This documentation covers C2PA v1 actions. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_actions) also describes expanded v2 actions. V1 actions are fully specified in the actions array. However, a v2 action may either be specified by an element of the actions array or from an element in the templates array with the same action name. From 1b86f20818068191792d10a6ba17654cee8b8427 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 2 Jun 2025 13:31:37 -0400 Subject: [PATCH 03/21] Reorg and add comments --- docs/manifest/assertions-actions.md | 355 ++++++++++++++-------------- docs/manifest/legacy-assertions.md | 3 +- 2 files changed, 180 insertions(+), 178 deletions(-) diff --git a/docs/manifest/assertions-actions.md b/docs/manifest/assertions-actions.md index 8896cc7..9bb4ef3 100644 --- a/docs/manifest/assertions-actions.md +++ b/docs/manifest/assertions-actions.md @@ -7,7 +7,7 @@ title: Assertions and actions Assertions provide information about when, where, and how an asset was created or transformed. -In the JSON manifest, each assertion is specified by a [AssertionDefinition](./json-ref/manifest-def.mdx#assertiondefinition) object. All the assertions in the manifest are in the `assertions` array. A ManifestAssertion object has two required properties, `label`, a string, and `data`, which can contain arbitrary information; and two optional properties, `kind` and `instance`. +The JSON manifest contains an `assertions` array, whose elements are [AssertionDefinition](./json-ref/manifest-def/#assertiondefinition) objects. An AssertionDefinition object has two required properties: `label`, a string, and `data`, which can contain arbitrary information. When [reading an assertion](../json-ref/reader#manifestassertion), there are two optional properties, `kind` and `instance`. The standard form of an assertion in a JSON manifest is: @@ -26,179 +26,6 @@ The standard form of an assertion in a JSON manifest is: ] ``` -## CAWG metadata assertions - -Use _CAWG metadata assertions_ to include metadata from metadata standards such as XMP, IPTC, and Exif in a manifest. - -Metadata assertions must include one or more `@context` properties in the `data` object, as explained in the [JSON-LD](https://www.w3.org/TR/json-ld/#the-context) specification. Follow the examples shown in each section. - -| Assertion | Label | Description | -|-----------|-------|-------------| -| [Creative work](#creative-work-assertion) | `stds.schema-org.CreativeWork` | Indicates the asset is the product of creative effort. | -| [Exif information](#exif-assertion) | `stds.exif` | Camera information such as maker, lens stored in Exchangeable image file format (Exif). | -| [IPTC photo and video metadata](#iptc-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](#do-not-train-assertion) | `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`. | - -### Creative work assertion - -A creative work assertion states that an asset was the product of creative effort, such as an original photograph or artwork. [Schema.org](https://schema.org/) provides a set of types and metadata fields, including [CreativeWork](https://schema.org/CreativeWork), which describes a representation of creative effort. This assertion provides information about the asset, including who created it and the date/time of publication. - -A creative work assertion has the label `stds.schema-org.CreativeWork`. - -For example: - -```json -... -"assertions": [ - ... - { - "label": "stds.schema-org.CreativeWork", - "data": { - "@context": "https://schema.org", - "@type": "CreativeWork", - "url": "https://stock.adobe.com/615559889" - }, - "kind": "Json" - }, - ... -] -``` - -### 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](https://www.cipa.jp/std/documents/download_e.html?DC-008-Translation-2019-E). - -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: - -```json -"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](https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata) and [Video Metadata Standard](https://www.iptc.org/standards/video-metadata-hub/recommendation/) 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 specify whether permission is granted to use an asset in data mining or AI/ML training. Instead use the C2PA ["do not train" assertion](#do-not-train-assertion). -::: - -For a summary reference to IPTC metadata properties, see [IPTC properties](iptc-properties). - -See also: -- [Exploring c2patool and IPTC Photo Metadata](https://iptc.atlassian.net/wiki/spaces/PMD/pages/613613569/Exploring+c2patool+and+IPTC+Photo+Metadata) (Aug 2022). -- [IPTC Photo Metadata User Guide](https://www.iptc.org/std/photometadata/documentation/userguide/) - -For example: - -```json -... -"assertions": [ - ... - { - "label": "stds.iptc", - "data": { - "@context" : { - "Iptc4xmpCore": "http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/", - "Iptc4xmpExt": "http://iptc.org/std/Iptc4xmpExt/2008-02-29/", - "dc" : "http://purl.org/dc/elements/1.1/", - "photoshop" : "http://ns.adobe.com/photoshop/1.0/", - "plus" : "http://ns.useplus.org/ldf/xmp/1.0/", - "xmp" : "http://ns.adobe.com/xap/1.0/", - "xmpDM" : "http://ns.adobe.com/xmp/1.0/DynamicMedia/", - "xmpRights" : "http://ns.adobe.com/xap/1.0/rights/" - }, - "photoshop:DateCreated": "Aug 31, 2022", - "dc:creator": [ "Julie Smith" ], - "Iptc4xmpExt:DigitalSourceType": "https://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture", - "dc:rights": "Copyright (C) 2022 Example Photo Agency. All Rights Reserved.", - "photoshop:Credit": "Julie Smith/Example Photo Agency via Example Distributor", - "plus:licensor": [ - { - "plus:LicensorName": "Example Photo Agency", - "plus:LicensorURL": "http://examplephotoagency.com/images/" - } - ], - "xmpRights:WebStatement": "http://examplephotoagency.com/terms.html", - "xmpRights:UsageTerms": [ - "Not for online publication. Germany OUT" - ], - "Iptc4xmpExt:LocationCreated": { - "Iptc4xmpExt:City": "San Francisco" - }, - "Iptc4xmpExt:PersonInImage": [ - "Erika Fictional" - ], - "Iptc4xmpCore:AltTextAccessibility": "Photo of Erika Fictional standing in front of the Golden Gate Bridge at sunset." - } - }, - ... -] -``` - -### 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. - -| 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 [C2PA Technical Specification](https://cawg.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_training_and_data_mining). - -For example: - -```json -"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." - } - } - } - } - ... -] -``` ## C2PA standard assertions @@ -221,7 +48,7 @@ The CAI SDK handles assertions for thumbnails, content bindings, and ingredients ### 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](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_binding_to_content). +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](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_binding_to_content). :::note The CAI SDK writes content bindings assertions, so normally you don't need to write them, just read them. @@ -386,7 +213,7 @@ For example: The old `ingredientId` field is deprecated. ::: -For more information on action parameters, see the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_parameters). +For more information on action parameters, see the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_parameters). #### The instance_id property @@ -452,10 +279,184 @@ Should this now be only for v2 actions, and then move info on v1 actions to [Rea -This documentation covers C2PA v1 actions. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_actions) also describes expanded v2 actions. V1 actions are fully specified in the actions array. However, a v2 action may either be specified by an element of the actions array or from an element in the templates array with the same action name. +This documentation covers C2PA v1 actions. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) also describes expanded v2 actions. V1 actions are fully specified in the actions array. However, a v2 action may either be specified by an element of the actions array or from an element in the templates array with the same action name. There are some additional differences between v1 and v2 actions, for example in v2, `softwareAgent` is a [ClaimGeneratorInfo](json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. The CAI APIs can read all v2 actions and write most v2 actions. +## CAWG metadata assertions + +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](https://cawg.io/metadata/1.1/#_assertion_definition) technical specification. + +Metadata assertions must include one or more `@context` properties in the `data` object, as explained in the [JSON-LD](https://www.w3.org/TR/json-ld/#the-context) specification. Follow the examples shown in each section. + +| Assertion | Label | Description | +|-----------|-------|-------------| +| [Creative work](#creative-work-assertion) | `stds.schema-org.CreativeWork` | Indicates the asset is the product of creative effort. | +| [Exif information](#exif-assertion) | `stds.exif` | Camera information such as maker, lens stored in Exchangeable image file format (Exif). | +| [IPTC photo and video metadata](#iptc-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](#do-not-train-assertion) | `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`. | + +### Creative work assertion + +A creative work assertion states that an asset was the product of creative effort, such as an original photograph or artwork. [Schema.org](https://schema.org/) provides a set of types and metadata fields, including [CreativeWork](https://schema.org/CreativeWork), which describes a representation of creative effort. This assertion provides information about the asset, including who created it and the date/time of publication. + +A creative work assertion has the label `stds.schema-org.CreativeWork`. + +For example: + +```json +... +"assertions": [ + ... + { + "label": "stds.schema-org.CreativeWork", + "data": { + "@context": "https://schema.org", + "@type": "CreativeWork", + "url": "https://stock.adobe.com/615559889" + }, + "kind": "Json" + }, + ... +] +``` + +### 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](https://www.cipa.jp/std/documents/download_e.html?DC-008-Translation-2019-E). + +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: + +```json +"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](https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata) and [Video Metadata Standard](https://www.iptc.org/standards/video-metadata-hub/recommendation/) 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 specify whether permission is granted to use an asset in data mining or AI/ML training. Instead use the C2PA ["do not train" assertion](#do-not-train-assertion). +::: + +For a summary reference to IPTC metadata properties, see [IPTC properties](iptc-properties). + +See also: +- [Exploring c2patool and IPTC Photo Metadata](https://iptc.atlassian.net/wiki/spaces/PMD/pages/613613569/Exploring+c2patool+and+IPTC+Photo+Metadata) (Aug 2022). +- [IPTC Photo Metadata User Guide](https://www.iptc.org/std/photometadata/documentation/userguide/) + +For example: + +```json +... +"assertions": [ + ... + { + "label": "stds.iptc", + "data": { + "@context" : { + "Iptc4xmpCore": "http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/", + "Iptc4xmpExt": "http://iptc.org/std/Iptc4xmpExt/2008-02-29/", + "dc" : "http://purl.org/dc/elements/1.1/", + "photoshop" : "http://ns.adobe.com/photoshop/1.0/", + "plus" : "http://ns.useplus.org/ldf/xmp/1.0/", + "xmp" : "http://ns.adobe.com/xap/1.0/", + "xmpDM" : "http://ns.adobe.com/xmp/1.0/DynamicMedia/", + "xmpRights" : "http://ns.adobe.com/xap/1.0/rights/" + }, + "photoshop:DateCreated": "Aug 31, 2022", + "dc:creator": [ "Julie Smith" ], + "Iptc4xmpExt:DigitalSourceType": "https://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture", + "dc:rights": "Copyright (C) 2022 Example Photo Agency. All Rights Reserved.", + "photoshop:Credit": "Julie Smith/Example Photo Agency via Example Distributor", + "plus:licensor": [ + { + "plus:LicensorName": "Example Photo Agency", + "plus:LicensorURL": "http://examplephotoagency.com/images/" + } + ], + "xmpRights:WebStatement": "http://examplephotoagency.com/terms.html", + "xmpRights:UsageTerms": [ + "Not for online publication. Germany OUT" + ], + "Iptc4xmpExt:LocationCreated": { + "Iptc4xmpExt:City": "San Francisco" + }, + "Iptc4xmpExt:PersonInImage": [ + "Erika Fictional" + ], + "Iptc4xmpCore:AltTextAccessibility": "Photo of Erika Fictional standing in front of the Golden Gate Bridge at sunset." + } + }, + ... +] +``` + +### 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. + +| 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](https://cawg.io/training-and-data-mining/1.1/#_assertion_definition) technical specification. + +For example: + +```json +"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](https://en.wikipedia.org/wiki/Reverse_domain_name_notation) syntax, for example `com.adobe.product-foo.bar`. diff --git a/docs/manifest/legacy-assertions.md b/docs/manifest/legacy-assertions.md index 61f90fb..3510946 100644 --- a/docs/manifest/legacy-assertions.md +++ b/docs/manifest/legacy-assertions.md @@ -4,8 +4,9 @@ title: Reading old manifest data --- The latest C2PA technical specification is [version 2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html). CAI recommends that applications: + - Write manifest data that conforms to this version. -- Read and validate manifest data from content credentials from applications that implemented earlier versions of the C2PA technical specification. This ensures that your application is "backward-compatible" and can still validate assets that had claims written in the past. +- Read and validate manifest data that conforms to earlier versions of the C2PA technical specification. This ensures that your application is "backward-compatible" and can still validate assets that had claims written in the past.
From 937704f02147214e9a3c99a481c0075707ea9d7e Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 12 Jun 2025 15:08:02 -0700 Subject: [PATCH 04/21] Restructuring content into sections for reading and writing manifest data --- docs/manifest/json-ref/index.md | 9 +---- docs/manifest/legacy-assertions.md | 21 ---------- docs/manifest/legacy.md | 17 ++++++++ docs/manifest/reading.md | 13 ++++++ docs/manifest/writing.md | 9 +++++ sidebars.js | 64 +++++++++++++++++------------- 6 files changed, 76 insertions(+), 57 deletions(-) delete mode 100644 docs/manifest/legacy-assertions.md create mode 100644 docs/manifest/legacy.md create mode 100644 docs/manifest/reading.md create mode 100644 docs/manifest/writing.md diff --git a/docs/manifest/json-ref/index.md b/docs/manifest/json-ref/index.md index 17f3fe9..9932d9d 100644 --- a/docs/manifest/json-ref/index.md +++ b/docs/manifest/json-ref/index.md @@ -6,11 +6,4 @@ pagination_next: null pagination_prev: null --- -The [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_manifests) describes a manifest with a binary structure in JPEG universal metadata box format ([JUMBF](https://www.iso.org/standard/84635.html)) that includes JSON as well as binary data for things like encryption keys and thumbnail images. Because the binary structure is hard to understand and program to, the SDK defines a JSON manifest structure that's a declarative language for representing and creating a binary manifest. - -The JSON manifest is an abstract translation layer that's easier to understand than the binary format. It can describe everything in the underlying binary format except for binary data such as thumbnails that are included by a structure called a _resource reference_. To generate a binary manifest, the SDK assembles all the JSON objects, resource references, and ingredients defined, and then converts them into different assertions and other objects as required. - -These JSON references are generated from the JSON schemas for [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) and [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) objects (_structs_ in Rust terminology): - -- [ManifestDefinition](manifest-def.mdx): Defines a manifest and builds a manifest store. -- [Reader](reader.mdx): Reads and validates a manifest. \ No newline at end of file +No longer used. \ No newline at end of file diff --git a/docs/manifest/legacy-assertions.md b/docs/manifest/legacy-assertions.md deleted file mode 100644 index 3510946..0000000 --- a/docs/manifest/legacy-assertions.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -id: legacy-manifests -title: Reading old manifest data ---- - -The latest C2PA technical specification is [version 2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html). CAI recommends that applications: - -- Write manifest data that conforms to this version. -- Read and validate manifest data that conforms to earlier versions of the C2PA technical specification. This ensures that your application is "backward-compatible" and can still validate assets that had claims written in the past. - - -
- -`c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. - -`SoftwareAgent` is now a structure - -`digitalSourceType` is now required on every ingredient, previously it was not. - -For READING old claims (only) … v1 actions and ingredients -
diff --git a/docs/manifest/legacy.md b/docs/manifest/legacy.md new file mode 100644 index 0000000..04084a5 --- /dev/null +++ b/docs/manifest/legacy.md @@ -0,0 +1,17 @@ +--- +id: legacy-manifests +title: Reading legacy manifest data +--- + +An application should write manifest data that conforms to the recent [version 2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html) C2PA technical specification, but should be abel to read and validate manifest data that conforms to earlier versions of the specification. This ensures that your application is "backward-compatible" and can still validate older assets with claims that were written in the past. + +
+ +`c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. + +`SoftwareAgent` is now a structure + +`digitalSourceType` is now required on every ingredient, previously it was not. + +For READING old claims (only) … v1 actions and ingredients +
diff --git a/docs/manifest/reading.md b/docs/manifest/reading.md new file mode 100644 index 0000000..27abedf --- /dev/null +++ b/docs/manifest/reading.md @@ -0,0 +1,13 @@ +--- +id: reading +title: Reading and validating manifest data +--- + +Use a [Reader](json-ref/reader.mdx) structure when reading and validating manifest data. The Rust library and other language libraries provide methods and objects for working with this structure. +This JSON reference is generated from the JSON schema for [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) objects (_struct_ in Rust terminology). + +- [Ingredients](manifest/ingredients.md) +- [CAWG identity assertions](manifest/cawg-id.md) +- [Reading legacy manifest data](manifest/legacy.md) +- [Validating manifests](manifest/validation.md) +- [Reader JSON reference](manifest/json-ref/reader.mdx) diff --git a/docs/manifest/writing.md b/docs/manifest/writing.md new file mode 100644 index 0000000..2b7b2e4 --- /dev/null +++ b/docs/manifest/writing.md @@ -0,0 +1,9 @@ +--- +id: writing +title: Building and writing manifest data +--- + +Use a [ManifestDefinition](json-ref/manifest-def.mdx) structure to define and construct manifest data for writing. The Rust library and other language libraries provide methods and objects for working with this structure. This JSON reference is generated from the JSON schema for [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) object (_struct_ in Rust terminology). + +- [Assertions and actions](manifest/assertions-actions.md) +- [ManifestDefinition JSON reference](manifest/json-ref/manifest-def.mdx) diff --git a/sidebars.js b/sidebars.js index 40b3635..071c338 100644 --- a/sidebars.js +++ b/sidebars.js @@ -29,51 +29,59 @@ const sidebars = { }, { type: 'category', - label: 'Understanding manifests', + label: 'Working with manifests', link: { type: 'doc', id: 'manifest/understanding-manifest' }, collapsed: true, items: [ { - type: 'doc', - id: 'manifest/assertions-actions', - }, - { - type: 'doc', - id: 'manifest/ingredients', - }, - { - type: 'doc', - id: 'manifest/manifest-validation', - }, - { - type: 'doc', - id: 'manifest/cawg-id', - }, - { - type: 'doc', - id: 'manifest/legacy-manifests', - }, - { - type: 'doc', - id: 'manifest/manifest-examples', - label: 'Examples', + type: 'category', + label: 'Reading manifest data', + link: { type: 'doc', id: 'manifest/reading' }, + collapsed: true, + items: [ + { + type: 'doc', + id: 'manifest/ingredients', + }, + { + type: 'doc', + id: 'manifest/cawg-id', + }, + { + type: 'doc', + id: 'manifest/legacy-manifests', + }, + { + type: 'doc', + id: 'manifest/manifest-validation', + }, + { + type: 'doc', + id: 'manifest/json-ref/reader', + }, + ], }, { type: 'category', - label: 'JSON reference', - link: { type: 'doc', id: 'manifest/json-ref/index' }, + label: 'Writing manifest data', + link: { type: 'doc', id: 'manifest/writing' }, collapsed: true, items: [ { type: 'doc', - id: 'manifest/json-ref/manifest-def', + id: 'manifest/assertions-actions', }, { type: 'doc', - id: 'manifest/json-ref/reader', + id: 'manifest/json-ref/manifest-def', }, ], }, + { + type: 'doc', + id: 'manifest/manifest-examples', + label: 'Examples', + }, ], }, { From 4feff2c67c016dcfb2dbc406e6c543b69e992c1a Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 18 Jun 2025 16:50:47 -0700 Subject: [PATCH 05/21] edits --- docs/manifest/assertions-actions.md | 13 ++++ docs/manifest/legacy.md | 98 +++++++++++++++++++++++++++++ 2 files changed, 111 insertions(+) diff --git a/docs/manifest/assertions-actions.md b/docs/manifest/assertions-actions.md index 9bb4ef3..20cc748 100644 --- a/docs/manifest/assertions-actions.md +++ b/docs/manifest/assertions-actions.md @@ -75,6 +75,19 @@ For example, the `c2pa.hash.data` assertion shown in the [detailed manifest exam ] ``` +### Timestamp assertion + +See . + +### Metadata assertions + +See . + +These new metadata assertions replace the old Exif and IPTC assertions. + +### Update assertions + + ### 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](json-ref/manifest-def.mdx#assertiondefinition) objects. For example: diff --git a/docs/manifest/legacy.md b/docs/manifest/legacy.md index 04084a5..4fb4f4c 100644 --- a/docs/manifest/legacy.md +++ b/docs/manifest/legacy.md @@ -15,3 +15,101 @@ An application should write manifest data that conforms to the recent [version 2 For READING old claims (only) … v1 actions and ingredients
+ +## Legacy metadata assertions + +Starting with version 2.2 the C2PA specification, provides for a category of metadata assertions that have a standardized serialization. Earlier versions had individual assertions for each metadata standard, as detailed below. + +### 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](https://www.cipa.jp/std/documents/download_e.html?DC-008-Translation-2019-E). + +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: + +```json +"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](https://www.iptc.org/std/photometadata/specification/IPTC-PhotoMetadata) and [Video Metadata Standard](https://www.iptc.org/standards/video-metadata-hub/recommendation/) 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 specify whether permission is granted to use an asset in data mining or AI/ML training. Instead use the C2PA ["do not train" assertion](#do-not-train-assertion). +::: + +For a summary reference to IPTC metadata properties, see [IPTC properties](iptc-properties). + +See also: +- [Exploring c2patool and IPTC Photo Metadata](https://iptc.atlassian.net/wiki/spaces/PMD/pages/613613569/Exploring+c2patool+and+IPTC+Photo+Metadata) (Aug 2022). +- [IPTC Photo Metadata User Guide](https://www.iptc.org/std/photometadata/documentation/userguide/) + +For example: + +```json +... +"assertions": [ + ... + { + "label": "stds.iptc", + "data": { + "@context" : { + "Iptc4xmpCore": "http://iptc.org/std/Iptc4xmpCore/1.0/xmlns/", + "Iptc4xmpExt": "http://iptc.org/std/Iptc4xmpExt/2008-02-29/", + "dc" : "http://purl.org/dc/elements/1.1/", + "photoshop" : "http://ns.adobe.com/photoshop/1.0/", + "plus" : "http://ns.useplus.org/ldf/xmp/1.0/", + "xmp" : "http://ns.adobe.com/xap/1.0/", + "xmpDM" : "http://ns.adobe.com/xmp/1.0/DynamicMedia/", + "xmpRights" : "http://ns.adobe.com/xap/1.0/rights/" + }, + "photoshop:DateCreated": "Aug 31, 2022", + "dc:creator": [ "Julie Smith" ], + "Iptc4xmpExt:DigitalSourceType": "https://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture", + "dc:rights": "Copyright (C) 2022 Example Photo Agency. All Rights Reserved.", + "photoshop:Credit": "Julie Smith/Example Photo Agency via Example Distributor", + "plus:licensor": [ + { + "plus:LicensorName": "Example Photo Agency", + "plus:LicensorURL": "http://examplephotoagency.com/images/" + } + ], + "xmpRights:WebStatement": "http://examplephotoagency.com/terms.html", + "xmpRights:UsageTerms": [ + "Not for online publication. Germany OUT" + ], + "Iptc4xmpExt:LocationCreated": { + "Iptc4xmpExt:City": "San Francisco" + }, + "Iptc4xmpExt:PersonInImage": [ + "Erika Fictional" + ], + "Iptc4xmpCore:AltTextAccessibility": "Photo of Erika Fictional standing in front of the Golden Gate Bridge at sunset." + } + }, + ... +] +``` \ No newline at end of file From 0273169a8be04af1f5792ac57f119323f527d83f Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 19 Jun 2025 11:40:06 -0700 Subject: [PATCH 06/21] wip reorg --- docs/manifest/assertions-actions.md | 40 ++++++++++++++++------------- docs/manifest/legacy.md | 23 +++++++++-------- 2 files changed, 35 insertions(+), 28 deletions(-) diff --git a/docs/manifest/assertions-actions.md b/docs/manifest/assertions-actions.md index 20cc748..b1bce9f 100644 --- a/docs/manifest/assertions-actions.md +++ b/docs/manifest/assertions-actions.md @@ -26,6 +26,24 @@ The standard form of an assertion in a JSON manifest is: ] ``` +### Changes from earlier releases + +
+Changes include: +- `c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. +- `SoftwareAgent` is a [ClaimGeneratorInfo](json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. +- `digitalSourceType` is now required on every ingredient, previously it was not. +- Actions are now V2 actions +- Ingredients are now V2 ingredients +
+ +#### V2 actions + +The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) describes expanded v2 actions. While v1 actions are fully specified in the actions array v2 actions may either be specified by an element of the actions array or 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. + ## C2PA standard assertions @@ -79,12 +97,6 @@ For example, the `c2pa.hash.data` assertion shown in the [detailed manifest exam See . -### Metadata assertions - -See . - -These new metadata assertions replace the old Exif and IPTC assertions. - ### Update assertions @@ -284,19 +296,11 @@ For example, the following action identifies that the `c2pa.opened` action was p ... ``` -#### V2 actions - -
- -Should this now be only for v2 actions, and then move info on v1 actions to [Reading old manifest data](legacy-manifests)? - -
- -This documentation covers C2PA v1 actions. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) also describes expanded v2 actions. V1 actions are fully specified in the actions array. However, a v2 action may either be specified by an element of the actions array or from an element in the templates array with the same action name. +## CAWG metadata assertions -There are some additional differences between v1 and v2 actions, for example in v2, `softwareAgent` is a [ClaimGeneratorInfo](json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. The CAI APIs can read all v2 actions and write most v2 actions. +Starting with version 2.2, the C2PA specification provides for a category of metadata assertions that have a standardized serialization. These new metadata assertions replace the old Exif and IPTC assertions. -## CAWG metadata assertions +See . 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](https://cawg.io/metadata/1.1/#_assertion_definition) technical specification. @@ -428,7 +432,7 @@ For example: ] ``` -### Training and data mining assertion +## 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. diff --git a/docs/manifest/legacy.md b/docs/manifest/legacy.md index 4fb4f4c..e4d9b62 100644 --- a/docs/manifest/legacy.md +++ b/docs/manifest/legacy.md @@ -3,22 +3,15 @@ id: legacy-manifests title: Reading legacy manifest data --- -An application should write manifest data that conforms to the recent [version 2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html) C2PA technical specification, but should be abel to read and validate manifest data that conforms to earlier versions of the specification. This ensures that your application is "backward-compatible" and can still validate older assets with claims that were written in the past. +As much as possible, an application should **write** manifest data that conforms to the recent [version 2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html) C2PA technical specification, but should be able to **read and validate** manifest data that conforms to earlier versions of the specification. This ensures that your application is "backward-compatible" and can still validate older assets with claims that were written in the past.
- -`c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. - -`SoftwareAgent` is now a structure - -`digitalSourceType` is now required on every ingredient, previously it was not. - For READING old claims (only) … v1 actions and ingredients
## Legacy metadata assertions -Starting with version 2.2 the C2PA specification, provides for a category of metadata assertions that have a standardized serialization. Earlier versions had individual assertions for each metadata standard, as detailed below. +Older versions of the SDK had individual assertions for each metadata standard, as detailed below. ### Exif assertion @@ -112,4 +105,14 @@ For example: }, ... ] -``` \ No newline at end of file +``` + +## Training and data mining assertion + +Old manifests may have training and data mining assertions with the following entry keys: +- `c2pa.data_mining` +- `c2pa.ai_training` +- `c2pa.ai_generative_training` +- `c2pa.ai_inference` + +These assertions have been replaced by [CAWG training and data mining assertions](assertions-actions.md#cawg-training-and-data-mining-assertion) with `cawg.*` entry keys. \ No newline at end of file From d170f8915b1b8b253529a9b1d6ee42e0ac2c427d Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 14 Jul 2025 08:52:40 -0700 Subject: [PATCH 07/21] wip save --- docs/manifest/assertions-actions.md | 56 +++++-------- docs/manifest/cawg-id.md | 4 + docs/manifest/ingredients-reading.md | 119 +++++++++++++++++++++++++++ docs/manifest/ingredients.md | 16 ++-- docs/manifest/legacy.md | 33 ++++++-- sidebars.js | 8 +- 6 files changed, 179 insertions(+), 57 deletions(-) create mode 100644 docs/manifest/ingredients-reading.md diff --git a/docs/manifest/assertions-actions.md b/docs/manifest/assertions-actions.md index b1bce9f..b213c09 100644 --- a/docs/manifest/assertions-actions.md +++ b/docs/manifest/assertions-actions.md @@ -29,20 +29,27 @@ The standard form of an assertion in a JSON manifest is: ### Changes from earlier releases
+ Changes include: - `c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. - `SoftwareAgent` is a [ClaimGeneratorInfo](json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. -- `digitalSourceType` is now required on every ingredient, previously it was not. + - Actions are now V2 actions - Ingredients are now V2 ingredients +
#### V2 actions The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) describes expanded v2 actions. While v1 actions are fully specified in the actions array v2 actions may either be specified by an element of the actions array or 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. +
+ +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 its actions array. However, in v2, an 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. ## C2PA standard assertions @@ -52,7 +59,7 @@ The C2PA Technical Specification defines a [set of standard assertions](https:// The following table summarizes some of the most important standard assertions.
-What other c2pa std assertions should we call out? +What other c2pa stadard assertions should we call out?
| Assertion | Label | Description | @@ -93,12 +100,15 @@ For example, the `c2pa.hash.data` assertion shown in the [detailed manifest exam ] ``` -### Timestamp assertion + ### Actions @@ -298,9 +308,7 @@ For example, the following action identifies that the `c2pa.opened` action was p ## CAWG metadata assertions -Starting with version 2.2, the C2PA specification provides for a category of metadata assertions that have a standardized serialization. These new metadata assertions replace the old Exif and IPTC assertions. - -See . +Starting with version 2.2, the C2PA specification provides for a category of [metadata assertions](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_metadata) 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](https://cawg.io/metadata/1.1/#_assertion_definition) technical specification. @@ -313,31 +321,6 @@ Metadata assertions must include one or more `@context` properties in the `data` | [IPTC photo and video metadata](#iptc-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](#do-not-train-assertion) | `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`. | -### Creative work assertion - -A creative work assertion states that an asset was the product of creative effort, such as an original photograph or artwork. [Schema.org](https://schema.org/) provides a set of types and metadata fields, including [CreativeWork](https://schema.org/CreativeWork), which describes a representation of creative effort. This assertion provides information about the asset, including who created it and the date/time of publication. - -A creative work assertion has the label `stds.schema-org.CreativeWork`. - -For example: - -```json -... -"assertions": [ - ... - { - "label": "stds.schema-org.CreativeWork", - "data": { - "@context": "https://schema.org", - "@type": "CreativeWork", - "url": "https://stock.adobe.com/615559889" - }, - "kind": "Json" - }, - ... -] -``` - ### 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](https://www.cipa.jp/std/documents/download_e.html?DC-008-Translation-2019-E). @@ -376,7 +359,7 @@ An IPTC assertion has the label `stds.iptc` and is stored in JSON-LD format usin 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 specify whether permission is granted to use an asset in data mining or AI/ML training. Instead use the C2PA ["do not train" assertion](#do-not-train-assertion). +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](#cawg-training-and-data-mining-assertion). ::: For a summary reference to IPTC metadata properties, see [IPTC properties](iptc-properties). @@ -436,6 +419,11 @@ For example: 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. +::: + + | 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` | diff --git a/docs/manifest/cawg-id.md b/docs/manifest/cawg-id.md index 8f192d2..9980239 100644 --- a/docs/manifest/cawg-id.md +++ b/docs/manifest/cawg-id.md @@ -10,6 +10,10 @@ There are two different ways to provide identity assertions: - Using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures) to sign the identity claims. Enterprises or large organizations can use this approach to assert their identity in a particular trust ecosystem; for example, a news organization or publisher. The SDK can validate and sign these claims. - Using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation). Individuals can use this approach to document their role in creating an asset by using identity signals collected and verified by a third-party aggregator. The SDK can validate these claims only. Signing is not supported. +SDK only does x.509 signer + +Adobe apps use an identity claim agg. + :::note The SDK can validate claims for both kinds of identity assertions, but can only sign claims for identity assertions using an X.509 certificate. ::: diff --git a/docs/manifest/ingredients-reading.md b/docs/manifest/ingredients-reading.md new file mode 100644 index 0000000..c81fe23 --- /dev/null +++ b/docs/manifest/ingredients-reading.md @@ -0,0 +1,119 @@ +--- +id: reading-ingredients +title: Reading ingredient data +--- + +## Overview + +The C2PA specification defines three kinds of ingredients: +- V1, with label `c2pa.ingredient`. +- V2, with label `c2pa.ingredient.v2`. +- V3, with label `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. + +:::note +The C2PA Technical Specification describes _ingredient assertions_ but the CAI SDK treats ingredients separately as their own objects in the JSON manifest rather than as a type of assertion. +::: + +## Ingredient objects + +The `ingredients` array contains an element for each ingredient used to create an asset. When an ingredient itself has Content Credentials, those manifests are included in the composed asset's manifest store to keep the provenance data intact. + +The `ingredients` array contains an [ingredient object](json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. + +Other important properties of the ingredient object include: +- `format`: MIME type of the source file (optional). +- `document_id` (optoinal) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. +- `thumbnail`: Object with properties that identify the thumbnail image. +- `active_manifest`: For an ingredient with a manifest store, the label of the active manifest. +- `relationship`: One of `parentOf`, `componentOf`, or `inputTo`. See [Relationship](#relationship) below. + +For example: + +```json + "ingredients": [ + ... + { + "title": "CAI.jpg", + "format": "image/jpeg", + "instance_id": "xmp:iid:315e20bf-10da-4f44-85f4-6de350bfe688", + "thumbnail": { + "format": "image/jpeg", + "identifier": "xmp-iid-315e20bf-10da-4f44-85f4-6de350bfe688.jpg" + }, + "relationship": "componentOf", + "active_manifest": "contentauth:urn:uuid:8bb8ad50-ef2f-4f75-b709-a0e302d58019" + } + ] +``` + +### Relationship + +The ingredient object's `relationship` property describes its relationship to the current asset. This property can have one of three values, as described in the table below. + +| Value of `relationship` | Description | +|--------------------------|-------------| +| `parentOf` | The current asset is a derived asset or asset rendition of this ingredient. This relationship value is also used with update manifests. There can be at most one parent ingredient in a manifest. | +| `componentOf` | This ingredient is one of the assets that composes the current asset. | +| `inputTo` | This ingredient was used as input to a computational process, such as an AI/ML model, that led to the creation or modification of this asset. | + +## Validation results + +_This is now validation results_ + +json-ref/reader#validationresults + +When ingredients are added, the SDK validates their Content Credentials (if any). However, the validation status of an ingredient does not imply anything about the validation status of the composed asset containing the ingredient. In other words: +- A composed asset's Content Credentials may be valid, but one or more of its ingredients may have invalid Content Credentials. For example, test file [adobe-20220124-XCA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-XCA.jpg) +- A composed asset's Content Credentials may be invalid, but one or more of its ingredients may have valid Content Credentials. For example, test file [adobe-20220124-CIE-sig-CA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CIE-sig-CA.jpg). + +:::note +Ingredient certificates are validated when they are added to the manifest store, NOT during validation of the composed asset. +::: + +### Example of ingredient with invalid credentials + +As noted above, the test file [adobe-20220124-CIE-sig-CA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CIE-sig-CA.jpg) has an ingredient with invalid Content Credentials, as shown in this snippet from the manifest store: + +```json +... +{ + "active_manifest": "contentauth:urn:uuid:40f2636a-402c-4792-9da4-644a63d1f7d0", + "manifests": { + "contentauth:urn:uuid:40f2636a-402c-4792-9da4-644a63d1f7d0": { + ... + "ingredients": [ + { + "title": "E-sig-CA.jpg", + "format": "image/jpeg", + "instance_id": "xmp:iid:81ca15f6-4ed0-422a-96cb-3e8014e29ac6", + "thumbnail": { + "format": "image/jpeg", + "identifier": "xmp-iid-81ca15f6-4ed0-422a-96cb-3e8014e29ac6.jpg" + }, + "relationship": "componentOf", + "active_manifest": "contentauth:urn:uuid:04cdf4ec-f713-4e47-a8d6-7af56501ce4b", + "validation_status": [ + { + "code": "timeStamp.mismatch", + "url": "Cose_Sign1", + "explanation": "timestamp message imprint did not match" + }, + { + "code": "claimSignature.mismatch", + "url": "self#jumbf=/c2pa/contentauth:urn:uuid:04cdf4ec-f713-4e47-a8d6-7af56501ce4b/c2pa.signature", + "explanation": "claim signature is not valid" + } + ... + ] + } + ] +``` + +## Examples + +The [C2PA public-testfiles](https://c2pa.org/public-testfiles/image/) repository has several examples of images with multiple ingredients: +- [Image with two ingredients](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CAICA.jpg); [View JSON manifest store](https://c2pa.org/public-testfiles/image/jpeg/manifests/adobe-20220124-CAICA/manifest_store.json) +- [Image with seven ingredients](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CAIAIIICAICIICAIICICA.jpg); [View JSON manifest store](https://c2pa.org/public-testfiles/image/jpeg/manifests/adobe-20220124-CAIAIIICAICIICAIICICA/manifest_store.json) + + + diff --git a/docs/manifest/ingredients.md b/docs/manifest/ingredients.md index 769bdc6..b9e009e 100644 --- a/docs/manifest/ingredients.md +++ b/docs/manifest/ingredients.md @@ -3,18 +3,12 @@ id: ingredients title: Ingredients --- -
- -`digitalSourceType` is now required on every ingredient, previously it was not. - -
- ## Overview Digital assets are often not created entirely from scratch, but instead created from one or more existing assets, for example placing an image into a layer in Photoshop. Such constituent assets are called _ingredients_.
-This should now cover v2 ingredients, right? +This should now cover v3 ingredients, which is what people should be writing now.
This documentation covers C2PA v1 ingredients. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_ingredient) also describes improved v2 ingredients. @@ -30,8 +24,8 @@ The `ingredients` array contains an element for each ingredient used to create a The `ingredients` array contains an [ingredient object](json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. Other important properties of the ingredient object include: -- `format`: MIME type of the source file. -- `document_id` and `instance_id` which are derived from the ingredient asset's XMP metadata. +- `format`: MIME type of the source file (optional). +- `document_id` (optoinal) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. - `thumbnail`: Object with properties that identify the thumbnail image. - `active_manifest`: For an ingredient with a manifest store, the label of the active manifest. - `relationship`: One of `parentOf`, `componentOf`, or `inputTo`. See [Relationship](#relationship) below. @@ -65,7 +59,9 @@ The ingredient object's `relationship` property describes its relationship to th | `componentOf` | This ingredient is one of the assets that composes the current asset. | | `inputTo` | This ingredient was used as input to a computational process, such as an AI/ML model, that led to the creation or modification of this asset. | -## Validation status +## Validation results + +See [Validation results](json-ref/reader#validationresults) in the manifest JSON reference. When ingredients are added, the SDK validates their Content Credentials (if any). However, the validation status of an ingredient does not imply anything about the validation status of the composed asset containing the ingredient. In other words: - A composed asset's Content Credentials may be valid, but one or more of its ingredients may have invalid Content Credentials. For example, test file [adobe-20220124-XCA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-XCA.jpg) diff --git a/docs/manifest/legacy.md b/docs/manifest/legacy.md index e4d9b62..a889831 100644 --- a/docs/manifest/legacy.md +++ b/docs/manifest/legacy.md @@ -50,15 +50,7 @@ An IPTC assertion has the label `stds.iptc` and is stored in JSON-LD format usin 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 specify whether permission is granted to use an asset in data mining or AI/ML training. Instead use the C2PA ["do not train" assertion](#do-not-train-assertion). -::: - -For a summary reference to IPTC metadata properties, see [IPTC properties](iptc-properties). - -See also: -- [Exploring c2patool and IPTC Photo Metadata](https://iptc.atlassian.net/wiki/spaces/PMD/pages/613613569/Exploring+c2patool+and+IPTC+Photo+Metadata) (Aug 2022). -- [IPTC Photo Metadata User Guide](https://www.iptc.org/std/photometadata/documentation/userguide/) +See also [IPTC Photo Metadata User Guide](https://www.iptc.org/std/photometadata/documentation/userguide/). For example: @@ -107,6 +99,29 @@ For example: ] ``` +### Creative work assertion + +The deprecated creative work metadata assertion has the label `stds.schema-org.CreativeWork`. + +For example: + +```json +... +"assertions": [ + ... + { + "label": "stds.schema-org.CreativeWork", + "data": { + "@context": "https://schema.org", + "@type": "CreativeWork", + "url": "https://stock.adobe.com/615559889" + }, + "kind": "Json" + }, + ... +] +``` + ## Training and data mining assertion Old manifests may have training and data mining assertions with the following entry keys: diff --git a/sidebars.js b/sidebars.js index 071c338..26ef1be 100644 --- a/sidebars.js +++ b/sidebars.js @@ -43,10 +43,6 @@ const sidebars = { type: 'doc', id: 'manifest/ingredients', }, - { - type: 'doc', - id: 'manifest/cawg-id', - }, { type: 'doc', id: 'manifest/legacy-manifests', @@ -71,6 +67,10 @@ const sidebars = { type: 'doc', id: 'manifest/assertions-actions', }, + { + type: 'doc', + id: 'manifest/cawg-id', + }, { type: 'doc', id: 'manifest/json-ref/manifest-def', From c3dd874134e2862cb9610df6d85cc58295d7c9a5 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 17 Jul 2025 14:02:47 -0700 Subject: [PATCH 08/21] Reorg files and add some new files to cover all reading/writing cases separately --- docs/manifest/ingredients.md | 120 -------------- docs/manifest/reading.md | 13 -- .../{ => reading}/ingredients-reading.md | 14 +- docs/manifest/{ => reading}/legacy.md | 2 +- docs/manifest/reading/reading-cawg-id.md | 155 ++++++++++++++++++ docs/manifest/reading/reading.md | 12 ++ docs/manifest/{ => reading}/validation.md | 12 +- docs/manifest/understanding.md | 30 ++-- docs/manifest/writing.md | 9 - .../{ => writing}/assertions-actions.md | 15 +- docs/manifest/{ => writing}/cawg-id.md | 8 +- docs/manifest/writing/ingredients.md | 68 ++++++++ docs/manifest/writing/writing.md | 11 ++ sidebars.js | 22 ++- 14 files changed, 298 insertions(+), 193 deletions(-) delete mode 100644 docs/manifest/ingredients.md delete mode 100644 docs/manifest/reading.md rename docs/manifest/{ => reading}/ingredients-reading.md (90%) rename docs/manifest/{ => reading}/legacy.md (97%) create mode 100644 docs/manifest/reading/reading-cawg-id.md create mode 100644 docs/manifest/reading/reading.md rename docs/manifest/{ => reading}/validation.md (88%) delete mode 100644 docs/manifest/writing.md rename docs/manifest/{ => writing}/assertions-actions.md (98%) rename docs/manifest/{ => writing}/cawg-id.md (97%) create mode 100644 docs/manifest/writing/ingredients.md create mode 100644 docs/manifest/writing/writing.md diff --git a/docs/manifest/ingredients.md b/docs/manifest/ingredients.md deleted file mode 100644 index b9e009e..0000000 --- a/docs/manifest/ingredients.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -id: ingredients -title: Ingredients ---- - -## Overview - -Digital assets are often not created entirely from scratch, but instead created from one or more existing assets, for example placing an image into a layer in Photoshop. Such constituent assets are called _ingredients_. - -
-This should now cover v3 ingredients, which is what people should be writing now. -
- -This documentation covers C2PA v1 ingredients. The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_ingredient) also describes improved v2 ingredients. - -:::note -The C2PA Technical Specification describes _ingredient assertions_ but the CAI SDK treats ingredients separately as their own objects in the JSON manifest rather than as a type of assertion. -::: - -## Ingredient objects - -The `ingredients` array contains an element for each ingredient used to create an asset. When an ingredient itself has Content Credentials, those manifests are included in the composed asset's manifest store to keep the provenance data intact. - -The `ingredients` array contains an [ingredient object](json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. - -Other important properties of the ingredient object include: -- `format`: MIME type of the source file (optional). -- `document_id` (optoinal) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. -- `thumbnail`: Object with properties that identify the thumbnail image. -- `active_manifest`: For an ingredient with a manifest store, the label of the active manifest. -- `relationship`: One of `parentOf`, `componentOf`, or `inputTo`. See [Relationship](#relationship) below. - -For example: - -```json - "ingredients": [ - ... - { - "title": "CAI.jpg", - "format": "image/jpeg", - "instance_id": "xmp:iid:315e20bf-10da-4f44-85f4-6de350bfe688", - "thumbnail": { - "format": "image/jpeg", - "identifier": "xmp-iid-315e20bf-10da-4f44-85f4-6de350bfe688.jpg" - }, - "relationship": "componentOf", - "active_manifest": "contentauth:urn:uuid:8bb8ad50-ef2f-4f75-b709-a0e302d58019" - } - ] -``` - -### Relationship - -The ingredient object's `relationship` property describes its relationship to the current asset. This property can have one of three values, as described in the table below. - -| Value of `relationship` | Description | -|--------------------------|-------------| -| `parentOf` | The current asset is a derived asset or asset rendition of this ingredient. This relationship value is also used with update manifests. There can be at most one parent ingredient in a manifest. | -| `componentOf` | This ingredient is one of the assets that composes the current asset. | -| `inputTo` | This ingredient was used as input to a computational process, such as an AI/ML model, that led to the creation or modification of this asset. | - -## Validation results - -See [Validation results](json-ref/reader#validationresults) in the manifest JSON reference. - -When ingredients are added, the SDK validates their Content Credentials (if any). However, the validation status of an ingredient does not imply anything about the validation status of the composed asset containing the ingredient. In other words: -- A composed asset's Content Credentials may be valid, but one or more of its ingredients may have invalid Content Credentials. For example, test file [adobe-20220124-XCA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-XCA.jpg) -- A composed asset's Content Credentials may be invalid, but one or more of its ingredients may have valid Content Credentials. For example, test file [adobe-20220124-CIE-sig-CA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CIE-sig-CA.jpg). - -:::note -Ingredient certificates are validated when they are added to the manifest store, NOT during validation of the composed asset. -::: - -### Example of ingredient with invalid credentials - -As noted above, the test file [adobe-20220124-CIE-sig-CA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CIE-sig-CA.jpg) has an ingredient with invalid Content Credentials, as shown in this snippet from the manifest store: - -```json -... -{ - "active_manifest": "contentauth:urn:uuid:40f2636a-402c-4792-9da4-644a63d1f7d0", - "manifests": { - "contentauth:urn:uuid:40f2636a-402c-4792-9da4-644a63d1f7d0": { - ... - "ingredients": [ - { - "title": "E-sig-CA.jpg", - "format": "image/jpeg", - "instance_id": "xmp:iid:81ca15f6-4ed0-422a-96cb-3e8014e29ac6", - "thumbnail": { - "format": "image/jpeg", - "identifier": "xmp-iid-81ca15f6-4ed0-422a-96cb-3e8014e29ac6.jpg" - }, - "relationship": "componentOf", - "active_manifest": "contentauth:urn:uuid:04cdf4ec-f713-4e47-a8d6-7af56501ce4b", - "validation_status": [ - { - "code": "timeStamp.mismatch", - "url": "Cose_Sign1", - "explanation": "timestamp message imprint did not match" - }, - { - "code": "claimSignature.mismatch", - "url": "self#jumbf=/c2pa/contentauth:urn:uuid:04cdf4ec-f713-4e47-a8d6-7af56501ce4b/c2pa.signature", - "explanation": "claim signature is not valid" - } - ... - ] - } - ] -``` - -## Examples - -The [C2PA public-testfiles](https://c2pa.org/public-testfiles/image/) repository has several examples of images with multiple ingredients: -- [Image with two ingredients](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CAICA.jpg); [View JSON manifest store](https://c2pa.org/public-testfiles/image/jpeg/manifests/adobe-20220124-CAICA/manifest_store.json) -- [Image with seven ingredients](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CAIAIIICAICIICAIICICA.jpg); [View JSON manifest store](https://c2pa.org/public-testfiles/image/jpeg/manifests/adobe-20220124-CAIAIIICAICIICAIICICA/manifest_store.json) - - - diff --git a/docs/manifest/reading.md b/docs/manifest/reading.md deleted file mode 100644 index 27abedf..0000000 --- a/docs/manifest/reading.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -id: reading -title: Reading and validating manifest data ---- - -Use a [Reader](json-ref/reader.mdx) structure when reading and validating manifest data. The Rust library and other language libraries provide methods and objects for working with this structure. -This JSON reference is generated from the JSON schema for [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) objects (_struct_ in Rust terminology). - -- [Ingredients](manifest/ingredients.md) -- [CAWG identity assertions](manifest/cawg-id.md) -- [Reading legacy manifest data](manifest/legacy.md) -- [Validating manifests](manifest/validation.md) -- [Reader JSON reference](manifest/json-ref/reader.mdx) diff --git a/docs/manifest/ingredients-reading.md b/docs/manifest/reading/ingredients-reading.md similarity index 90% rename from docs/manifest/ingredients-reading.md rename to docs/manifest/reading/ingredients-reading.md index c81fe23..9dc11a4 100644 --- a/docs/manifest/ingredients-reading.md +++ b/docs/manifest/reading/ingredients-reading.md @@ -1,13 +1,13 @@ --- id: reading-ingredients -title: Reading ingredient data +title: Reading ingredients --- ## Overview -The C2PA specification defines three kinds of ingredients: -- V1, with label `c2pa.ingredient`. -- V2, with label `c2pa.ingredient.v2`. +Existing manifests may contain any of these three kinds of ingredients: +- V1, with label `c2pa.ingredient` (deprecated). +- V2, with label `c2pa.ingredient.v2` (deprecated). - V3, with label `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. :::note @@ -18,7 +18,7 @@ The C2PA Technical Specification describes _ingredient assertions_ but the CAI S The `ingredients` array contains an element for each ingredient used to create an asset. When an ingredient itself has Content Credentials, those manifests are included in the composed asset's manifest store to keep the provenance data intact. -The `ingredients` array contains an [ingredient object](json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. +The `ingredients` array contains an [ingredient object](manifest/json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. Other important properties of the ingredient object include: - `format`: MIME type of the source file (optional). @@ -58,9 +58,7 @@ The ingredient object's `relationship` property describes its relationship to th ## Validation results -_This is now validation results_ - -json-ref/reader#validationresults +The [ValidationResults](/docs/manifest/json-ref/reader#validationresults) object contains the the validation results for the active manifest and any changes to ingredients. When ingredients are added, the SDK validates their Content Credentials (if any). However, the validation status of an ingredient does not imply anything about the validation status of the composed asset containing the ingredient. In other words: - A composed asset's Content Credentials may be valid, but one or more of its ingredients may have invalid Content Credentials. For example, test file [adobe-20220124-XCA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-XCA.jpg) diff --git a/docs/manifest/legacy.md b/docs/manifest/reading/legacy.md similarity index 97% rename from docs/manifest/legacy.md rename to docs/manifest/reading/legacy.md index a889831..8923f12 100644 --- a/docs/manifest/legacy.md +++ b/docs/manifest/reading/legacy.md @@ -130,4 +130,4 @@ Old manifests may have training and data mining assertions with the following en - `c2pa.ai_generative_training` - `c2pa.ai_inference` -These assertions have been replaced by [CAWG training and data mining assertions](assertions-actions.md#cawg-training-and-data-mining-assertion) with `cawg.*` entry keys. \ No newline at end of file +These assertions have been replaced by [CAWG training and data mining assertions](../writing/assertions-actions.md#cawg-training-and-data-mining-assertion) with `cawg.*` entry keys. \ No newline at end of file diff --git a/docs/manifest/reading/reading-cawg-id.md b/docs/manifest/reading/reading-cawg-id.md new file mode 100644 index 0000000..24f47a7 --- /dev/null +++ b/docs/manifest/reading/reading-cawg-id.md @@ -0,0 +1,155 @@ +--- +id: reading-cawg-id +title: Reading CAWG identity assertions +--- + +The [Creator Assertions Working Group (CAWG)](https://cawg.io/) identity assertion enables a credential holder to prove control over a digital identity and to use that identity to document a content creator’s role(s) in a C2PA asset’s lifecycle. + +
+Revise to focus on reading these assertions. +
+ +The SDK can read and validate CAWG identity assertions provided: + +- Using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures) to sign the identity claims. Enterprises or large organizations can use this approach to assert their identity in a particular trust ecosystem; for example, a news organization or publisher. The SDK can validate and sign these claims. +- Using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation). Individuals can use this approach to document their role in creating an asset by using identity signals collected and verified by a third-party aggregator. The SDK can validate these claims only. Signing is not supported. + +## Identity assertions provided using an X.509 certificate + +In an identity assertion by using an X.509 certificate, the value of `signer_payload.sig_type` is `cawg.x509.cose`. The signature value must be a COSE signature as described in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures). + +## Identity assertions provided using a claim aggregator + +As defined in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_identity_claims_aggregation), an identity assertion can be signed using a trusted third-party intermediary known as a _identity claims aggregator_ to gather these signals and to restate them on their behalf. + +The identity claims aggregator: + +- Collects and verifies identity attestation claims from various identity providers such as social media sites and ID verification vendors. +- Creates a unique asset-specific credential that binds the identity attestation claims to a specific asset. + +## Identity assertion + +An identity assertion using an identity claims aggregator has this general form in JSON: + +```json +"assertions": [ + ... + { + "label": "cawg.identity", + "data": { + "@context": [ + "https://www.w3.org/ns/credentials/v2", + "https://cawg.io/identity/1.1/ica/context/" + ], + "type": [ + "VerifiableCredential", + "IdentityClaimsAggregationCredential" + ], + "issuer": "did:web:connected-identities.identity.adobe.com", + "validFrom": "2025-04-29T17:34:44Z", + "verifiedIdentities": [ + { + "type": "cawg.", + "username": "", + "uri": "", + "verifiedAt": "", + "provider": { + "id": "", + "name": "" + } + }, + ... + ] + } + } +] +``` + +### Verified identity types + +The following table describes the allowed values of the `type` property of `verifiedIdentities` array elements. + +| Value | Meaning | +|--------------|----------| +| `cawg.document_verification` | The identity provider verified one or more government-issued identity documents presented by the content creator. +| `cawg.web_site` | The content creator has proven control over a specific domain to the identity claims aggregator._ +| `cawg.affiliation` | The identity provider is attesting to the content creator’s membership in an organization. This could be a professional organization or an employment relationship. +| `cawg.social_media` | The content creator has demonstrated control over an account (typically a social media account) hosted by the identity provider. +| `cawg.crypto_wallet` | The content creator has demonstrated control over an account (typically a crypto-wallet) hosted by the identity provider. + +:::note +The above table is based on the [CAWG identity assertion technical specifications](https://cawg.io/identity/1.1/#vc-credentialsubject-verifiedidentity-type). +::: + +### Example + +```json +"assertions": [ + ... + { + "label": "cawg.identity", + "data": { + "@context": [ + "https://www.w3.org/ns/credentials/v2", + "https://cawg.io/identity/1.1/ica/context/" + ], + "type": [ + "VerifiableCredential", + "IdentityClaimsAggregationCredential" + ], + "issuer": "did:web:connected-identities.identity.adobe.com", + "validFrom": "2025-04-29T17:34:44Z", + "verifiedIdentities": [ + { + "type": "cawg.social_media", + "username": "xyz", + "uri": "https://www.instagram.com/xyz", + "verifiedAt": "2024-10-08T18:04:08Z", + "provider": { + "id": "https://instagram.com", + "name": "instagram" + } + }, + { + "type": "cawg.social_media", + "username": "xyz", + "uri": "https://www.behance.net/xyz", + "verifiedAt": "2024-10-22T19:31:17Z", + "provider": { + "id": "https://behance.net", + "name": "behance" + } + }, + { + "type": "cawg.social_media", + "username": "J Smith", + "uri": "https://www.linkedin.com/in/jsmith", + "verifiedAt": "2024-10-08T18:03:41Z", + "provider": { + "id": "https://linkedin.com", + "name": "linkedin" + } + }, + { + "type": "cawg.social_media", + "username": "xyz", + "uri": "https://twitter.com/xyz", + "verifiedAt": "2024-10-08T18:03:49Z", + "provider": { + "id": "https://twitter.com", + "name": "twitter" + } + } + ], + "credentialSchema": [ + { + "id": "https://cawg.io/identity/1.1/ica/schema/", + "type": "JSONSchema" + } + ] + } + } + ... +] +``` + diff --git a/docs/manifest/reading/reading.md b/docs/manifest/reading/reading.md new file mode 100644 index 0000000..a3bcabb --- /dev/null +++ b/docs/manifest/reading/reading.md @@ -0,0 +1,12 @@ +--- +id: reading-index +title: Reading and validating manifest data +--- + +Use a [Reader](manifest/json-ref/reader.mdx) structure to read and validate manifest data. The Rust library and other language libraries provide methods and objects for working with this structure. + +- [Reading ingredients](ingredients-reading.md) +- [Reading CAWG identity assertions](reading-cawg-id.md) +- [Reading legacy manifest data](legacy.md) +- [Validating manifests](validation.md) +- [Reader JSON reference](manifest/json-ref/reader.mdx) generated from the JSON schema for [Reader](https://docs.rs/c2pa/latest/c2pa/struct.Reader.html) object (_struct_ in Rust terminology). diff --git a/docs/manifest/validation.md b/docs/manifest/reading/validation.md similarity index 88% rename from docs/manifest/validation.md rename to docs/manifest/reading/validation.md index 2af0ff0..11158f5 100644 --- a/docs/manifest/validation.md +++ b/docs/manifest/reading/validation.md @@ -3,11 +3,11 @@ id: manifest-validation title: Validating manifests --- -Processing an asset includes [validating the manifests](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_validation) in the associated manifest store. During validation, errors can occur in the active manifest and in ingredients. +Processing an asset includes [validating the manifests](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_validation) in the associated manifest store. During validation, errors can occur in the active manifest and in ingredients. ## Validation errors in manifests -When you load an asset, all the manifests in the manifest store are validated and any [failure codes](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_failure_codes) are assigned to the `validation_status` array. Inspect the array to find the validation errors. +When you load an asset, all the manifests in the manifest store are validated and any [failure codes](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_failure_codes) are assigned to the `validation_status` array. Inspect the array to find the validation errors. :::tip Validation returns ONLY error codes; success is not explicitly indicated. If there are no validation errors, then the manifest won't have the `validation_status` element. @@ -27,11 +27,11 @@ Don't assume that just because you didn't get an error from the function return Ingredients are validated when they are imported into an asset and the result is stored in the ingredient's `validation_status` array. -Only errors that are not already recorded in the `validation_status` of an ingredient are reported. See [ValidationStatus](./manifest-ref.mdx#validationstatus) object in Manifest store reference. +Only errors that are not already recorded in the `validation_status` of an ingredient are reported. See [ValidationStatus](../json-ref/manifest-def.mdx#validationstatus) object in Manifest store reference. ## Error status codes -The following table describes some common validation error status codes. Refer to the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_failure_codes) for the full list. +The following table describes some common validation error status codes. Refer to the [C2PA Technical Specification](https://c2pa.org/specifications/specification2.2/specs/C2PA_Specification.html#_failure_codes) for the full list. | Validation Status Code| Description | Type of URI | | --------------------- | ------------ | ----------- | @@ -51,7 +51,7 @@ Validation error status codes can contain JUMBF URIs that reference assertions o - **Assertion URI**: A URI like `self#jumbf=c2pa.assertions/` where `` is either `stds.schema-org.*` or `c2pa.*`. - **Signature Box URI**: A URI like `self#jumbf=c2pa.signature`. -For more information, see the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_uri_references). +For more information, see the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_uri_references). diff --git a/docs/manifest/understanding.md b/docs/manifest/understanding.md index 594b647..2229961 100644 --- a/docs/manifest/understanding.md +++ b/docs/manifest/understanding.md @@ -1,31 +1,37 @@ --- id: understanding-manifest -title: Understanding manifests +title: Working with manifests --- -## Overview +## Understanding manifests The concept of a _manifest_ is central to how Content Credentials work. A collection of manifests (known as a _manifest store_) is attached to an asset. Each manifest contains information about the provenance of the asset. Creating or editing an asset using a C2PA-compliant device or tool (for example Adobe Photoshop) adds a new manifest to the manifest store. -A manifest store can be linked to an asset in three ways: +The manifests in the manifest store are not ordered, but the most-recently added manifest is the _active manifest_. The active manifest has content bindings that can be validated with the asset—that is, it's hashed with the asset to ensure its validity. + +### Location of manifest store + +A manifest store can be either: -1. Directly embedded in the asset's metadata. -1. In a sidecar file, a file with the same file name as the asset but with a `.c2pa` extension. -1. In a remote URL, linked from the asset's metadata, as detailed in the [C2PA specification](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html#_embedding_a_reference_to_the_active_manifest). NOTE: A given asset can have a remote manifest store plus a local manifest store linked in one of the first two ways. +- Directly embedded in the asset's metadata. +- In a _sidecar file_, which is a file with the same file name as the asset but with a `.c2pa` extension. -To determine if an asset has Content Credentials, the SDK checks for the presence of a manifest store (in the order shown above). So, for example to see if `foo.jpg` has Content Credentials, the SDK first checks if there's a manifest store in the file itself, then looks for a sidecar file (`foo.c2pa` in the same directory), and finally looks in the asset's metadata for a reference to a remote manifest store. +In addition, an asset can have a [external manifest store](https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_external_manifests), linked from the asset's metadata, as detailed in the [C2PA specification](https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_embedding_a_reference_to_an_external_manifest). This is sometimes referred to as a _remote manifest_. -A remote manifest store can be provided for a given asset as well as an embedded or sidecar manifest store. In other words, an asset can have an embedded _and_ a remote manifest store or a sidecar _and_ a remote manifest store. +To determine if an asset has Content Credentials, the SDK checks for the presence of a manifest store in this order: +1. In the asset metadata +1. In a sidebar file. +1. In a remote manifest. + +So, for example to see if `foo.jpg` has Content Credentials, the SDK first checks if there's a manifest store in the file itself, then looks for a sidecar file (`foo.c2pa` in the same directory), and finally looks in the asset's metadata for a reference to a remote manifest store. :::info Currently, only Adobe has implemented a Content Credentials cloud service to provide access to remote manifest stores, but in theory anyone could do so to provide a publicly-accessible network location for manifests. ::: -The manifests in the manifest store are not ordered, but the most-recently added manifest is the _active manifest_. The active manifest has content bindings that can be validated with the asset—that is, it's hashed with the asset to ensure its validity. - -## Binary versus JSON manifest +## Binary versus JSON manifest formats The manifest as described in the C2PA specification is a binary structure in JPEG universal metadata box format ([JUMBF](https://www.iso.org/standard/84635.html)) that can include JSON and binary data for things like encryption keys and thumbnail images. @@ -48,4 +54,4 @@ The time-stamp is typically defined as part of the signing information. You can ## References - [JUMBF](https://www.iso.org/standard/84635.html): A framework for JPEG standards to add universal metadata, supplementary images, or other elements in addition to the base image. -- [C2PA Technical Specification v1.4](https://c2pa.org/specifications/specifications/1.4/specs/C2PA_Specification.html) \ No newline at end of file +- [C2PA Technical Specification v2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html) \ No newline at end of file diff --git a/docs/manifest/writing.md b/docs/manifest/writing.md deleted file mode 100644 index 2b7b2e4..0000000 --- a/docs/manifest/writing.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -id: writing -title: Building and writing manifest data ---- - -Use a [ManifestDefinition](json-ref/manifest-def.mdx) structure to define and construct manifest data for writing. The Rust library and other language libraries provide methods and objects for working with this structure. This JSON reference is generated from the JSON schema for [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) object (_struct_ in Rust terminology). - -- [Assertions and actions](manifest/assertions-actions.md) -- [ManifestDefinition JSON reference](manifest/json-ref/manifest-def.mdx) diff --git a/docs/manifest/assertions-actions.md b/docs/manifest/writing/assertions-actions.md similarity index 98% rename from docs/manifest/assertions-actions.md rename to docs/manifest/writing/assertions-actions.md index b213c09..1f1fded 100644 --- a/docs/manifest/assertions-actions.md +++ b/docs/manifest/writing/assertions-actions.md @@ -1,6 +1,6 @@ --- id: assertions-actions -title: Assertions and actions +title: Writing assertions and actions --- ## Overview @@ -28,17 +28,13 @@ The standard form of an assertion in a JSON manifest is: ### Changes from earlier releases -
- Changes include: - `c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. -- `SoftwareAgent` is a [ClaimGeneratorInfo](json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. +- `SoftwareAgent` is a [ClaimGeneratorInfo](../json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. -- Actions are now V2 actions +- Actions are now V3 actions - Ingredients are now V2 ingredients -
- #### V2 actions The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) describes expanded v2 actions. While v1 actions are fully specified in the actions array v2 actions may either be specified by an element of the actions array or from an element in the templates array with the same action name. @@ -51,7 +47,6 @@ V1 actions have a label of `c2pa.actions` v2 actions have a label of `c2pa.actio v1 actions are fully specified in its actions array. However, in v2, an 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. - ## C2PA standard assertions The C2PA Technical Specification defines a [set of standard assertions](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_standard_c2pa_assertion_summary) and their corresponding labels. In addition, you can define [custom assertions](#custom-assertions) for your specific application. @@ -79,7 +74,7 @@ Content bindings are standard assertions such as `c2pa.hash.boxes` and `c2pa.has 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](examples.mdx/#detailed-manifest) specifies an exclusion hash: +For example, the `c2pa.hash.data` assertion shown in the [detailed manifest example](../examples.mdx/#detailed-manifest) specifies an exclusion hash: ```json "assertions": [ @@ -112,7 +107,7 @@ Update assertions ### 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](json-ref/manifest-def.mdx#assertiondefinition) objects. For example: +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](../json-ref/manifest-def.mdx#assertiondefinition) objects. For example: ```json ... diff --git a/docs/manifest/cawg-id.md b/docs/manifest/writing/cawg-id.md similarity index 97% rename from docs/manifest/cawg-id.md rename to docs/manifest/writing/cawg-id.md index 9980239..d6b3cd9 100644 --- a/docs/manifest/cawg-id.md +++ b/docs/manifest/writing/cawg-id.md @@ -1,6 +1,6 @@ --- id: cawg-id -title: CAWG identity assertions +title: Writing CAWG identity assertions --- The [Creator Assertions Working Group (CAWG)](https://cawg.io/) identity assertion enables a credential holder to prove control over a digital identity and to use that identity to document a content creator’s role(s) in a C2PA asset’s lifecycle. @@ -8,11 +8,7 @@ The [Creator Assertions Working Group (CAWG)](https://cawg.io/) identity asserti There are two different ways to provide identity assertions: - Using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures) to sign the identity claims. Enterprises or large organizations can use this approach to assert their identity in a particular trust ecosystem; for example, a news organization or publisher. The SDK can validate and sign these claims. -- Using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation). Individuals can use this approach to document their role in creating an asset by using identity signals collected and verified by a third-party aggregator. The SDK can validate these claims only. Signing is not supported. - -SDK only does x.509 signer - -Adobe apps use an identity claim agg. +- Using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation). Individuals can use this approach to document their role in creating an asset by using identity signals collected and verified by a third-party aggregator. Adobe applications (for example) use this method to provide identity claims. :::note The SDK can validate claims for both kinds of identity assertions, but can only sign claims for identity assertions using an X.509 certificate. diff --git a/docs/manifest/writing/ingredients.md b/docs/manifest/writing/ingredients.md new file mode 100644 index 0000000..b9bad60 --- /dev/null +++ b/docs/manifest/writing/ingredients.md @@ -0,0 +1,68 @@ +--- +id: ingredients +title: Writing ingredients +--- + +## Overview + +Digital assets are often not created entirely from scratch, but instead created from one or more existing assets, for example placing an image into a layer in Photoshop. Such constituent assets are called _ingredients_. + +Old manifests may contain deprecated v1 and v2 ingredients, but applications should only write v3 ingredients. + +:::note +The C2PA Technical Specification describes _ingredient assertions_ but the CAI SDK treats ingredients separately as their own objects in the JSON manifest rather than as a type of assertion. +::: + +## Ingredient objects + +The `ingredients` array contains an element for each ingredient used to create an asset. When an ingredient itself has Content Credentials, those manifests are included in the composed asset's manifest store to keep the provenance data intact. + +The `ingredients` array contains an [ingredient object](manifest/json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. + +Other important properties of the ingredient object include: +- `format`: MIME type of the source file (optional). +- `document_id` (optoinal) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. +- `thumbnail`: Object with properties that identify the thumbnail image. +- `active_manifest`: For an ingredient with a manifest store, the label of the active manifest. +- `relationship`: One of `parentOf`, `componentOf`, or `inputTo`. See [Relationship](#relationship) below. + +For example: + +```json +"ingredients": [ + { + "title": "turkey.jpeg", + "format": "image/jpeg", + "instance_id": "xmp.iid:3250038a-22ca-459b-8392-de275f8b155c", + "relationship": "parentOf", + "label": "c2pa.ingredient.v3" + }, + ... +], +``` + +### Relationship + +The ingredient object's `relationship` property describes its relationship to the current asset. This property can have one of three values, as described in the table below. + +| Value of `relationship` | Description | +|--------------------------|-------------| +| `parentOf` | The current asset is a derived asset or asset rendition of this ingredient. This relationship value is also used with update manifests. There can be at most one parent ingredient in a manifest. | +| `componentOf` | This ingredient is one of the assets that composes the current asset. | +| `inputTo` | This ingredient was used as input to a computational process, such as an AI/ML model, that led to the creation or modification of this asset. | + +## Validation results + +See [Validation results](json-ref/reader#validationresults) in the manifest JSON reference. + +When ingredients are added, the SDK validates their Content Credentials (if any). However, the validation status of an ingredient does not imply anything about the validation status of the composed asset containing the ingredient. In other words: +- A composed asset's Content Credentials may be valid, but one or more of its ingredients may have invalid Content Credentials. For example, test file [adobe-20220124-XCA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-XCA.jpg) +- A composed asset's Content Credentials may be invalid, but one or more of its ingredients may have valid Content Credentials. For example, test file [adobe-20220124-CIE-sig-CA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CIE-sig-CA.jpg). + +:::note +Ingredient certificates are validated when they are added to the manifest store, NOT during validation of the composed asset. +::: + + + + diff --git a/docs/manifest/writing/writing.md b/docs/manifest/writing/writing.md new file mode 100644 index 0000000..1640feb --- /dev/null +++ b/docs/manifest/writing/writing.md @@ -0,0 +1,11 @@ +--- +id: writing-index +title: Building and writing manifest data +--- + +Use a [ManifestDefinition](../json-ref/manifest-def.mdx) structure to define and construct manifest data for writing. The Rust library and other language libraries provide methods and objects for working with this structure. This JSON reference is generated from the JSON schema for the [ManifestDefinition](https://docs.rs/c2pa/latest/c2pa/struct.ManifestDefinition.html) object (_struct_ in Rust terminology). + +- [Writing ingredients](ingredients.md) +- [Writing assertions and actions](assertions-actions.md) +- [Writing CAWG identity assersions](cawg-id.md) +- [ManifestDefinition JSON reference](manifest/json-ref/manifest-def.mdx) diff --git a/sidebars.js b/sidebars.js index 26ef1be..d3f3ae0 100644 --- a/sidebars.js +++ b/sidebars.js @@ -36,20 +36,24 @@ const sidebars = { { type: 'category', label: 'Reading manifest data', - link: { type: 'doc', id: 'manifest/reading' }, + link: { type: 'doc', id: 'manifest/reading/reading-index' }, collapsed: true, items: [ { type: 'doc', - id: 'manifest/ingredients', + id: 'manifest/reading/reading-ingredients', }, { type: 'doc', - id: 'manifest/legacy-manifests', + id: 'manifest/reading/reading-cawg-id', }, { type: 'doc', - id: 'manifest/manifest-validation', + id: 'manifest/reading/legacy-manifests', + }, + { + type: 'doc', + id: 'manifest/reading/manifest-validation', }, { type: 'doc', @@ -60,16 +64,20 @@ const sidebars = { { type: 'category', label: 'Writing manifest data', - link: { type: 'doc', id: 'manifest/writing' }, + link: { type: 'doc', id: 'manifest/writing/writing-index' }, collapsed: true, items: [ { type: 'doc', - id: 'manifest/assertions-actions', + id: 'manifest/writing/ingredients', + }, + { + type: 'doc', + id: 'manifest/writing/assertions-actions', }, { type: 'doc', - id: 'manifest/cawg-id', + id: 'manifest/writing/cawg-id', }, { type: 'doc', From c383f790fb65e7966c9c805306c1bcb11056c860 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Wed, 23 Jul 2025 14:02:57 -0700 Subject: [PATCH 09/21] typo --- docs/manifest/reading/ingredients-reading.md | 2 +- docs/manifest/writing/ingredients.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/manifest/reading/ingredients-reading.md b/docs/manifest/reading/ingredients-reading.md index 9dc11a4..8a0baa8 100644 --- a/docs/manifest/reading/ingredients-reading.md +++ b/docs/manifest/reading/ingredients-reading.md @@ -22,7 +22,7 @@ The `ingredients` array contains an [ingredient object](manifest/json-ref/manife Other important properties of the ingredient object include: - `format`: MIME type of the source file (optional). -- `document_id` (optoinal) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. +- `document_id` (optional) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. - `thumbnail`: Object with properties that identify the thumbnail image. - `active_manifest`: For an ingredient with a manifest store, the label of the active manifest. - `relationship`: One of `parentOf`, `componentOf`, or `inputTo`. See [Relationship](#relationship) below. diff --git a/docs/manifest/writing/ingredients.md b/docs/manifest/writing/ingredients.md index b9bad60..785ec96 100644 --- a/docs/manifest/writing/ingredients.md +++ b/docs/manifest/writing/ingredients.md @@ -21,7 +21,7 @@ The `ingredients` array contains an [ingredient object](manifest/json-ref/manife Other important properties of the ingredient object include: - `format`: MIME type of the source file (optional). -- `document_id` (optoinal) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. +- `document_id` (optional) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. - `thumbnail`: Object with properties that identify the thumbnail image. - `active_manifest`: For an ingredient with a manifest store, the label of the active manifest. - `relationship`: One of `parentOf`, `componentOf`, or `inputTo`. See [Relationship](#relationship) below. From 33b35d39cac40cbdc11199a86850f81f9b93390a Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 24 Jul 2025 12:56:55 -0700 Subject: [PATCH 10/21] cawg updates --- docs/manifest/reading/legacy.md | 19 ++++++++++++++++++- docs/manifest/writing/cawg-id.md | 23 ++--------------------- 2 files changed, 20 insertions(+), 22 deletions(-) diff --git a/docs/manifest/reading/legacy.md b/docs/manifest/reading/legacy.md index 8923f12..62b610d 100644 --- a/docs/manifest/reading/legacy.md +++ b/docs/manifest/reading/legacy.md @@ -9,9 +9,26 @@ As much as possible, an application should **write** manifest data that conforms For READING old claims (only) … v1 actions and ingredients +## Legacy ingredients + +Existing manifests may contain any of these three kinds of ingredients: +- V1, with label `c2pa.ingredient` (deprecated). +- V2, with label `c2pa.ingredient.v2` (deprecated). +- V3, with label `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. + +## Legacy actions + +Existing manifests may contain two versions of actions: original v1 actions, with label `c2pa.actions`, and revised v2 actions, with label `c2pa.actions.v2`. While a v1 action is fully specified in its actions array, 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. + ## Legacy metadata assertions -Older versions of the SDK had individual assertions for each metadata standard, as detailed below. +Existing manifests may contain individual assertions for each metadata standard: +- [Exif assertion](#exif-assertion) +- [IPTC metadata assertion](#iptc-metadata-assertion) +- [Creative Work assertion](#creative-work-assertion) + +In the latest version of the SDK, Exif and IPTC assertions are now CAWG assertions, and the CreativeWork assertion is not supported at all. + ### Exif assertion diff --git a/docs/manifest/writing/cawg-id.md b/docs/manifest/writing/cawg-id.md index d6b3cd9..5f94c03 100644 --- a/docs/manifest/writing/cawg-id.md +++ b/docs/manifest/writing/cawg-id.md @@ -5,35 +5,16 @@ title: Writing CAWG identity assertions The [Creator Assertions Working Group (CAWG)](https://cawg.io/) identity assertion enables a credential holder to prove control over a digital identity and to use that identity to document a content creator’s role(s) in a C2PA asset’s lifecycle. -There are two different ways to provide identity assertions: - -- Using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures) to sign the identity claims. Enterprises or large organizations can use this approach to assert their identity in a particular trust ecosystem; for example, a news organization or publisher. The SDK can validate and sign these claims. -- Using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation). Individuals can use this approach to document their role in creating an asset by using identity signals collected and verified by a third-party aggregator. Adobe applications (for example) use this method to provide identity claims. +The SDK can write and sign claims for CAWG identity assertions provided using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures) to sign the identity claims. Enterprises or large organizations can use this approach to assert their identity in a particular trust ecosystem; for example, a news organization or publisher. The SDK can validate and sign these claims. :::note -The SDK can validate claims for both kinds of identity assertions, but can only sign claims for identity assertions using an X.509 certificate. +CAWG identity assertions can also be created using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation), but the SDK only read and validate claims for these kinds of assertions. It cannot write them. ::: ## Using an X.509 certificate When providing an identity assertion by using an X.509 certificate, the value of `signer_payload.sig_type` must be `cawg.x509.cose`. The signature value must be a COSE signature as described in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures). -## Using an identity claim aggregator - -As defined in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_identity_claims_aggregation), content creators may wish to document their role in creating an asset using identity signals such as: -- Verified web sites -- Social media accounts -- Official ID documentation -- Professional accreditations -- Organizational affiliations - -To facilitate the use of such identity signals, the content creator may use the services of a trusted third-party intermediary known as a _identity claims aggregator_ to gather these signals and to restate them on their behalf. - -The identity claims aggregator: - -- Collects and verifies identity attestation claims from various identity providers such as social media sites and ID verification vendors. -- Creates a unique asset-specific credential that binds the identity attestation claims to a specific asset. - ## Identity assertion An identity assertion using an identity claims aggregator has this general form in JSON: From 3af1829015a8298d1ea76ae33a5678779fe7bfbe Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 24 Jul 2025 13:24:45 -0700 Subject: [PATCH 11/21] more cleanup --- docs/manifest/reading/legacy.md | 17 ++++++++++------- docs/manifest/reading/reading-cawg-id.md | 20 ++++++++------------ docs/manifest/writing/assertions-actions.md | 18 ++++++++---------- docs/manifest/writing/cawg-id.md | 12 +++++------- docs/manifest/writing/ingredients.md | 6 +++++- 5 files changed, 36 insertions(+), 37 deletions(-) diff --git a/docs/manifest/reading/legacy.md b/docs/manifest/reading/legacy.md index 62b610d..b60b38f 100644 --- a/docs/manifest/reading/legacy.md +++ b/docs/manifest/reading/legacy.md @@ -5,21 +5,25 @@ title: Reading legacy manifest data As much as possible, an application should **write** manifest data that conforms to the recent [version 2.2](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html) C2PA technical specification, but should be able to **read and validate** manifest data that conforms to earlier versions of the specification. This ensures that your application is "backward-compatible" and can still validate older assets with claims that were written in the past. -
-For READING old claims (only) … v1 actions and ingredients -
- ## Legacy ingredients Existing manifests may contain any of these three kinds of ingredients: - V1, with label `c2pa.ingredient` (deprecated). - V2, with label `c2pa.ingredient.v2` (deprecated). -- V3, with label `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. +- V3, with label `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. + +
+What should we say about reading v1 and v2 ingredients? +
## Legacy actions Existing manifests may contain two versions of actions: original v1 actions, with label `c2pa.actions`, and revised v2 actions, with label `c2pa.actions.v2`. While a v1 action is fully specified in its actions array, 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. +
+What should we say about reading v1 actions? +
+ ## Legacy metadata assertions Existing manifests may contain individual assertions for each metadata standard: @@ -29,7 +33,6 @@ Existing manifests may contain individual assertions for each metadata standard: In the latest version of the SDK, Exif and IPTC assertions are now CAWG assertions, and the CreativeWork assertion is not supported at all. - ### 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](https://www.cipa.jp/std/documents/download_e.html?DC-008-Translation-2019-E). @@ -139,7 +142,7 @@ For example: ] ``` -## Training and data mining assertion +## Legacy training and data mining assertion Old manifests may have training and data mining assertions with the following entry keys: - `c2pa.data_mining` diff --git a/docs/manifest/reading/reading-cawg-id.md b/docs/manifest/reading/reading-cawg-id.md index 24f47a7..3542b56 100644 --- a/docs/manifest/reading/reading-cawg-id.md +++ b/docs/manifest/reading/reading-cawg-id.md @@ -5,29 +5,25 @@ title: Reading CAWG identity assertions The [Creator Assertions Working Group (CAWG)](https://cawg.io/) identity assertion enables a credential holder to prove control over a digital identity and to use that identity to document a content creator’s role(s) in a C2PA asset’s lifecycle. -
-Revise to focus on reading these assertions. -
- The SDK can read and validate CAWG identity assertions provided: - Using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures) to sign the identity claims. Enterprises or large organizations can use this approach to assert their identity in a particular trust ecosystem; for example, a news organization or publisher. The SDK can validate and sign these claims. - Using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation). Individuals can use this approach to document their role in creating an asset by using identity signals collected and verified by a third-party aggregator. The SDK can validate these claims only. Signing is not supported. -## Identity assertions provided using an X.509 certificate - -In an identity assertion by using an X.509 certificate, the value of `signer_payload.sig_type` is `cawg.x509.cose`. The signature value must be a COSE signature as described in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures). +## Assertions signed using a certificate -## Identity assertions provided using a claim aggregator +In an identity assertion provided by using an X.509 certificate, the value of `signer_payload.sig_type` is `cawg.x509.cose`. The signature value must be a COSE signature as described in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures). -As defined in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_identity_claims_aggregation), an identity assertion can be signed using a trusted third-party intermediary known as a _identity claims aggregator_ to gather these signals and to restate them on their behalf. +## Assertions signed using a claim aggregator -The identity claims aggregator: +An identity assertion can also be signed using a trusted third-party intermediary known as an [_identity claims aggregator_](https://cawg.io/identity/1.1/#_identity_claims_aggregation). The identity claims aggregator: - Collects and verifies identity attestation claims from various identity providers such as social media sites and ID verification vendors. - Creates a unique asset-specific credential that binds the identity attestation claims to a specific asset. -## Identity assertion +In an identity assertion provided by using an identity clarims aggregator, the value of `signer_payload.sig_type` is `cawg.identity_claims_aggregation`. + +### Example An identity assertion using an identity claims aggregator has this general form in JSON: @@ -65,7 +61,7 @@ An identity assertion using an identity claims aggregator has this general form ] ``` -### Verified identity types +## Verified identity types The following table describes the allowed values of the `type` property of `verifiedIdentities` array elements. diff --git a/docs/manifest/writing/assertions-actions.md b/docs/manifest/writing/assertions-actions.md index 1f1fded..20d77c2 100644 --- a/docs/manifest/writing/assertions-actions.md +++ b/docs/manifest/writing/assertions-actions.md @@ -31,8 +31,6 @@ The standard form of an assertion in a JSON manifest is: Changes include: - `c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. - `SoftwareAgent` is a [ClaimGeneratorInfo](../json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. - -- Actions are now V3 actions - Ingredients are now V2 ingredients #### V2 actions @@ -40,12 +38,12 @@ Changes include: The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) describes expanded v2 actions. While v1 actions are fully specified in the actions array v2 actions may either be specified by an element of the actions array or 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. +The CAI APIs can read all v2 actions and write most v2 actions. What v2 actions can it NOT write?
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 its actions array. However, in v2, an 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. +V1 actions are fully specified in its 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. ## C2PA standard assertions @@ -105,7 +103,7 @@ Update assertions --> -### Actions +## 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](../json-ref/manifest-def.mdx#assertiondefinition) objects. For example: @@ -137,13 +135,13 @@ Each object in the `actions` array has the following standard properties. | `softwareAgent` | No | The software or hardware used to perform the action. | `"Adobe Firefly"` | | `parameters` | No | Additional information describing the action; see [Parameters](#parameters) | Reference to ingredients in the `org.cai.ingredientIds` array. | -#### Action names +### Action names The value of the `action` property must be either one of the pre-defined [standard C2PA action strings](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) 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](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions). -#### Digital source type +### 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." @@ -172,7 +170,7 @@ The value of `digitalSourceType` is one of the URLs specified by the Internation This table is provided for convenience. For the authoritative list, see the [IPTC NewsCodes Digital Source Type scheme (controlled vocabulary)](https://cv.iptc.org/newscodes/digitalsourcetype/). ::: -#### Generative AI action +### 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. @@ -201,7 +199,7 @@ For other possible values of `digitalSourceType`, see [Digital source type](#dig Where `` is the name of the generative AI tool or service. -#### Parameters +### Parameters The `parameters` property can contain any data that provide more details on the action, for example: @@ -415,7 +413,7 @@ For example: 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. +Training and data mining assertions formerly had `c2pa.*` labels. See [Legacy training and data mining assertion](../reading/legacy.md#legacy-training-and-data-mining-assertion) for more information. ::: diff --git a/docs/manifest/writing/cawg-id.md b/docs/manifest/writing/cawg-id.md index 5f94c03..fa9009c 100644 --- a/docs/manifest/writing/cawg-id.md +++ b/docs/manifest/writing/cawg-id.md @@ -3,20 +3,18 @@ id: cawg-id title: Writing CAWG identity assertions --- -The [Creator Assertions Working Group (CAWG)](https://cawg.io/) identity assertion enables a credential holder to prove control over a digital identity and to use that identity to document a content creator’s role(s) in a C2PA asset’s lifecycle. +The [Creator Assertions Working Group (CAWG)](https://cawg.io/) identity assertion enables a credential holder to prove control over a digital identity and to use that identity to document a content creator’s role(s) in an asset’s lifecycle. -The SDK can write and sign claims for CAWG identity assertions provided using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures) to sign the identity claims. Enterprises or large organizations can use this approach to assert their identity in a particular trust ecosystem; for example, a news organization or publisher. The SDK can validate and sign these claims. +The SDK can write and sign claims for CAWG identity assertions provided using an [X.509 certificate](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures). :::note -CAWG identity assertions can also be created using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation), but the SDK only read and validate claims for these kinds of assertions. It cannot write them. +CAWG identity assertions can also be created using an [identity claim aggregator](https://cawg.io/identity/1.1/#_identity_claims_aggregation), but the SDK only _read and validate_ claims for these kinds of assertions. It cannot write them. ::: ## Using an X.509 certificate When providing an identity assertion by using an X.509 certificate, the value of `signer_payload.sig_type` must be `cawg.x509.cose`. The signature value must be a COSE signature as described in the [CAWG Identity Assertion technical specification](https://cawg.io/identity/1.1/#_x_509_certificates_and_cose_signatures). -## Identity assertion - An identity assertion using an identity claims aggregator has this general form in JSON: ```json @@ -53,7 +51,7 @@ An identity assertion using an identity claims aggregator has this general form ] ``` -### Verified identity types +## Verified identity types The following table describes the allowed values of the `type` property of `verifiedIdentities` array elements. @@ -69,7 +67,7 @@ The following table describes the allowed values of the `type` property of `veri The above table is based on the [CAWG identity assertion technical specifications](https://cawg.io/identity/1.1/#vc-credentialsubject-verifiedidentity-type). ::: -### Example +## Example ```json "assertions": [ diff --git a/docs/manifest/writing/ingredients.md b/docs/manifest/writing/ingredients.md index 785ec96..ce9a021 100644 --- a/docs/manifest/writing/ingredients.md +++ b/docs/manifest/writing/ingredients.md @@ -7,7 +7,11 @@ title: Writing ingredients Digital assets are often not created entirely from scratch, but instead created from one or more existing assets, for example placing an image into a layer in Photoshop. Such constituent assets are called _ingredients_. -Old manifests may contain deprecated v1 and v2 ingredients, but applications should only write v3 ingredients. +[Old manifests](../reading/legacy.md) may contain deprecated v1 and v2 ingredients, but applications should only write v3 ingredients. + +
+This page should cover only v3 ingredients. +
:::note The C2PA Technical Specification describes _ingredient assertions_ but the CAI SDK treats ingredients separately as their own objects in the JSON manifest rather than as a type of assertion. From b898d6446f86c858777d764a198954185c0a9eb6 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 28 Aug 2025 14:27:08 -0700 Subject: [PATCH 12/21] Change org.cai.ingredientIds to IngredientIds --- docs/manifest/writing/assertions-actions.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/manifest/writing/assertions-actions.md b/docs/manifest/writing/assertions-actions.md index 20d77c2..099635c 100644 --- a/docs/manifest/writing/assertions-actions.md +++ b/docs/manifest/writing/assertions-actions.md @@ -133,7 +133,7 @@ Each object in the `actions` array has the following standard properties. | `action` | Yes | The action name. See [Action names](#action-names). | `c2pa.created` | | `digitalSourceType` | No | A URL identifying a [IPTC term](https://cv.iptc.org/newscodes/digitalsourcetype/). See [Digital source type](#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](#parameters) | Reference to ingredients in the `org.cai.ingredientIds` array. | +| `parameters` | No | Additional information describing the action; see [Parameters](#parameters) | Reference to ingredients in the `ingredientIds` array. | ### Action names @@ -216,10 +216,10 @@ The `parameters` property can contain any data that provide more details on the ] ``` -When creating an actions assertion that has an associated ingredient, the `parameters` object must include a `org.cai.ingredientIds` property with an array of one or more [`instance_id` values](#the-instance_id-property) 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](#the-instance_id-property) from ingredients. This is how you associate an action with one or more ingredients. :::info -The [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_parameters) 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 `org.cai.ingredientIds` parameter with a matching ingredient. +The [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_parameters) 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: @@ -229,7 +229,7 @@ For example: { "action": "c2pa.opened", "parameters": { - "org.cai.ingredientIds": [ + "ingredientIds": [ "xmp.iid:813ee422-9736-4cdc-9be6-4e35ed8e41cb" ] } @@ -247,7 +247,7 @@ For more information on action parameters, see the [C2PA Technical Specification 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 `org.cai.ingredientIds` parameters field of the action with an array of ingredient `instance_id` values. +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. ```json "ingredients": [ @@ -263,7 +263,7 @@ Any `c2pa.opened` or `c2pa.placed` action must have an associated ingredient ide { "action": "c2pa.*", "parameters": { - "org.cai.ingredientIds": [ + "ingredientIds": [ "" ], } @@ -291,7 +291,7 @@ For example, the following action identifies that the `c2pa.opened` action was p { "action": "c2pa.opened", "parameters": { - "org.cai.ingredientIds": [ + "ingredientIds": [ "xmp.iid:3250038a-22ca-459b-8392-de275f8b155c" ], } From 0170bdcf305fa89f0ccc29d9e290936c5afd6544 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 5 Sep 2025 13:23:48 -0700 Subject: [PATCH 13/21] Clean up for review --- docs/manifest/reading/ingredients-reading.md | 8 +++++--- docs/manifest/reading/legacy.md | 9 +++++---- docs/manifest/reading/reading-cawg-id.md | 2 +- docs/manifest/writing/assertions-actions.md | 6 ++---- docs/manifest/writing/ingredients.md | 6 +++--- 5 files changed, 16 insertions(+), 15 deletions(-) diff --git a/docs/manifest/reading/ingredients-reading.md b/docs/manifest/reading/ingredients-reading.md index 3da8d4d..a5991f9 100644 --- a/docs/manifest/reading/ingredients-reading.md +++ b/docs/manifest/reading/ingredients-reading.md @@ -6,9 +6,9 @@ title: Reading ingredients ## Overview Existing manifests may contain any of these three kinds of ingredients: -- V1, with label `c2pa.ingredient` (deprecated). -- V2, with label `c2pa.ingredient.v2` (deprecated). -- V3, with label `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. +- V1, with labels starting with `c2pa.ingredient` (deprecated). See [Reading legacy manifest data](legacy.md#legacy-ingredients). +- V2, with labels starting with `c2pa.ingredient.v2` (deprecated). See [Reading legacy manifest data](legacy.md#legacy-ingredients). +- V3, with labels starting with `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. :::note The C2PA Technical Specification describes _ingredient assertions_ but the CAI SDK treats ingredients separately as their own objects in the JSON manifest rather than as a type of assertion. @@ -20,6 +20,8 @@ The `ingredients` array contains an element for each ingredient used to create a The `ingredients` array contains an [ingredient object](manifest/json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. +The `label` property for the first ingredient in a manifest is `c2pa.ingredient.v3` When there is more than one ingredient, subsequent labels have a monotonically increasing index: `c2pa.ingredient.v3__1`, `c2pa.ingredient.v3__2`, and so on. + Other important properties of the ingredient object include: - `format`: MIME type of the source file (optional). - `document_id` (optional) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. diff --git a/docs/manifest/reading/legacy.md b/docs/manifest/reading/legacy.md index b60b38f..23df092 100644 --- a/docs/manifest/reading/legacy.md +++ b/docs/manifest/reading/legacy.md @@ -7,10 +7,11 @@ As much as possible, an application should **write** manifest data that conforms ## Legacy ingredients -Existing manifests may contain any of these three kinds of ingredients: -- V1, with label `c2pa.ingredient` (deprecated). -- V2, with label `c2pa.ingredient.v2` (deprecated). -- V3, with label `c2pa.ingredient.v3`, which addresses the issue of validating ingredients after redaction. +Old manifests may contain these kinds of deprecated ingredient data: +- V1 ingredients, with label `c2pa.ingredient`. +- V2 ingredients, with label `c2pa.ingredient.v2`. + +
What should we say about reading v1 and v2 ingredients? diff --git a/docs/manifest/reading/reading-cawg-id.md b/docs/manifest/reading/reading-cawg-id.md index 3542b56..9b1b2ba 100644 --- a/docs/manifest/reading/reading-cawg-id.md +++ b/docs/manifest/reading/reading-cawg-id.md @@ -68,7 +68,7 @@ The following table describes the allowed values of the `type` property of `veri | Value | Meaning | |--------------|----------| | `cawg.document_verification` | The identity provider verified one or more government-issued identity documents presented by the content creator. -| `cawg.web_site` | The content creator has proven control over a specific domain to the identity claims aggregator._ +| `cawg.web_site` | The content creator has proven control over a specific domain to the identity claims aggregator. | `cawg.affiliation` | The identity provider is attesting to the content creator’s membership in an organization. This could be a professional organization or an employment relationship. | `cawg.social_media` | The content creator has demonstrated control over an account (typically a social media account) hosted by the identity provider. | `cawg.crypto_wallet` | The content creator has demonstrated control over an account (typically a crypto-wallet) hosted by the identity provider. diff --git a/docs/manifest/writing/assertions-actions.md b/docs/manifest/writing/assertions-actions.md index 22ec058..4438dff 100644 --- a/docs/manifest/writing/assertions-actions.md +++ b/docs/manifest/writing/assertions-actions.md @@ -37,6 +37,8 @@ Changes include: The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) describes expanded v2 actions. While v1 actions are fully specified in the actions array v2 actions may either be specified by an element of the actions array or 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?
@@ -51,10 +53,6 @@ The C2PA Technical Specification defines a [set of standard assertions](https:// The following table summarizes some of the most important standard assertions. -
-What other c2pa stadard assertions should we call out? -
- | Assertion | Label | Description | |-----------|-------|-------------| | [Content bindings](#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. | diff --git a/docs/manifest/writing/ingredients.md b/docs/manifest/writing/ingredients.md index ce9a021..96504f0 100644 --- a/docs/manifest/writing/ingredients.md +++ b/docs/manifest/writing/ingredients.md @@ -9,9 +9,7 @@ Digital assets are often not created entirely from scratch, but instead created [Old manifests](../reading/legacy.md) may contain deprecated v1 and v2 ingredients, but applications should only write v3 ingredients. -
-This page should cover only v3 ingredients. -
+Applications should write only v3 ingredients, with label starting with `c2pa.ingredient.v3` and are described in the [C2PA specification](https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#ingredient_assertion) . :::note The C2PA Technical Specification describes _ingredient assertions_ but the CAI SDK treats ingredients separately as their own objects in the JSON manifest rather than as a type of assertion. @@ -23,6 +21,8 @@ The `ingredients` array contains an element for each ingredient used to create a The `ingredients` array contains an [ingredient object](manifest/json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. +The `label` property for the first ingredient in a manifest is `c2pa.ingredient.v3` When there is more than one ingredient, subsequent labels have a monotonically increasing index: `c2pa.ingredient.v3__1`, `c2pa.ingredient.v3__2`, and so on. + Other important properties of the ingredient object include: - `format`: MIME type of the source file (optional). - `document_id` (optional) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. From 34e61968856c2a8aadf55711832d3e697db8637c Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 5 Sep 2025 13:31:33 -0700 Subject: [PATCH 14/21] add review comment --- docs/manifest/reading/legacy.md | 4 +++- docs/manifest/reading/validation.md | 8 ++++++++ docs/manifest/writing/assertions-actions.md | 8 ++++++-- 3 files changed, 17 insertions(+), 3 deletions(-) diff --git a/docs/manifest/reading/legacy.md b/docs/manifest/reading/legacy.md index 23df092..7796e10 100644 --- a/docs/manifest/reading/legacy.md +++ b/docs/manifest/reading/legacy.md @@ -11,7 +11,7 @@ Old manifests may contain these kinds of deprecated ingredient data: - V1 ingredients, with label `c2pa.ingredient`. - V2 ingredients, with label `c2pa.ingredient.v2`. - +
What should we say about reading v1 and v2 ingredients? @@ -21,6 +21,8 @@ What should we say about reading v1 and v2 ingredients? Existing manifests may contain two versions of actions: original v1 actions, with label `c2pa.actions`, and revised v2 actions, with label `c2pa.actions.v2`. While a v1 action is fully specified in its actions array, 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. + +
What should we say about reading v1 actions?
diff --git a/docs/manifest/reading/validation.md b/docs/manifest/reading/validation.md index 11158f5..921da57 100644 --- a/docs/manifest/reading/validation.md +++ b/docs/manifest/reading/validation.md @@ -5,6 +5,14 @@ title: Validating manifests Processing an asset includes [validating the manifests](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_validation) in the associated manifest store. During validation, errors can occur in the active manifest and in ingredients. +In the latest version of the SDK, +- Builder performs validation by default, so you can't create an invalid manifest. Previously, the SDK was permissive in this regard. +- Validation is much stricter + +
+Need a high-level summary of full validation, what we're looking for, etc. +
+ ## Validation errors in manifests When you load an asset, all the manifests in the manifest store are validated and any [failure codes](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_failure_codes) are assigned to the `validation_status` array. Inspect the array to find the validation errors. diff --git a/docs/manifest/writing/assertions-actions.md b/docs/manifest/writing/assertions-actions.md index 4438dff..008a41c 100644 --- a/docs/manifest/writing/assertions-actions.md +++ b/docs/manifest/writing/assertions-actions.md @@ -26,12 +26,16 @@ The standard form of an assertion in a JSON manifest is: ] ``` +:::important +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: -- `c2pa.data_mining` > `cawg.data_mining`, etc. were renamed, with xref. +- 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](../writing/assertions-actions.md#cawg-training-and-data-mining-assertion) - `SoftwareAgent` is a [ClaimGeneratorInfo](../json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. -- Ingredients are now V2 ingredients +- Ingredients are now V3 ingredients #### V2 actions From 5072faa32d334161d5c47d68d53cb03d3b956e54 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 5 Sep 2025 13:54:34 -0700 Subject: [PATCH 15/21] update validation --- docs/manifest/reading/validation.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/docs/manifest/reading/validation.md b/docs/manifest/reading/validation.md index 921da57..e8f0373 100644 --- a/docs/manifest/reading/validation.md +++ b/docs/manifest/reading/validation.md @@ -15,7 +15,11 @@ Need a high-level summary of full validation, what we're looking for, etc. ## Validation errors in manifests -When you load an asset, all the manifests in the manifest store are validated and any [failure codes](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_failure_codes) are assigned to the `validation_status` array. Inspect the array to find the validation errors. +When you load an asset, all the manifests in the manifest store are validated and any [failure codes](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_failure_codes) are assigned to the `validation_status` array. Inspect the array to find the validation errors. + +`Reader` has these validation methods: +- `validation_state()` returns `ValidationState`, which can be `Invalid`, `Valid` or `Trusted`. +- `validation_results()` returns `ValidationResults`, which returns `success`, `informational`, and `failure` codes for the active manifest and ingredients. NOTE: `ValidationStatus` is deprecated in favor of `ValidationResults`. :::tip Validation returns ONLY error codes; success is not explicitly indicated. If there are no validation errors, then the manifest won't have the `validation_status` element. From f9e7a1715385f6e67f6d2a024d0f5baf950f7008 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 5 Sep 2025 14:16:05 -0700 Subject: [PATCH 16/21] Updates to validation --- docs/manifest/reading/validation.md | 49 +++++++---------------------- 1 file changed, 11 insertions(+), 38 deletions(-) diff --git a/docs/manifest/reading/validation.md b/docs/manifest/reading/validation.md index e8f0373..52efc78 100644 --- a/docs/manifest/reading/validation.md +++ b/docs/manifest/reading/validation.md @@ -13,37 +13,33 @@ In the latest version of the SDK, Need a high-level summary of full validation, what we're looking for, etc.
-## Validation errors in manifests - -When you load an asset, all the manifests in the manifest store are validated and any [failure codes](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_failure_codes) are assigned to the `validation_status` array. Inspect the array to find the validation errors. - `Reader` has these validation methods: -- `validation_state()` returns `ValidationState`, which can be `Invalid`, `Valid` or `Trusted`. -- `validation_results()` returns `ValidationResults`, which returns `success`, `informational`, and `failure` codes for the active manifest and ingredients. NOTE: `ValidationStatus` is deprecated in favor of `ValidationResults`. +- `validation_state()` returns `ValidationState` object (`validation_state` in JSON), which can be `Invalid`, `Valid` or `Trusted`. +- `validation_results()` returns `ValidationResults` (`validation_results` in JSON), which can be `success`, `informational`, and `failure` codes for the active manifest and ingredients. -:::tip -Validation returns ONLY error codes; success is not explicitly indicated. If there are no validation errors, then the manifest won't have the `validation_status` element. +:::note +The old `ValidationStatus` and `validation_status` array in previous SDK releases are deprecated in favor of `ValidationResults` / `validation_results` and `ValidationState` / `validation_state`. ::: +## Validation errors in manifests + +When you load an asset, all the manifests in the manifest store are validated and [result codes](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_failure_codes) are assigned to properties in the `validation_results` object. + Manifest validation errors can occur, for example, when: - The bits of an asset are edited after it was signed. - A claim or assertion is missing or tampered with. - The manifest is signed with an invalid credential. -:::caution -Don't assume that just because you didn't get an error from the function return value that there are not validation errors. You MUST check the `validation_status` array to see if there are errors or not. -::: - ## Validation errors in ingredients -Ingredients are validated when they are imported into an asset and the result is stored in the ingredient's `validation_status` array. +Ingredients are validated when they are imported into an asset and the result is stored in the ingredient's `validation_results` object. -Only errors that are not already recorded in the `validation_status` of an ingredient are reported. See [ValidationStatus](../json-ref/manifest-def.mdx#validationstatus) object in Manifest store reference. +Only errors that are not already recorded in the `validation_results` of an ingredient are reported. See [ValidationStatus](../json-ref/manifest-def.mdx#validationresults) object in Manifest store reference. ## Error status codes -The following table describes some common validation error status codes. Refer to the [C2PA Technical Specification](https://c2pa.org/specifications/specification2.2/specs/C2PA_Specification.html#_failure_codes) for the full list. +The following table describes some common validation error status codes. Refer to the [C2PA Technical Specification](https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_failure_codes) for the full list. | Validation Status Code| Description | Type of URI | | --------------------- | ------------ | ----------- | @@ -64,26 +60,3 @@ Validation error status codes can contain JUMBF URIs that reference assertions o - **Signature Box URI**: A URI like `self#jumbf=c2pa.signature`. For more information, see the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_uri_references). - - From 8980dee17c9c92f668537d692c9d7dc3e70a1844 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 5 Sep 2025 14:17:25 -0700 Subject: [PATCH 17/21] labels for legacy ingredients --- docs/manifest/reading/legacy.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/manifest/reading/legacy.md b/docs/manifest/reading/legacy.md index 7796e10..d4d3836 100644 --- a/docs/manifest/reading/legacy.md +++ b/docs/manifest/reading/legacy.md @@ -8,13 +8,13 @@ As much as possible, an application should **write** manifest data that conforms ## Legacy ingredients Old manifests may contain these kinds of deprecated ingredient data: -- V1 ingredients, with label `c2pa.ingredient`. -- V2 ingredients, with label `c2pa.ingredient.v2`. +- V1 ingredients, with labels that begin with `c2pa.ingredient`. +- V2 ingredients, with labels that begin with `c2pa.ingredient.v2`.
-What should we say about reading v1 and v2 ingredients? +Should we say anything more about reading v1 and v2 ingredients?
## Legacy actions From 3b7267b460395114cf1276566bc4a0a35df584be Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 5 Sep 2025 15:34:11 -0700 Subject: [PATCH 18/21] Move section on v2 actions --- docs/manifest/writing/assertions-actions.md | 24 +++++++++------------ 1 file changed, 10 insertions(+), 14 deletions(-) diff --git a/docs/manifest/writing/assertions-actions.md b/docs/manifest/writing/assertions-actions.md index 008a41c..fdcd95d 100644 --- a/docs/manifest/writing/assertions-actions.md +++ b/docs/manifest/writing/assertions-actions.md @@ -37,20 +37,6 @@ Changes include: - `SoftwareAgent` is a [ClaimGeneratorInfo](../json-ref/manifest-def.mdx#claimgeneratorinfo) structure instead of a string. - Ingredients are now V3 ingredients -#### V2 actions - -The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) describes expanded v2 actions. While v1 actions are fully specified in the actions array v2 actions may either be specified by an element of the actions array or 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? -
- -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 its 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. - ## C2PA standard assertions The C2PA Technical Specification defines a [set of standard assertions](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_standard_c2pa_assertion_summary) and their corresponding labels. In addition, you can define [custom assertions](#custom-assertions) for your specific application. @@ -138,6 +124,16 @@ Each object in the `actions` array has the following standard properties. | `parameters` | No | Additional information describing the action; see [Parameters](#parameters) | Reference to ingredients in the `ingredientIds` array. | | `parameters` | No | Additional information describing the action; see [Parameters](#parameters) | Reference to ingredients in the `ingredientIds` array. | +### V2 actions + +The [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) 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? +
+ ### Action names The value of the `action` property must be either one of the pre-defined [standard C2PA action strings](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions) 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. From cbc302924ad477ce88528cd8b1dc05209a70325a Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 5 Sep 2025 16:05:56 -0700 Subject: [PATCH 19/21] Removed missed instance of CreativeWork --- docs/manifest/writing/assertions-actions.md | 59 +++++++++++++-------- 1 file changed, 37 insertions(+), 22 deletions(-) diff --git a/docs/manifest/writing/assertions-actions.md b/docs/manifest/writing/assertions-actions.md index fdcd95d..18e9113 100644 --- a/docs/manifest/writing/assertions-actions.md +++ b/docs/manifest/writing/assertions-actions.md @@ -46,7 +46,7 @@ The following table summarizes some of the most important standard assertions. | Assertion | Label | Description | |-----------|-------|-------------| | [Content bindings](#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](#actions) | `c2pa.actions` | Creation, edits, and other actions on an asset, such as cropping, color or contrast adjustment, and so on. | +| [Actions](#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. @@ -93,13 +93,19 @@ Update assertions ## 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](../json-ref/manifest-def.mdx#assertiondefinition) objects. For example: +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](../json-ref/manifest-def.mdx#assertiondefinition) objects. + +:::important +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: ```json ... "assertions": [ { - "label": "c2pa.actions", + "label": "c2pa.actions.v2", "data": { "actions": [ { @@ -131,7 +137,8 @@ The [C2PA Technical Specification](https://c2pa.org/specifications/specification 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? +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 @@ -140,7 +147,7 @@ The value of the `action` property must be either one of the pre-defined [standa For the complete list of standard actions, see the [C2PA Technical Specification](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_actions). -### Digital source type +### 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." @@ -181,7 +188,7 @@ For other possible values of `digitalSourceType`, see [Digital source type](#dig "assertions": [ ... { - "label": "c2pa.actions", + "label": "c2pa.actions.v2", "data": { "actions": [ { @@ -280,27 +287,37 @@ For example, the following action identifies that the `c2pa.opened` action was p ```json "ingredients": [ { - "title": "test.jpeg", + "title": "crater-lake.jpeg", "format": "image/jpeg", - "instance_id": "xmp.iid:3250038a-22ca-459b-8392-de275f8b155c", - "relationship": "parentOf" + "instance_id": "xmp.iid:7f136ee1-6e84-4d80-9de3-e1180ef2b690", + "relationship": "parentOf", + "label": "c2pa.ingredient.v3" } ], "assertions": [ { - "label": "c2pa.actions", + "label": "c2pa.actions.v2", "data": { "actions": [ - { - "action": "c2pa.opened", - "parameters": { - "ingredientIds": [ - "ingredientIds": [ - "xmp.iid:3250038a-22ca-459b-8392-de275f8b155c" - ], - } - }, - ... + { + "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 @@ -313,7 +330,6 @@ Metadata assertions must include one or more `@context` properties in the `data` | Assertion | Label | Description | |-----------|-------|-------------| -| [Creative work](#creative-work-assertion) | `stds.schema-org.CreativeWork` | Indicates the asset is the product of creative effort. | | [Exif information](#exif-assertion) | `stds.exif` | Camera information such as maker, lens stored in Exchangeable image file format (Exif). | | [IPTC photo and video metadata](#iptc-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](#do-not-train-assertion) | `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`. | @@ -420,7 +436,6 @@ Assertions with the `cawg.training-mining` label provide information about wheth Training and data mining assertions formerly had `c2pa.*` labels. See [Legacy training and data mining assertion](../reading/legacy.md#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` | From 8e59a3f88cc227e57a39b7c5293a9ba89ceea47e Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 11 Sep 2025 16:20:18 -0700 Subject: [PATCH 20/21] Gavin review comments --- docs/manifest/json-ref/index.md | 4 +++- docs/manifest/json-ref/manifest-def.mdx | 6 +++-- docs/manifest/json-ref/reader.mdx | 6 +++-- docs/manifest/reading/ingredients-reading.md | 23 +++++++++++++++----- docs/manifest/writing/ingredients.md | 10 ++++++--- 5 files changed, 35 insertions(+), 14 deletions(-) diff --git a/docs/manifest/json-ref/index.md b/docs/manifest/json-ref/index.md index 9932d9d..d94e92d 100644 --- a/docs/manifest/json-ref/index.md +++ b/docs/manifest/json-ref/index.md @@ -6,4 +6,6 @@ pagination_next: null pagination_prev: null --- -No longer used. \ No newline at end of file +Please see: +- [ManifestDefinition JSON reference](manifest-def.mdx) +- [Reader JSON reference](reader.mdx) \ No newline at end of file diff --git a/docs/manifest/json-ref/manifest-def.mdx b/docs/manifest/json-ref/manifest-def.mdx index 77c5dda..95a88b9 100644 --- a/docs/manifest/json-ref/manifest-def.mdx +++ b/docs/manifest/json-ref/manifest-def.mdx @@ -7,9 +7,11 @@ hide_table_of_contents: true import ManifestReference from './manifest-ref.js'; :::danger Warning -This is a beta release of this reference. It is a work in progress and may not be accurate or complete. +This is a beta release of this reference. It is a work in progress and may not be accurate or complete. It was generated from the unmodified JSON schema generated from c2pa-rs on 05/09/2025. ::: -This page is generated from the unmodified JSON schema generated from c2pa-rs on 05/09/2025. +The [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_manifests) describes a manifest with a binary structure in JPEG universal metadata box format ([JUMBF](https://www.iso.org/standard/84635.html)) that includes JSON as well as binary data for things like encryption keys and thumbnail images. Because the binary structure is hard to understand and program to, the SDK defines a JSON manifest structure that's a declarative language for representing and creating a binary manifest. + +The JSON manifest is an abstract translation layer that's easier to understand than the binary format. It can describe everything in the underlying binary format except for binary data such as thumbnails that are included by a structure called a _resource reference_. To generate a binary manifest, the SDK assembles all the JSON objects, resource references, and ingredients defined, and then converts them into different assertions and other objects as required. diff --git a/docs/manifest/json-ref/reader.mdx b/docs/manifest/json-ref/reader.mdx index b4a1141..c1085af 100644 --- a/docs/manifest/json-ref/reader.mdx +++ b/docs/manifest/json-ref/reader.mdx @@ -7,9 +7,11 @@ hide_table_of_contents: true import ManifestReference from './manifest-ref.js'; :::danger Warning -This is a beta release of this reference. It is a work in progress and may not be accurate or complete. +This is a beta release of this reference. It is a work in progress and may not be accurate or complete. It was generated from the unmodified JSON schema generated from c2pa-rs on 05/09/2025. ::: -This page is generated from the unmodified JSON schema generated from c2pa-rs on 05/09/2025. +The [C2PA specification](https://c2pa.org/specifications/specifications/2.1/specs/C2PA_Specification.html#_manifests) describes a manifest with a binary structure in JPEG universal metadata box format ([JUMBF](https://www.iso.org/standard/84635.html)) that includes JSON as well as binary data for things like encryption keys and thumbnail images. Because the binary structure is hard to understand and program to, the SDK defines a JSON manifest structure that's a declarative language for representing and creating a binary manifest. + +The JSON manifest is an abstract translation layer that's easier to understand than the binary format. It can describe everything in the underlying binary format except for binary data such as thumbnails that are included by a structure called a _resource reference_. To generate a binary manifest, the SDK assembles all the JSON objects, resource references, and ingredients defined, and then converts them into different assertions and other objects as required. diff --git a/docs/manifest/reading/ingredients-reading.md b/docs/manifest/reading/ingredients-reading.md index a5991f9..b15f903 100644 --- a/docs/manifest/reading/ingredients-reading.md +++ b/docs/manifest/reading/ingredients-reading.md @@ -3,7 +3,9 @@ id: reading-ingredients title: Reading ingredients --- -## Overview +## Overview + +Digital assets are often not created entirely from scratch, but instead created from one or more existing assets, for example placing an image into a layer in Photoshop. Such constituent assets are called _ingredients_. Existing manifests may contain any of these three kinds of ingredients: - V1, with labels starting with `c2pa.ingredient` (deprecated). See [Reading legacy manifest data](legacy.md#legacy-ingredients). @@ -18,17 +20,29 @@ The C2PA Technical Specification describes _ingredient assertions_ but the CAI S The `ingredients` array contains an element for each ingredient used to create an asset. When an ingredient itself has Content Credentials, those manifests are included in the composed asset's manifest store to keep the provenance data intact. -The `ingredients` array contains an [ingredient object](manifest/json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. +The `ingredients` array contains an [ingredient object](manifest/json-ref/reader.mdx#ingredient) for each ingredient. The `ingredient` object's `title` property (usually is the source file name) is required for v1 and v2 ingredients, but optional for v3 ingredients. + +### The label property + +The `label` property is used in two ways: + +- When creating an ingredient, you can assign any value you like to `label` and we will match that with the the action `ingredientIds` to find an associated action. The value you specify here does not end up in the manifest. it is optional and only used for doing action/ingredient pairing. +- When reading a manifest, the `label` will always exist and correspond to actual label assigned to the ingredient. It will be in the format you described below. Note that older v1 claims may have older forms of ingredient labels. The `label` property for the first ingredient in a manifest is `c2pa.ingredient.v3` When there is more than one ingredient, subsequent labels have a monotonically increasing index: `c2pa.ingredient.v3__1`, `c2pa.ingredient.v3__2`, and so on. +### Other properties + Other important properties of the ingredient object include: + - `format`: MIME type of the source file (optional). - `document_id` (optional) and `instance_id` (required) which are derived from the ingredient asset's XMP metadata. - `thumbnail`: Object with properties that identify the thumbnail image. - `active_manifest`: For an ingredient with a manifest store, the label of the active manifest. - `relationship`: One of `parentOf`, `componentOf`, or `inputTo`. See [Relationship](#relationship) below. +An ingredient assertion must always have a `relationship` and an `instance_id`, but the API will default `relationship` to `componentOf` if not specified and will generate an `instance_id` if you don't give it one. It will also always return a label. + For example: ```json @@ -55,7 +69,7 @@ The ingredient object's `relationship` property describes its relationship to th | Value of `relationship` | Description | |--------------------------|-------------| | `parentOf` | The current asset is a derived asset or asset rendition of this ingredient. This relationship value is also used with update manifests. There can be at most one parent ingredient in a manifest. | -| `componentOf` | This ingredient is one of the assets that composes the current asset. | +| `componentOf` | This ingredient is one of the assets that composes the current asset. This is the default value. | | `inputTo` | This ingredient was used as input to a computational process, such as an AI/ML model, that led to the creation or modification of this asset. | ## Validation results @@ -114,6 +128,3 @@ As noted above, the test file [adobe-20220124-CIE-sig-CA.jpg](https://contentcre The [C2PA public-testfiles](https://spec.c2pa.org/public-testfiles/image/) repository has several examples of images with multiple ingredients: - [Image with two ingredients](https://contentcredentials.org/verify?source=https://spec.c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CAICA.jpg); [View JSON manifest store](https://spec.c2pa.org/public-testfiles/image/jpeg/manifests/adobe-20220124-CAICA/manifest_store.json) - [Image with seven ingredients](https://contentcredentials.org/verify?source=https://spec.c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CAIAIIICAICIICAIICICA.jpg); [View JSON manifest store](https://spec.c2pa.org/public-testfiles/image/jpeg/manifests/adobe-20220124-CAIAIIICAICIICAIICICA/manifest_store.json) - - - diff --git a/docs/manifest/writing/ingredients.md b/docs/manifest/writing/ingredients.md index 96504f0..7499893 100644 --- a/docs/manifest/writing/ingredients.md +++ b/docs/manifest/writing/ingredients.md @@ -3,13 +3,15 @@ id: ingredients title: Writing ingredients --- -## Overview +## Overview Digital assets are often not created entirely from scratch, but instead created from one or more existing assets, for example placing an image into a layer in Photoshop. Such constituent assets are called _ingredients_. [Old manifests](../reading/legacy.md) may contain deprecated v1 and v2 ingredients, but applications should only write v3 ingredients. -Applications should write only v3 ingredients, with label starting with `c2pa.ingredient.v3` and are described in the [C2PA specification](https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#ingredient_assertion) . +Applications should write only v3 ingredients, with label starting with `c2pa.ingredient.v3` as described in the [C2PA specification](https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#ingredient_assertion). + +The API will only write v3 ingredients to a v2 claim. It will write v2 ingredients to a v1 claim and will read any of the three formats. :::note The C2PA Technical Specification describes _ingredient assertions_ but the CAI SDK treats ingredients separately as their own objects in the JSON manifest rather than as a type of assertion. @@ -21,7 +23,7 @@ The `ingredients` array contains an element for each ingredient used to create a The `ingredients` array contains an [ingredient object](manifest/json-ref/manifest-def.mdx#ingredient) for each ingredient. The only required property of the `ingredient` object is the `title` property, which usually is the source file name. -The `label` property for the first ingredient in a manifest is `c2pa.ingredient.v3` When there is more than one ingredient, subsequent labels have a monotonically increasing index: `c2pa.ingredient.v3__1`, `c2pa.ingredient.v3__2`, and so on. +When reading an ingredient, `label` property for the first ingredient in a manifest is `c2pa.ingredient.v3` When there is more than one ingredient, subsequent labels have a monotonically increasing index: `c2pa.ingredient.v3__1`, `c2pa.ingredient.v3__2`, and so on. you can use your own labels when creating new ingredients, but those labels are only temporary and will be replaced. Other important properties of the ingredient object include: - `format`: MIME type of the source file (optional). @@ -55,6 +57,8 @@ The ingredient object's `relationship` property describes its relationship to th | `componentOf` | This ingredient is one of the assets that composes the current asset. | | `inputTo` | This ingredient was used as input to a computational process, such as an AI/ML model, that led to the creation or modification of this asset. | +Note that `parentOf` ingredients must have a matching `c2pa.opened` action as the first action in the manifest and `componentOf` ingredients must have an associated `c2pa.placed` action. + ## Validation results See [Validation results](json-ref/reader#validationresults) in the manifest JSON reference. From 8e50d882e94289ac4bf19b2903cd25af651c74ae Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 11 Sep 2025 16:32:21 -0700 Subject: [PATCH 21/21] missed commits --- docs/manifest/reading/legacy.md | 19 +++++++++++-------- docs/manifest/reading/validation.md | 9 +++++++-- docs/manifest/writing/ingredients.md | 5 +---- 3 files changed, 19 insertions(+), 14 deletions(-) diff --git a/docs/manifest/reading/legacy.md b/docs/manifest/reading/legacy.md index d4d3836..e32a349 100644 --- a/docs/manifest/reading/legacy.md +++ b/docs/manifest/reading/legacy.md @@ -8,28 +8,30 @@ As much as possible, an application should **write** manifest data that conforms ## Legacy ingredients Old manifests may contain these kinds of deprecated ingredient data: + - V1 ingredients, with labels that begin with `c2pa.ingredient`. - V2 ingredients, with labels that begin with `c2pa.ingredient.v2`. - +While these labels will show up so you can detect them, the API will return the same ingredient object for all of them, but the field contents may vary depending on the version. -
-Should we say anything more about reading v1 and v2 ingredients? -
## Legacy actions Existing manifests may contain two versions of actions: original v1 actions, with label `c2pa.actions`, and revised v2 actions, with label `c2pa.actions.v2`. While a v1 action is fully specified in its actions array, 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. - +As with Ingredients, a single `Actions` object handles both versions of actions. The label will be different for each version, and you may want to to check for both labels or use `starts_with`. + + ## Legacy metadata assertions Existing manifests may contain individual assertions for each metadata standard: + - [Exif assertion](#exif-assertion) - [IPTC metadata assertion](#iptc-metadata-assertion) - [Creative Work assertion](#creative-work-assertion) @@ -148,6 +150,7 @@ For example: ## Legacy training and data mining assertion Old manifests may have training and data mining assertions with the following entry keys: + - `c2pa.data_mining` - `c2pa.ai_training` - `c2pa.ai_generative_training` diff --git a/docs/manifest/reading/validation.md b/docs/manifest/reading/validation.md index 52efc78..565250e 100644 --- a/docs/manifest/reading/validation.md +++ b/docs/manifest/reading/validation.md @@ -5,9 +5,14 @@ title: Validating manifests Processing an asset includes [validating the manifests](https://c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_validation) in the associated manifest store. During validation, errors can occur in the active manifest and in ingredients. -In the latest version of the SDK, +In the latest version of the SDK: + - Builder performs validation by default, so you can't create an invalid manifest. Previously, the SDK was permissive in this regard. -- Validation is much stricter +- Validation is much stricter. + +::: note +There is a setting to disable full validation when signing. +:::
Need a high-level summary of full validation, what we're looking for, etc. diff --git a/docs/manifest/writing/ingredients.md b/docs/manifest/writing/ingredients.md index 7499893..c449e1a 100644 --- a/docs/manifest/writing/ingredients.md +++ b/docs/manifest/writing/ingredients.md @@ -64,13 +64,10 @@ Note that `parentOf` ingredients must have a matching `c2pa.opened` action as th See [Validation results](json-ref/reader#validationresults) in the manifest JSON reference. When ingredients are added, the SDK validates their Content Credentials (if any). However, the validation status of an ingredient does not imply anything about the validation status of the composed asset containing the ingredient. In other words: + - A composed asset's Content Credentials may be valid, but one or more of its ingredients may have invalid Content Credentials. For example, test file [adobe-20220124-XCA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-XCA.jpg) - A composed asset's Content Credentials may be invalid, but one or more of its ingredients may have valid Content Credentials. For example, test file [adobe-20220124-CIE-sig-CA.jpg](https://contentcredentials.org/verify?source=https://c2pa.org/public-testfiles/image/jpeg/adobe-20220124-CIE-sig-CA.jpg). :::note Ingredient certificates are validated when they are added to the manifest store, NOT during validation of the composed asset. ::: - - - -