more cleanup

Author: crandmck

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.
 
-<div class="review-comment">
-For READING old claims (only) … v1 actions and ingredients
-</div>
-
 ## 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.
+
+<div class="review-comment">
+What should we say about reading v1 and v2 ingredients?
+</div>
 
 ## 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.
 
+<div class="review-comment">
+What should we say about reading v1 actions?
+</div>
+
 ## 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`

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.
 
-<div class="review-comment">
-Revise to focus on reading these assertions.
-</div>
-
 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.
 

docs/manifest/writing/assertions-actions.md

@@ -31,21 +31,19 @@ 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
 
 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.
 
 <div class="review-comment">
-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?
 </div>
 
 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 `<TOOL_NAME>` 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.
 :::
 
 

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": [

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.
+
+<div class="review-comment">
+This page should cover only v3 ingredients.
+</div>
 
 :::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.