feat: add settings structs to the public API

cli/tests/fixtures/trust/cawg_sign_settings.toml

@@ -1,8 +1,7 @@
 # c2pa-rs Configuration File
 
 # Version information.
-version_major = 1
-version_minor = 0
+version = 1
 
 # Trust settings for certificate validation.
 # [trust]
@@ -220,13 +219,13 @@ xPd7wFhjRZHfuWb2cs63xjAGjQ==
 """
 # String to trust configuration.
 trust_config = """
-//id-kp-emailProtection 
+//id-kp-emailProtection
 1.3.6.1.5.5.7.3.4
-//id-kp-documentSigning 
+//id-kp-documentSigning
 1.3.6.1.5.5.7.3.36
-//id-kp-timeStamping 
+//id-kp-timeStamping
 1.3.6.1.5.5.7.3.8
-//id-kp-OCSPSigning 
+//id-kp-OCSPSigning
 1.3.6.1.5.5.7.3.9
 // MS C2PA Signing
 1.3.6.1.4.1.311.76.59.1.9
@@ -418,8 +417,8 @@ name = "c2pa-rs testing"
 version = "1.0.0"
 # The operating system the claim generator is running on.
 #operating_system.name = "macOS"
-# Or if the name isn't specified, it can be inferred automatically.
-operating_system.infer = true
+# Or specify "auto" to infer the operating system automatically.
+operating_system = "auto"
 # Arbitrary fields can also be defined.
 #
 # By default, the SDK adds a field "org.cai.c2pa_rs" with the value

sdk/examples/c2pa.toml

@@ -1,8 +1,7 @@
 # c2pa-rs Configuration File
 
 # Version information.
-version_major = 1
-version_minor = 0
+version = 1
 
 # # Trust settings for certificate validation.
 # [trust]
@@ -66,9 +65,8 @@ name = "My Service"
 # A human readable string of the product's version.
 version = "1.0.0"
 # The operating system the claim generator is running on.
-operating_system.name = "macOS"
-# Or if the name isn't specified, it can be inferred automatically.
-operating_system.infer = true
+# Or specify "auto" to infer the operating system automatically.
+operating_system = "macOS"
 # Arbitrary fields can also be defined.
 #
 # By default, the SDK adds a field "org.cai.c2pa_rs" with the value

sdk/src/settings/builder.rs

@@ -31,9 +31,10 @@ use crate::{
 ///
 /// These formats are a combination of types supported in [image-rs](https://docs.rs/image/latest/image/enum.ImageFormat.html)
 /// and types defined by the [IANA registry media type](https://www.iana.org/assignments/media-types/media-types.xhtml) (as defined in the spec).
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
-pub(crate) enum ThumbnailFormat {
+pub enum ThumbnailFormat {
     /// An image in PNG format.
     Png,
     /// An image in JPEG format.
@@ -46,9 +47,10 @@ pub(crate) enum ThumbnailFormat {
     Tiff,
 }
 /// Quality of the thumbnail.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
-pub(crate) enum ThumbnailQuality {
+pub enum ThumbnailQuality {
     /// Low quality.
     Low,
     /// Medium quality.
@@ -58,8 +60,9 @@ pub(crate) enum ThumbnailQuality {
 }
 
 /// Settings for controlling automatic thumbnail generation.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ThumbnailSettings {
+pub struct ThumbnailSettings {
     /// Whether or not to automatically generate thumbnails.
     pub enabled: bool,
     /// Whether to ignore thumbnail generation errors.
@@ -118,55 +121,44 @@ impl SettingsValidate for ThumbnailSettings {
 }
 
 /// Settings for the auto actions (e.g. created, opened, placed).
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct AutoActionSettings {
+pub struct AutoActionSettings {
     /// Whether to enable this auto action or not.
     pub enabled: bool,
     /// The default source type for the auto action.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub source_type: Option<DigitalSourceType>,
 }
 
-/// Settings for how to specify the claim generator info's operating system.
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ClaimGeneratorInfoOSSettings {
-    /// Whether or not to infer the operating system.
-    pub infer: bool,
+#[serde(untagged, rename_all = "lowercase")]
+pub enum ClaimGeneratorInfoOperatingSystem {
+    /// Whether or not to automatically infer the operating system.
+    Auto,
     /// The name of the operating system.
-    ///
-    /// Note this field overrides [ClaimGeneratorInfoOSSettings::infer].
-    pub name: Option<String>,
-}
-
-impl Default for ClaimGeneratorInfoOSSettings {
-    fn default() -> Self {
-        Self {
-            infer: true,
-            name: None,
-        }
-    }
+    Other(String),
 }
 
 /// Settings for the claim generator info.
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ClaimGeneratorInfoSettings {
+pub struct ClaimGeneratorInfoSettings {
     /// A human readable string naming the claim_generator.
     pub name: String,
     /// A human readable string of the product's version.
     #[serde(skip_serializing_if = "Option::is_none")]
     pub version: Option<String>,
     /// Reference to an icon.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub icon: Option<ResourceRef>,
+    pub(crate) icon: Option<ResourceRef>,
     /// Settings for the claim generator info's operating system field.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub operating_system: Option<ClaimGeneratorInfoOSSettings>,
+    pub operating_system: Option<ClaimGeneratorInfoOperatingSystem>,
     /// Any other values that are not part of the standard.
     #[serde(flatten)]
-    pub other: HashMap<String, toml::Value>,
+    pub other: HashMap<String, serde_json::Value>,
 }
 
 impl TryFrom<ClaimGeneratorInfoSettings> for ClaimGeneratorInfo {
@@ -178,11 +170,10 @@ impl TryFrom<ClaimGeneratorInfoSettings> for ClaimGeneratorInfo {
             version: value.version,
             icon: value.icon.map(UriOrResource::ResourceRef),
             operating_system: {
-                let os = value.operating_system.unwrap_or_default();
-                match os.infer {
-                    true => Some(consts::OS.to_owned()),
-                    false => os.name,
-                }
+                value.operating_system.map(|os| match os {
+                    ClaimGeneratorInfoOperatingSystem::Auto => consts::OS.to_owned(),
+                    ClaimGeneratorInfoOperatingSystem::Other(name) => name,
+                })
             },
             other: value
                 .other
@@ -198,6 +189,7 @@ impl TryFrom<ClaimGeneratorInfoSettings> for ClaimGeneratorInfo {
 }
 
 /// Settings for an action template.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub(crate) struct ActionTemplateSettings {
     /// The label associated with this action. See ([c2pa_action][crate::assertions::actions::c2pa_action]).
@@ -221,7 +213,7 @@ pub(crate) struct ActionTemplateSettings {
     pub description: Option<String>,
     /// Additional parameters for the template
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub template_parameters: Option<HashMap<String, toml::Value>>,
+    pub template_parameters: Option<HashMap<String, serde_json::Value>>,
 }
 
 impl TryFrom<ActionTemplateSettings> for ActionTemplate {
@@ -256,7 +248,6 @@ impl TryFrom<ActionTemplateSettings> for ActionTemplate {
 }
 
 /// Settings for an action.
-#[allow(unused)]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
 pub(crate) struct ActionSettings {
     /// The label associated with this action. See ([`c2pa_action`]).
@@ -323,33 +314,33 @@ impl TryFrom<ActionSettings> for Action {
 ///
 /// The reason this setting exists only for an [Actions][crate::assertions::Actions] assertion
 /// is because of its mandations and reusable fields.
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize)]
-pub(crate) struct ActionsSettings {
+pub struct ActionsSettings {
     /// Whether or not to set the [Actions::all_actions_included][crate::assertions::Actions::all_actions_included]
     /// field.
     pub all_actions_included: bool,
     /// Templates to be added to the [Actions::templates][crate::assertions::Actions::templates] field.
+    #[doc(hidden)]
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub templates: Option<Vec<ActionTemplateSettings>>,
-    // TODO: should we define a new struct for "Action" too, like ActionTemplateSettings?
-    /// Actions to be added to the [Actions::actions][crate::assertions::Actions::actions] field.
-    #[serde(skip_serializing_if = "Option::is_none")]
-    pub actions: Option<Vec<ActionSettings>>,
-    /// Whether to automatically generate a c2pa.created [Action][crate::assertions::Action]
-    /// assertion or error that it doesn't already exist.
+    pub(crate) templates: Option<Vec<ActionTemplateSettings>>,
+    //
+    // /// Actions to be added to the [Actions::actions][crate::assertions::Actions::actions] field.
+    // #[doc(hidden)]
+    // #[serde(skip_serializing_if = "Option::is_none")]
+    // pub(crate) actions: Option<Vec<ActionSettings>>,
+    //
+    /// Whether to automatically generate a c2pa.created [Action] assertion or error that it doesn't already exist.
     ///
     /// For more information about the mandatory conditions for a c2pa.created action assertion, see here:
     /// <https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_mandatory_presence_of_at_least_one_actions_assertion>
     pub auto_created_action: AutoActionSettings,
-    /// Whether to automatically generate a c2pa.opened [Action][crate::assertions::Action]
-    /// assertion or error that it doesn't already exist.
+    /// Whether to automatically generate a c2pa.opened [Action] assertion or error that it doesn't already exist.
     ///
     /// For more information about the mandatory conditions for a c2pa.opened action assertion, see here:
     /// <https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_mandatory_presence_of_at_least_one_actions_assertion>
     pub auto_opened_action: AutoActionSettings,
-    /// Whether to automatically generate a c2pa.placed [Action][crate::assertions::Action]
-    /// assertion or error that it doesn't already exist.
+    /// Whether to automatically generate a c2pa.placed [Action] assertion or error that it doesn't already exist.
     ///
     /// For more information about the mandatory conditions for a c2pa.placed action assertion, see:
     /// <https://spec.c2pa.org/specifications/specifications/2.2/specs/C2PA_Specification.html#_relationship>
@@ -361,7 +352,6 @@ impl Default for ActionsSettings {
         ActionsSettings {
             all_actions_included: true,
             templates: None,
-            actions: None,
             auto_created_action: AutoActionSettings {
                 enabled: true,
                 source_type: Some(DigitalSourceType::Empty),
@@ -389,9 +379,9 @@ impl SettingsValidate for ActionsSettings {
 
 // TODO: do more validation on URL fields, cert fields, etc.
 /// Settings for the [Builder][crate::Builder].
-#[allow(unused)]
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Clone, Debug, Deserialize, PartialEq, Serialize, Default)]
-pub(crate) struct BuilderSettings {
+pub struct BuilderSettings {
     /// Claim generator info that is automatically added to the builder.
     ///
     /// Note that this information will prepend any claim generator info
@@ -404,18 +394,21 @@ pub(crate) struct BuilderSettings {
     ///
     /// For more information on the reasoning behind this field see [ActionsSettings].
     pub actions: ActionsSettings,
-
-    // Certificate statuses will be fetched for either all the manifest labels, or just the active manifest.
-    pub certificate_status_fetch: Option<OcspFetch>,
-
-    // Whether or not existing OCSP responses should be overridden by new values.
+    // REVIEW NOTE: should this be in builder settings or core?
+    /// Certificate statuses will be fetched for either all the manifest labels, or just the active manifest.
+    pub certificate_status_fetch: Option<OcspFetchScope>,
+    /// Whether or not existing OCSP responses should be overridden by new values.
     pub certificate_status_should_override: Option<bool>,
 }
 
+/// The scope of which manifests to fetch for OCSP.
+#[cfg_attr(feature = "json_schema", derive(schemars::JsonSchema))]
 #[derive(Copy, Clone, Debug, Deserialize, PartialEq, Serialize)]
 #[serde(rename_all = "lowercase")]
-pub(crate) enum OcspFetch {
+pub enum OcspFetchScope {
+    /// Fetch OCSP for all manifests.
     All,
+    /// Fetch OCSP for the active manifest only.
     Active,
 }