Builder reference

note

This is a beta release of this reference. It is a work in progress and may have issues or errors.

Builder

Use a Builder to add a signed manifest to an asset.

Properties

Property	Type	Description	Required?	Default Value
assertions	Array of AssertionDefinition	A list of assertions	NO	[]
claim_generator_info	Array of ClaimGeneratorInfo	Software that generated the claim, as a list of `ClaimGeneratorInfo`. In JSON, when this key is omitted (or the array is empty), the value is resolved at claim-building time: settings.builder.claim_generator_info if set, otherwise on the active `Context` is used if set, otherwise `ClaimGeneratorInfo::default`. A non-empty list in the definition is used as given.	NO	N/A
claim_version	Integer	The version of the claim. Defaults to 2.	NO	N/A
format	String	The format of the source file as a MIME type.	NO	"application/octet-stream"
hash_alg	String	Hash algorithm used for asset hashing (DataHash, BmffHash) and assertion hashing in the claim. Defaults to `"sha256"` when not set. Valid values: `"sha256"`, `"sha384"`, `"sha512"`. This sets the claim-level `alg` field and is the default used by `Builder::update_hash_from_stream`. It can be overridden on individual hard binding assertions (e.g. a pre-constructed `DataHash`) by setting the assertion's own `alg` field before adding it to the builder. Named `hash_alg` (rather than `alg`) to avoid collision with the signer's signature algorithm, which uses the same key in some combined JSON configurations.	NO	N/A
ingredients	Array of Ingredient	A List of ingredients	NO	[]
instance_id	String	Instance ID from `xmpMM:InstanceID` in XMP metadata.	NO	"xmp:iid:1ff4f129-6187-4f95-8910-01b36ffe60d0"
intent	Either BuilderIntent or Null	A builder should construct a created, opened or updated manifest.	NO	N/A
label	String	Allows you to pre-define the manifest label, which must be unique. Not intended for general use. If not set, it will be assigned automatically.	NO	N/A
metadata	Array of AssertionMetadata	Optional manifest metadata. This will be deprecated in the future; not recommended to use.	NO	N/A
no_embed	Boolean	If true, the manifest store will not be embedded in the asset on sign.	YES	N/A
redactions	Array of String	JUMBF URIs of assertions to redact from ingredient manifests. Each URI has the form `self#jumbf=/c2pa//c2pa.assertions/`. Use a `Reader` to discover the manifest label. See the redaction guide for details.	NO	N/A
remote_url	String	Optional remote URL for the manifest.	NO	N/A
thumbnail	Either ResourceRef or Null	An optional ResourceRef to a thumbnail image that represents the asset that was signed. Must be available when the manifest is signed.	NO	N/A
timestamp_manifest_labels	Array of String	Manifest labels to fetch timestamps for. Examples of a manifest label may include: - `contentauth:urn:uuid:c2677d4b-0a93-4444-876f-ed2f2d40b8cf` - `urn:c2pa:fa479510-2a7d-c165-7b26-488a267f4c6a`	YES	N/A
title	String	A human-readable title, generally source filename.	NO	N/A
vendor	String	Optional prefix added to the generated Manifest Label This is typically a reverse domain name.	NO	N/A

Definitions

Actor

DateT

Frame

IngredientDeltaValidationResult

Item

ManifestAssertionKind

Range

Role

Shape

Text

Time

Actor

Identifies a person responsible for an action.

Property	Type	Description	Required?	Default Value
credentials	Array of HashedUri	List of references to W3C Verifiable Credentials.	NO	N/A
identifier	String	An identifier for a human actor, used when the "type" is `humanEntry.identified`.	NO	N/A

AssertionData

This allows the assertion to be expressed as CBOR or JSON. The default is CBOR unless you specify that an assertion should be JSON.

Property	Type	Description	Required?	Default Value
type	Either N/A	This allows the assertion to be expressed as CBOR or JSON. The default is CBOR unless you specify that an assertion should be JSON.	NO	N/A

AssertionDefinition

Defines an assertion that consists of a label that can be either a C2PA-defined assertion label or a custom label in reverse domain format.

Property	Type	Description	Required?	Default Value
created	Boolean	True if this assertion is attributed to the signer (defaults to false)	NO	N/A
data	AssertionData	The assertion data	YES	N/A
kind	Either ManifestAssertionKind or Null	The kind of assertion data, either Cbor or Json (defaults to Cbor)	NO	N/A
label	String	An assertion label in reverse domain format	YES	N/A

AssertionMetadata

The AssertionMetadata structure can be used as part of other assertions or on its own to reference others

Property	Type	Description	Required?	Default Value
dataSource	Either DataSource or Null	N/A	NO	N/A
dateTime	Either DateT or Null	N/A	NO	N/A
localizations	Array of Object	N/A	NO	N/A
reference	Either HashedUri or Null	N/A	NO	N/A
regionOfInterest	Either RegionOfInterest or Null	N/A	NO	N/A
reviewRatings	Array of ReviewRating	N/A	NO	N/A

AssetType

Property	Type	Description	Required?	Default Value
type	String	N/A	YES	N/A
version	String	N/A	NO	N/A

BuilderIntent

Represents the type of builder flow being used.

This determines how the builder will be used, such as creating a new asset, opening an existing asset, or updating an existing asset.

Type	Description	Value
Object	This is a new digital creation, a DigitalSourceType is required. The Manifest must not have have a parent ingredient. A `c2pa.created` action will be added if not provided.	Object (see below)
String	This is an edit of a pre-existing parent asset. The Manifest must have a parent ingredient. A parent ingredient will be generated from the source stream if not otherwise provided. A `c2pa.opened action will be tied to the parent ingredient.	edit
String	A restricted version of Edit for non-editorial changes. There must be only one ingredient, as a parent. No changes can be made to the hashed content of the parent. There are additional restrictions on the types of changes that can be made.	update

Property	Type	Description	Required?	Default Value
create	DigitalSourceType	N/A	YES	N/A

ClaimGeneratorInfo

Description of the claim generator, or the software used in generating the claim.

This structure is also used for actions softwareAgent

Property	Type	Description	Required?	Default Value
icon	Either UriOrResource or Null	hashed URI to the icon (either embedded or remote)	NO	N/A
name	String	A human readable string naming the claim_generator	YES	N/A
operating_system	String	A human readable string of the OS the claim generator is running on. CrJSON schema uses `operating_system`; C2PA CBOR may use `schema.org.SoftwareApplication.operatingSystem`.	NO	N/A
version	String	A human readable string of the product's version	NO	N/A

Coordinate

An x, y coordinate used for specifying vertices in polygons.

Property	Type	Description	Required?	Default Value
x	Number	The coordinate along the x-axis.	YES	N/A
y	Number	The coordinate along the y-axis.	YES	N/A

DataSource

A description of the source for assertion data

Property	Type	Description	Required?	Default Value
actors	Array of Actor	A list of `Actor`s associated with this source.	NO	N/A
details	String	A human-readable string giving details about the source of the assertion data.	NO	N/A
type	String	A value from among the enumerated list indicating the source of the assertion.	YES	N/A

DateT

Property	Type	Description	Required?	Default Value
type	String	N/A	NO	N/A

DigitalSourceType

Description of the source of an asset.

The digital source type must be either a value from the IPTC Digital Source Types or a C2PA-specific value as given in the C2PA Technical Specification.

Type	Description	Value
String	Media whose digital content is effectively empty, such as a blank canvas or zero-length video.	http://c2pa.org/digitalsourcetype/empty
String	Data that is the result of algorithmically using a model derived from sampled content and data. Differs from IPTC Digital Source Type `trainedAlgorithmicMedia` in that the result isn’t a media type (e.g., image or video) but is a data format (e.g., CSV, pickle).	http://c2pa.org/digitalsourcetype/trainedAlgorithmicData
String	The media was captured from a real-life source using a digital camera or digital recording device.	http://cv.iptc.org/newscodes/digitalsourcetype/digitalCapture
String	The media is the result of capturing multiple frames from a real-life source using a digital camera or digital recording device, then automatically merging them into a single frame using digital signal processing techniques and/or non-generative AI. Includes High Dynamic Range (HDR) processing common in smartphone camera apps.	http://cv.iptc.org/newscodes/digitalsourcetype/computationalCapture
String	The media was digitised from a negative on film or other transparent medium.	http://cv.iptc.org/newscodes/digitalsourcetype/negativeFilm
String	The media was digitised from a positive on a transparency or other transparent medium.	http://cv.iptc.org/newscodes/digitalsourcetype/positiveFilm
String	The media was digitised from a non-transparent medium such as a photographic print.	http://cv.iptc.org/newscodes/digitalsourcetype/print
String	Minor augmentation or correction by a human, such as a digitally-retouched photo used in a magazine.	http://cv.iptc.org/newscodes/digitalsourcetype/minorHumanEdits
String	Augmentation, correction or enhancement by one or more humans using non-generative tools.	http://cv.iptc.org/newscodes/digitalsourcetype/humanEdits
String	Augmentation, correction or enhancement using a Generative AI model, such as with inpainting or outpainting operations.	http://cv.iptc.org/newscodes/digitalsourcetype/compositeWithTrainedAlgorithmicMedia
String	Modification or correction by algorithm without changing the main content of the media, initiated or configured by a human, such as sharpening or applying noise reduction.	http://cv.iptc.org/newscodes/digitalsourcetype/algorithmicallyEnhanced
String	The digital image was created by computer software.	http://cv.iptc.org/newscodes/digitalsourcetype/softwareImage
String	Media created by a human using digital tools.	http://cv.iptc.org/newscodes/digitalsourcetype/digitalArt
String	Media created by a human using non-generative tools.	http://cv.iptc.org/newscodes/digitalsourcetype/digitalCreation
String	Digital media representation of data via human programming or creativity.	http://cv.iptc.org/newscodes/digitalsourcetype/dataDrivenMedia
String	Digital media created algorithmically using an Artificial Intelligence model trained on captured content.	http://cv.iptc.org/newscodes/digitalsourcetype/trainedAlgorithmicMedia
String	Media created purely by an algorithm not based on any sampled training data, e.g. an image created by software using a mathematical formula.	http://cv.iptc.org/newscodes/digitalsourcetype/algorithmicMedia
String	A capture of the contents of the screen of a computer or mobile device.	http://cv.iptc.org/newscodes/digitalsourcetype/screenCapture
String	Live recording of virtual event based on Generative AI and/or captured elements.	http://cv.iptc.org/newscodes/digitalsourcetype/virtualRecording
String	Mix or composite of several elements, any of which may or may not be generative AI.	http://cv.iptc.org/newscodes/digitalsourcetype/composite
String	Mix or composite of several elements that are all captures of real life.	http://cv.iptc.org/newscodes/digitalsourcetype/compositeCapture
String	Mix or composite of several elements, at least one of which is Generative AI.	http://cv.iptc.org/newscodes/digitalsourcetype/compositeSynthetic
String	An unknown digital source type.	N/A

Frame

A frame range representing starting and ending frames or pages.

If both start and end are missing, the frame will span the entire asset.

Property	Type	Description	Required?	Default Value
end	Integer	The end of the frame inclusive or the end of the asset if not present.	NO	N/A
start	Integer	The start of the frame or the end of the asset if not present. The first frame/page starts at 0.	NO	N/A

HashedUri

A HashedUri provides a reference to content available within the same manifest store.

This is described in URI References in the C2PA Technical Specification.

Property	Type	Description	Required?	Default Value
alg	String	A string identifying the cryptographic hash algorithm used to compute the hash	NO	N/A
hash	Array of Integer	Byte string containing the hash value	YES	N/A
url	String	JUMBF URI reference	YES	N/A

Ingredient

An Ingredient is any external asset that has been used in the creation of an asset.

Property	Type	Description	Required?	Default Value
active_manifest	String	The active manifest label (if one exists). If this ingredient has a `ManifestStore`, this will hold the label of the active `Manifest`.	NO	N/A
data	Either ResourceRef or Null	A reference to the actual data of the ingredient.	NO	N/A
data_types	Array of AssetType	Additional information about the data's type to the ingredient V2 structure.	NO	N/A
description	String	Additional description of the ingredient.	NO	N/A
document_id	String	Document ID from `xmpMM:DocumentID` in XMP metadata.	NO	N/A
format	String	The format of the source file as a MIME type.	NO	N/A
hash	String	An optional hash of the asset to prevent duplicates.	NO	N/A
informational_URI	String	URI to an informational page about the ingredient or its data.	NO	N/A
instance_id	String	Instance ID from `xmpMM:InstanceID` in XMP metadata.	NO	N/A
label	String	The ingredient's label as assigned in the manifest.	NO	N/A
manifest_data	Either ResourceRef or Null	A `ManifestStore` from the source asset extracted as a binary C2PA blob.	NO	N/A
metadata	Either AssertionMetadata or Null	Any additional `Metadata` as defined in the C2PA spec.	NO	N/A
ocsp_responses	Array of ResourceRef	N/A	NO	N/A
provenance	String	URI from `dcterms:provenance` in XMP metadata.	NO	N/A
relationship	Relationship	Set to `ParentOf` if this is the parent ingredient. There can only be one parent ingredient in the ingredients.	NO	"componentOf"
thumbnail	Either ResourceRef or Null	A thumbnail image capturing the visual state at the time of import. A tuple of thumbnail MIME format (for example `image/jpeg`) and binary bits of the image.	NO	N/A
title	String	A human-readable title, generally source filename.	NO	N/A
validation_results	Either ValidationResults or Null	Validation results (Ingredient.V3)	NO	N/A
validation_status	Array of ValidationStatus	Validation status (Ingredient v1 & v2)	NO	N/A

IngredientDeltaValidationResult

Represents any changes or deltas between the current and previous validation results for an ingredient's manifest.

Property	Type	Description	Required?	Default Value
ingredientAssertionURI	String	JUMBF URI reference to the ingredient assertion	YES	N/A
validationDeltas	StatusCodes	Validation results for the ingredient's active manifest	YES	N/A

Item

Description of the boundaries of an identified range.

Property	Type	Description	Required?	Default Value
identifier	String	The container-specific term used to identify items, such as "track_id" for MP4 or "item_ID" for HEIF.	YES	N/A
value	String	The value of the identifier, e.g. a value of "2" for an identifier of "track_id" would imply track 2 of the asset.	YES	N/A

ManifestAssertionKind

Assertions in C2PA can be stored in several formats

Property	Type	Description	Required?	Default Value
type	Enum (Cbor, Json, Binary, Uri)	Assertions in C2PA can be stored in several formats	NO	N/A

Range

A spatial, temporal, frame, or textual range describing the region of interest.

Property	Type	Description	Required?	Default Value
frame	Either Frame or Null	A frame range.	NO	N/A
item	Either Item or Null	A item identifier.	NO	N/A
shape	Either Shape or Null	A spatial range.	NO	N/A
text	Either Text or Null	A textual range.	NO	N/A
time	Either Time or Null	A temporal range.	NO	N/A
type	RangeType	The type of range of interest.	YES	N/A

RangeType

The type of range for the region of interest.

Type	Description	Value
String	A spatial range, see `Shape` for more details.	spatial
String	A temporal range, see `Time` for more details.	temporal
String	A spatial range, see `Frame` for more details.	frame
String	A textual range, see `Text` for more details.	textual
String	A range identified by a specific identifier and value, see `Item` for more details.	identified

RegionOfInterest

A region of interest within an asset describing the change.

This struct can be used from Action::changes, AssertionMetadata::region_of_interest, or SoftBindingScope::region.

Property	Type	Description	Required?	Default Value
description	String	A free-text string.	NO	N/A
identifier	String	A free-text string representing a machine-readable, unique to this assertion, identifier for the region.	NO	N/A
metadata	Either AssertionMetadata or Null	Additional information about the asset.	NO	N/A
name	String	A free-text string representing a human-readable name for the region which might be used in a user interface.	NO	N/A
region	Array of Range	A range describing the region of interest for the specific asset.	YES	N/A
role	Either Role or Null	A value from our controlled vocabulary or an entity-specific value (e.g., com.litware.coolArea) that represents the role of a region among other regions.	NO	N/A
type	String	A value from a controlled vocabulary such as https://cv.iptc.org/newscodes/imageregiontype/ or an entity-specific value (e.g., com.litware.newType) that represents the type of thing(s) depicted by a region. Note this field serializes/deserializes into the name `type`.	NO	N/A

Relationship

The relationship of the ingredient to the current asset.

Type	Description	Value
String	The current asset is derived from this ingredient.	parentOf
String	The current asset is a part of this ingredient.	componentOf
String	The ingredient was used as an input to a computational process to create or modify the asset.	inputTo

ResourceRef

A reference to a resource to be used in JSON serialization.

The underlying data can be read as a stream via Reader::resource_to_streamcrate::Reader::resource_to_stream.

Property	Type	Description	Required?	Default Value
alg	String	The algorithm used to hash the resource (if applicable).	NO	N/A
data_types	Array of AssetType	More detailed data types as defined in the C2PA spec.	NO	N/A
format	String	The mime type of the referenced resource.	YES	N/A
hash	String	The hash of the resource (if applicable).	NO	N/A
identifier	String	A URI that identifies the resource as referenced from the manifest. This may be a JUMBF URI, a file path, a URL or any other string. Relative JUMBF URIs will be resolved with the manifest label. Relative file paths will be resolved with the base path if provided.	YES	N/A

ReviewRating

A rating on an Assertion.

See C2PA Specification - Review Ratings.

Property	Type	Description	Required?	Default Value
code	String	N/A	NO	N/A
explanation	String	N/A	YES	N/A
value	Integer	N/A	YES	N/A

Role

A role describing the region.

Type	Description	Value
String	Arbitrary area worth identifying.	c2pa.areaOfInterest
String	This area is all that is left after a crop action.	c2pa.cropped
String	This area has had edits applied to it.	c2pa.edited
String	The area where an ingredient was placed/added.	c2pa.placed
String	Something in this area was redacted.	c2pa.redacted
String	Area specific to a subject (human or not).	c2pa.subjectArea
String	A range of information was removed/deleted.	c2pa.deleted
String	Styling was applied to this area.	c2pa.styled
String	Invisible watermarking was applied to this area for the purpose of soft binding.	c2pa.watermarked

Shape

A spatial range representing rectangle, circle, or a polygon.

Property	Type	Description	Required?	Default Value
height	Number	The height of a rectnagle. This field can be ignored for circles and polygons.	NO	N/A
inside	Boolean	If the range is inside the shape. The default value is true.	NO	N/A
origin	Coordinate	THe origin of the coordinate in the shape.	YES	N/A
type	ShapeType	The type of shape.	YES	N/A
unit	UnitType	The type of unit for the shape range.	YES	N/A
vertices	Array of Coordinate	The vertices of the polygon. This field can be ignored for rectangles and circles.	NO	N/A
width	Number	The width for rectangles or diameter for circles. This field can be ignored for polygons.	NO	N/A

ShapeType

The type of shape for the range.

Type	Description	Value
String	A rectangle.	rectangle
String	A circle.	circle
String	A polygon.	polygon

StatusCodes

Contains a set of success, informational, and failure validation status codes.

Property	Type	Description	Required?	Default Value
failure	Array of ValidationStatus	An array of validation failure codes. May be empty.	YES	N/A
informational	Array of ValidationStatus	An array of validation informational codes. May be empty.	YES	N/A
success	Array of ValidationStatus	An array of validation success codes. May be empty.	YES	N/A

Text

A textual range representing multiple (possibly discontinuous) ranges of text.

Property	Type	Description	Required?	Default Value
selectors	Array of TextSelectorRange	The ranges of text to select.	YES	N/A

TextSelector

Selects a range of text via a fragment identifier.

This is modeled after the W3C Web Annotation selector model.

Property	Type	Description	Required?	Default Value
end	Integer	The end character offset or the end of the fragment if not present.	NO	N/A
fragment	String	Fragment identifier as per RFC3023 (XML) or ISO 32000-2 (PDF), Annex O.	YES	N/A
start	Integer	The start character offset or the start of the fragment if not present.	NO	N/A

TextSelectorRange

One or two TextSelector identifiying the range to select.

Property	Type	Description	Required?	Default Value
end	Either TextSelector or Null	The end of the text range.	NO	N/A
selector	TextSelector	The start (or entire) text range.	YES	N/A

Time

A temporal range representing a starting time to an ending time.

Property	Type	Description	Required?	Default Value
end	String	The end time or the end of the asset if not present.	NO	N/A
start	String	The start time or the start of the asset if not present.	NO	N/A
type	TimeType	The type of time.	NO	"npt"

TimeType

The type of time.

Type	Description	Value
String	Times are described using Normal Play Time (npt) as described in RFC 2326.	npt

UnitType

The type of unit for the range.

Type	Description	Value
String	Use pixels.	pixel
String	Use percentage.	percent

UriOrResource

Type	Description	Value
ResourceRef	N/A	N/A
HashedUri	N/A	N/A

ValidationResults

A map of validation results for a manifest store.

The map contains the validation results for the active manifest and any ingredient deltas. It is normal for there to be many

Property	Type	Description	Required?	Default Value
activeManifest	Either StatusCodes or Null	Validation status codes for the ingredient's active manifest. Present if ingredient is a C2PA asset. Not present if the ingredient is not a C2PA asset.	NO	N/A
ingredientDeltas	Array of IngredientDeltaValidationResult	List of any changes/deltas between the current and previous validation results for each ingredient's manifest. Present if the the ingredient is a C2PA asset.	NO	N/A
validationTime	String	Time when the validation was performed (RFC 3339 date-time). Used only for document-level validationInfo; not serialized in validationResults (e.g. ingredient assertions).	NO	N/A

ValidationStatus

A ValidationStatus struct describes the validation status of a specific part of a manifest.

See Existing Manifests - C2PA Technical Specification.

Property	Type	Description	Required?	Default Value
code	String	N/A	YES	N/A
explanation	String	N/A	NO	N/A
success	Boolean	N/A	NO	N/A
url	String	N/A	NO	N/A