Function normalizeDiscoveredSignal

Parameters

• signal: {
      restricted_attributes?: RestrictedAttribute[];
      demographic_predicate?: DemographicPredicate;
      policy_categories?: string[];
      taxonomy?: {
          ref: string;
          version?: string;
          segtax?: number;
          etag?: string;
          values: { id: string; path?: string; modifiers?: string[] }[];
          value_mappings?: {
              value: string;
              taxonomy_value_id: string;
              path?: string;
              modifiers?: string[];
          }[];
          parent_match_behavior?: "unknown"
          | "exact_only"
          | "descendants_supported";
      };
      segmentation_criteria?: string;
      criteria_url?: string;
      data_sources?: (
          | "email"
          | "app_behavior"
          | "app_usage"
          | "web_usage"
          | "geo_location"
          | "tv_ott_or_stb_device"
          | "panel"
          | "online_ecommerce"
          | "credit_data"
          | "loyalty_card"
          | "transaction"
          | "online_survey"
          | "offline_survey"
          | "public_record_census"
          | "public_record_voter_file"
          | "public_record_other"
          | "offline_transaction"
      )[];
      methodology?: "declared"
      | "inferred"
      | "modeled"
      | "observed"
      | "derived";
      audience_expansion?: boolean;
      device_expansion?: boolean;
      refresh_cadence?:
          | "daily"
          | "weekly"
          | "monthly"
          | "quarterly"
          | "intra_day"
          | "bi_monthly"
          | "bi_annually"
          | "annually";
      lookback_window?: | "daily"
      | "weekly"
      | "monthly"
      | "quarterly"
      | "intra_day"
      | "bi_monthly"
      | "bi_annually"
      | "annually";
      onboarder?: {
          match_keys: (
              | "email"
              | "name"
              | "address"
              | "postal"
              | "lat_long"
              | "mobile_id"
              | "cookie_id"
              | "ip"
              | "customer_id"
              | "phone"
          )[];
          pre_onboarding_audience_expansion?: boolean;
          pre_onboarding_device_expansion?: boolean;
          pre_onboarding_precision_level?: | "individual"
          | "household"
          | "business"
          | "geography";
      };
      countries?: string[];
      consent_basis?: ConsentBasis[];
      art9_basis?: | "explicit_consent"
      | "manifestly_made_public"
      | "substantial_public_interest"
      | "vital_interests";
      modeling?: {
          method: "lookalike"
          | "supervised"
          | "embedding"
          | "rules";
          seed_source: {
              type:
                  | "panel"
                  | "first_party_crm"
                  | "declared_survey"
                  | "transactional"
                  | "behavioral";
              provider_signed: boolean;
          };
          training_data_jurisdictions: string[];
          ai_act_risk_class: "limited"
          | "minimal"
          | "high_risk";
          disclosure?: {
              required: boolean;
              jurisdictions?: [
                  {
                      country: string;
                      region?: string;
                      regulation: string;
                      disclosure_text?: string;
                      disclosure_url?: string;
                      audience?: "buyer"
                      | "public"
                      | "data_subject"
                      | "regulator";
                  },
                  ...{
                      country: string;
                      region?: string;
                      regulation: string;
                      disclosure_text?: string;
                      disclosure_url?: string;
                      audience?: "buyer"
                      | "public"
                      | "data_subject"
                      | "regulator";
                  }[],
              ];
              notes?: string;
          };
      };
      data_subject_rights?: {
          upstream_source_domain?: string;
          channels: {
              rights: (
                  "access"
                  | "rectification"
                  | "erasure"
                  | "portability"
                  | "objection"
              )[];
              url?: string;
              email?: string;
              languages?: string[];
              countries?: string[];
          }[];
          response_sla_days?: number;
          ccpa_opt_out_url?: string;
      };
      last_updated?: string;
      dts_compliant_version?: string;
      signal_ref?: SignalRef;
      signal_id?: SignalID;
      name: string;
      description: string;
      methodology_url?: string;
      value_type?: SignalValueType;
      categories?: string[];
      range?: { min: number; max: number };
      signal_agent_segment_id: string;
      signal_type: SignalAvailabilityType;
      data_provider?: string;
      coverage_percentage?: number;
      coverage_forecast?: {
          points: [
              ForecastPoint & { dimensions: {}; metrics?: {} },
              ...(ForecastPoint & { dimensions: {}; metrics?: {} })[],
          ];
          forecast_range_unit: "availability";
          method: ForecastMethod;
          scope: {
              kind: "product" | "inventory" | "custom" | "account";
              label: string;
              product_id?: string;
              countries?: [string, ...string[]];
              line_item_types?: [string, ...string[]];
              date_range?: DateRange;
          };
          bucket_semantics: "exclusive"
          | "overlapping";
          bucket_completeness: "complete" | "partial";
          generated_at?: string;
          valid_until?: string;
          ext?: ExtensionObject;
      };
      deployments: Deployment[];
      pricing_options?: VendorPricingOption[];
  }

  • Optionalrestricted_attributes?: RestrictedAttribute[]

    Restricted attribute categories this listing touches. Required with demographic_predicate and must include age. For referenced provider/source signals, any projected values must match the authoritative definition.

  • Optionaldemographic_predicate?: DemographicPredicate

  • Optionalpolicy_categories?: string[]

    Policy categories this signal is sensitive for.

  • Optionaltaxonomy?: {
        ref: string;
        version?: string;
        segtax?: number;
        etag?: string;
        values: { id: string; path?: string; modifiers?: string[] }[];
        value_mappings?: {
            value: string;
            taxonomy_value_id: string;
            path?: string;
            modifiers?: string[];
        }[];
        parent_match_behavior?: "unknown"
        | "exact_only"
        | "descendants_supported";
    }

    Optional taxonomy metadata describing what this signal means in an external audience, content, retail-media, or provider-owned taxonomy.

  • Optionalsegmentation_criteria?: string

  • Optionalcriteria_url?: string

  • Optionaldata_sources?: (
        | "email"
        | "app_behavior"
        | "app_usage"
        | "web_usage"
        | "geo_location"
        | "tv_ott_or_stb_device"
        | "panel"
        | "online_ecommerce"
        | "credit_data"
        | "loyalty_card"
        | "transaction"
        | "online_survey"
        | "offline_survey"
        | "public_record_census"
        | "public_record_voter_file"
        | "public_record_other"
        | "offline_transaction"
    )[]

  • Optionalmethodology?: "declared" | "inferred" | "modeled" | "observed" | "derived"

  • Optionalaudience_expansion?: boolean

  • Optionaldevice_expansion?: boolean

  • Optionalrefresh_cadence?:
        | "daily"
        | "weekly"
        | "monthly"
        | "quarterly"
        | "intra_day"
        | "bi_monthly"
        | "bi_annually"
        | "annually"

  • Optionallookback_window?:
        | "daily"
        | "weekly"
        | "monthly"
        | "quarterly"
        | "intra_day"
        | "bi_monthly"
        | "bi_annually"
        | "annually"

  • Optionalonboarder?: {
        match_keys: (
            | "email"
            | "name"
            | "address"
            | "postal"
            | "lat_long"
            | "mobile_id"
            | "cookie_id"
            | "ip"
            | "customer_id"
            | "phone"
        )[];
        pre_onboarding_audience_expansion?: boolean;
        pre_onboarding_device_expansion?: boolean;
        pre_onboarding_precision_level?: | "individual"
        | "household"
        | "business"
        | "geography";
    }

  • Optionalcountries?: string[]

  • Optionalconsent_basis?: ConsentBasis[]

    Data provider's declared GDPR Article 6 lawful basis or consent basis for the underlying signal definition, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own processing basis for the provider-declared basis.

  • Optionalart9_basis?:
        | "explicit_consent"
        | "manifestly_made_public"
        | "substantial_public_interest"
        | "vital_interests"

    Data provider's declared GDPR Article 9 basis for the underlying signal definition when special-category data is involved and Article 9 applies, projected into this get_signals response row when requested. Sellers and federating agents that pass through another provider's signal MUST NOT substitute their own Article 9 basis for the provider-declared basis.

  • Optionalmodeling?: {
        method: "lookalike" | "supervised" | "embedding" | "rules";
        seed_source: {
            type:
                | "panel"
                | "first_party_crm"
                | "declared_survey"
                | "transactional"
                | "behavioral";
            provider_signed: boolean;
        };
        training_data_jurisdictions: string[];
        ai_act_risk_class: "limited"
        | "minimal"
        | "high_risk";
        disclosure?: {
            required: boolean;
            jurisdictions?: [
                {
                    country: string;
                    region?: string;
                    regulation: string;
                    disclosure_text?: string;
                    disclosure_url?: string;
                    audience?: "buyer"
                    | "public"
                    | "data_subject"
                    | "regulator";
                },
                ...{
                    country: string;
                    region?: string;
                    regulation: string;
                    disclosure_text?: string;
                    disclosure_url?: string;
                    audience?: "buyer"
                    | "public"
                    | "data_subject"
                    | "regulator";
                }[],
            ];
            notes?: string;
        };
    }

    • method: "lookalike" | "supervised" | "embedding" | "rules"

    • seed_source: {
          type:
              | "panel"
              | "first_party_crm"
              | "declared_survey"
              | "transactional"
              | "behavioral";
          provider_signed: boolean;
      }

      • type: "panel" | "first_party_crm" | "declared_survey" | "transactional" | "behavioral"

      • provider_signed: boolean

        Provider assertion that the seed source carries a signed attestation. Consumers MUST NOT treat this boolean alone as cryptographic proof.

    • training_data_jurisdictions: string[]

    • ai_act_risk_class: "limited" | "minimal" | "high_risk"

    • Optionaldisclosure?: {
          required: boolean;
          jurisdictions?: [
              {
                  country: string;
                  region?: string;
                  regulation: string;
                  disclosure_text?: string;
                  disclosure_url?: string;
                  audience?: "buyer"
                  | "public"
                  | "data_subject"
                  | "regulator";
              },
              ...{
                  country: string;
                  region?: string;
                  regulation: string;
                  disclosure_text?: string;
                  disclosure_url?: string;
                  audience?: "buyer"
                  | "public"
                  | "data_subject"
                  | "regulator";
              }[],
          ];
          notes?: string;
      }

      • required: boolean

        The provider's claim that a modeling or AI-use disclosure is required for this signal in at least one applicable jurisdiction. This is a declared compliance signal, not a protocol-level legal determination.

      • Optionaljurisdictions?: [
            {
                country: string;
                region?: string;
                regulation: string;
                disclosure_text?: string;
                disclosure_url?: string;
                audience?: "buyer"
                | "public"
                | "data_subject"
                | "regulator";
            },
            ...{
                country: string;
                region?: string;
                regulation: string;
                disclosure_text?: string;
                disclosure_url?: string;
                audience?: "buyer"
                | "public"
                | "data_subject"
                | "regulator";
            }[],
        ]

        Jurisdictions where a modeling or AI-use disclosure applies.

        Min Items

        1

      • Optionalnotes?: string

        Optional provider notes on how the disclosure should be interpreted. Informational only; buyers should not branch programmatically on this text.

  • Optionaldata_subject_rights?: {
        upstream_source_domain?: string;
        channels: {
            rights: (
                "access"
                | "rectification"
                | "erasure"
                | "portability"
                | "objection"
            )[];
            url?: string;
            email?: string;
            languages?: string[];
            countries?: string[];
        }[];
        response_sla_days?: number;
        ccpa_opt_out_url?: string;
    }

    Per-signal data-subject-rights routing. This is a contact/routing reference, not a machine-callable AdCP API.

  • Optionallast_updated?: string

    When this listing record was last updated. This indicates freshness of the listing record, not an attestation that the underlying data or model was refreshed at that time.

  • Optionaldts_compliant_version?: string

  • Optionalsignal_ref?: SignalRef

  • Optionalsignal_id?: SignalID

  • name: string

    Human-readable signal name

  • description: string

    Detailed signal description

  • Optionalmethodology_url?: string

    Optional link to published methodology, media-kit, or data documentation. For data_provider and signal_source refs, this SHOULD match or supplement the referenced definition.

  • Optionalvalue_type?: SignalValueType

  • Optionalcategories?: string[]

    Valid values for categorical signals. Present when value_type is 'categorical'. Buyers must use one of these values in SignalTargeting.values.

  • Optionalrange?: { min: number; max: number }

    Valid range for numeric signals. Present when value_type is 'numeric'.

    • min: number

      Minimum value (inclusive)

    • max: number

      Maximum value (inclusive)

  • signal_agent_segment_id: string

    Opaque resolved-segment handle issued by this signal source. Pass this string verbatim to activate_signal.signal_agent_segment_id, and echo it in package signal targeting when the selected product option exposes the same handle. Treat the value as provider-scoped and opaque: providers MAY namespace it so two providers can expose similarly named signals without relying on a shared taxonomy. Do not pass the signal_id object as this handle, and do not reconstruct a segment handle from categorical values when get_signals returned a resolved segment.

  • signal_type: SignalAvailabilityType

  • Optionaldata_provider?: string

    Human-readable source name for the signal, when applicable. For data_provider-scoped signals this is the data provider name; for signal_source-scoped signals it may identify the signal source or proprietary origin.

  • Optionalcoverage_percentage?: number

    Deprecated

    DEPRECATED for detailed planning. Optional legacy scalar percentage of audience coverage retained only as a fallback for clients that do not consume coverage_forecast. When coverage_forecast is present, coverage_forecast is authoritative for signal-level discovery and coverage_percentage is fallback-only. If coverage_forecast includes an absent bucket over the same denominator, coverage_percentage SHOULD align with 100 * (1 - absent coverage_rate.mid).

    Minimum

    0

    Maximum

    100

  • Optionalcoverage_forecast?: {
        points: [
            ForecastPoint & { dimensions: {}; metrics?: {} },
            ...(ForecastPoint & { dimensions: {}; metrics?: {} })[],
        ];
        forecast_range_unit: "availability";
        method: ForecastMethod;
        scope: {
            kind: "product" | "inventory" | "custom" | "account";
            label: string;
            product_id?: string;
            countries?: [string, ...string[]];
            line_item_types?: [string, ...string[]];
            date_range?: DateRange;
        };
        bucket_semantics: "exclusive"
        | "overlapping";
        bucket_completeness: "complete" | "partial";
        generated_at?: string;
        valid_until?: string;
        ext?: ExtensionObject;
    }

    • points: [
          ForecastPoint & { dimensions: {}; metrics?: {} },
          ...(ForecastPoint & { dimensions: {}; metrics?: {} })[],
      ]

      Coverage or availability points. Each point reuses the standard ForecastPoint shape, MUST include a signal dimension, and MUST include metrics.coverage_rate. Use metrics.impressions for count denominators and metrics.coverage_rate for the fraction of the declared scope represented by the point.

      Min Items

      1

    • forecast_range_unit: "availability"

      How to interpret the points array. Signal coverage forecasts always use 'availability' because the points describe available inventory or population coverage, not spend curves or temporal pacing.

    • method: ForecastMethod

    • scope: {
          kind: "product" | "inventory" | "custom" | "account";
          label: string;
          product_id?: string;
          countries?: [string, ...string[]];
          line_item_types?: [string, ...string[]];
          date_range?: DateRange;
      }

      Explicit denominator for the coverage forecast. This identifies the inventory, product, account, or custom universe that coverage_rate values are relative to. Additional seller-specific qualifiers are allowed for scopes such as line item type, ad server, inventory class, country, or flight window.

      • kind: "product" | "inventory" | "custom" | "account"

        Denominator family for the coverage forecast.

      • label: string

        Human-readable denominator label, such as 'network price-priority inventory'.

      • Optionalproduct_id?: string

        Product denominator when kind is 'product'.

      • Optionalcountries?: [string, ...string[]]

        Countries included in the denominator, as ISO 3166-1 alpha-2 codes.

        Min Items

        1

      • Optionalline_item_types?: [string, ...string[]]

        Seller or ad-server line item types included in the denominator.

        Min Items

        1

      • Optionaldate_range?: DateRange

    • bucket_semantics: "exclusive" | "overlapping"

      'exclusive' means the returned signal-value buckets do not overlap with each other. 'overlapping' means one impression or user can appear in multiple returned buckets, so coverage_rate values may sum above 1.0. This field describes overlap among returned buckets; bucket_completeness declares whether the returned buckets cover the full denominator.

    • bucket_completeness: "complete" | "partial"

      'complete' means the returned buckets cover the declared denominator. For complete + exclusive forecasts, count metrics and coverage_rate values can be treated as a full partition, subject to metric additivity rules. 'partial' means omitted denominator share represents undisclosed, other, or unsupported buckets; buyers MUST NOT infer totals by summing returned points.

    • Optionalgenerated_at?: string

      When this coverage forecast was computed.

    • Optionalvalid_until?: string

      When this coverage forecast expires.

    • Optionalext?: ExtensionObject

  • deployments: Deployment[]

    Array of deployment targets

  • Optionalpricing_options?: VendorPricingOption[]

    Pricing options available for this signal when it has an incremental price. The buyer selects one and passes its pricing_option_id in report_usage or package-level signal_targeting_groups for billing verification. Omit when pricing is unavailable to the caller, bundled into the destination product, or has no incremental cost.