Type Alias ProjectionDiagnostic

Type Declaration

• ProjectionDiagnosticBase & {
      code: "CANONICAL_PRODUCT_FORMATS_UNAVAILABLE";
      error: {
          details: {
              product_id: string;
              reason:
                  | "legacy_format_list_empty"
                  | "canonical_format_list_empty"
                  | "missing_format_declaration"
                  | "nested_placement_format_list_empty";
          };
      };
  }

  • code: "CANONICAL_PRODUCT_FORMATS_UNAVAILABLE"

    SDK-local code: a valid seller product cannot be represented on the canonical-only public surface because it has no canonical option. Legacy format_ids: [] is format-agnostic, not a failed lookup.

  • error: {
        details: {
            product_id: string;
            reason:
                | "legacy_format_list_empty"
                | "canonical_format_list_empty"
                | "missing_format_declaration"
                | "nested_placement_format_list_empty";
        };
    }

• ProjectionDiagnosticBase & {
      code: "FORMAT_PROJECTION_FAILED";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              resolution_failure:
                  | "no_registry_match"
                  | "catalog_lacks_canonical_annotation"
                  | "no_match"
                  | "custom_converter_failed"
                  | "invalid_format_id_parameters"
                  | "catalog_requirement_conflict";
              converter_error?: string;
          };
      };
  }

  • code: "FORMAT_PROJECTION_FAILED"

    Spec code (enums/error-code.json): registry-coverage gap or v1-catalog-coverage gap depending on resolution_failure:

    • no_registry_match — v2→v1 direction. Registry has no entries for this canonical (and v1_translatable is true).
    • catalog_lacks_canonical_annotation — v1→v2 direction. The AAO catalog has this v1 format but hasn't annotated it with a canonical: field. Native, DOOH, broadcast, and card-scaffolding categories sit in this bucket at 3.1 GA. Distinct from a generic registry gap — the catalog DOES know the format, it just hasn't blessed a v2 canonical mapping yet. Symmetric counterpart to CANONICAL_NOT_V1_TRANSLATABLE: that signals "no v1 form possible"; this signals "no v2 form yet."
    • no_match — v1→v2 direction, format not in catalog or registry, no structural match.
    • invalid_format_id_parameters — the legacy ref carries malformed dimensional or duration discriminators.
    • catalog_requirement_conflict — catalog-authored fixed requirements are internally ambiguous or contradict the ref.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            resolution_failure:
                | "no_registry_match"
                | "catalog_lacks_canonical_annotation"
                | "no_match"
                | "custom_converter_failed"
                | "invalid_format_id_parameters"
                | "catalog_requirement_conflict";
            converter_error?: string;
        };
    }

• ProjectionDiagnosticBase & {
      code: "FORMAT_DECLARATION_V1_AMBIGUOUS";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              registry_matches: number;
          };
      };
  }

  • code: "FORMAT_DECLARATION_V1_AMBIGUOUS"

    Spec code (enums/error-code.json): registry has family-level structural entries for this canonical (e.g., the VAST entries for video_vast), but none are invertible to a specific v1 named format. Family is known, specific format isn't pickable. Correctable by the seller adding v1_format_ref to the declaration.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            registry_matches: number;
        };
    }

• ProjectionDiagnosticBase & {
      code: "FORMAT_DECLARATION_V1_NOT_APPLICABLE";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              reason: "canonical_formats_only";
          };
      };
  }

  • code: "FORMAT_DECLARATION_V1_NOT_APPLICABLE"

    SDK-local code: declaration has canonical_formats_only: true. Seller explicitly opted out of v1 emission. Not a registry- coverage gap; not ambiguous. Informational so buyers can see why a product disappeared from a v1-only catalog.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            reason: "canonical_formats_only";
        };
    }

• ProjectionDiagnosticBase & {
      code: "CANONICAL_NOT_V1_TRANSLATABLE";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
          };
      };
  }

  • code: "CANONICAL_NOT_V1_TRANSLATABLE"

    SDK-local code: canonical declares v1_translatable: false. Structural v1-unreachability — no v1 form is possible for this canonical regardless of registry coverage. The 4 inherently-v2 canonicals at 3.1 GA: image_carousel, sponsored_placement, responsive_creative, agent_placement. Spec is explicit: SDKs MUST NOT emit FORMAT_PROJECTION_FAILED for these (they're not coverage gaps).

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
        };
    }

• ProjectionDiagnosticBase & {
      code: "FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE";
      error: {
          details: {
              format_kind: CanonicalFormatKind;
              product_id: string;
              format_option_id?: string;
              size_mode: "sizes" | "responsive_range";
              declared_sizes_count?: number;
              emitted_sizes_count?: number;
              v1_emit_represents_size?: { width?: number; height?: number };
          };
      };
  }

  • code: "FORMAT_DECLARATION_V1_LOSSY_MULTI_SIZE"

    SDK-local code: v2 declaration uses multi-size (sizes: [...]) or responsive (min_width/max_width/min_height/max_height) params, but v1_format_ref is a single catalog entry that can only carry ONE fixed (width, height). The v1 wire emit represents only the seller-chosen representative size; the remaining sizes are silently dropped on the v1 wire.

    This diagnostic is emitted alongside the v1 format_id — not instead of it — so the v1 buyer still sees the product but the buyer code is told what coverage was lost. Different from FORMAT_DECLARATION_V1_AMBIGUOUS (no v1 emit) and FORMAT_DECLARATION_V1_NOT_APPLICABLE (seller opt-out).

    Surface follow-up: an SDK MAY (non-normative) expand multi- size to N v1 format_ids by looking up the catalog for each size. Today's prototype emits only the seller-asserted representative; multi-emit is a follow-up.

  • error: {
        details: {
            format_kind: CanonicalFormatKind;
            product_id: string;
            format_option_id?: string;
            size_mode: "sizes" | "responsive_range";
            declared_sizes_count?: number;
            emitted_sizes_count?: number;
            v1_emit_represents_size?: { width?: number; height?: number };
        };
    }

    • details: {
          format_kind: CanonicalFormatKind;
          product_id: string;
          format_option_id?: string;
          size_mode: "sizes" | "responsive_range";
          declared_sizes_count?: number;
          emitted_sizes_count?: number;
          v1_emit_represents_size?: { width?: number; height?: number };
      }

      • format_kind: CanonicalFormatKind

      • product_id: string

      • Optionalformat_option_id?: string

      • size_mode: "sizes" | "responsive_range"

      • Optionaldeclared_sizes_count?: number

      • Optionalemitted_sizes_count?: number

        How many v1 format_ids the SDK actually emitted. < declared_sizes_count when the catalog doesn't cover every declared size; equal when the catalog has full coverage. The fan-out is non-normative — when this equals 1, only the seller-asserted rep was emitted; v1 buyers lose the rest.

      • Optionalv1_emit_represents_size?: { width?: number; height?: number }

• ProjectionDiagnosticBase & {
      code: "LEGACY_FORMAT_ID_DROPPED_UNMAPPED";
      error: {
          details: {
              product_id: string;
              resolution_failure: "unmapped_legacy_format";
          };
      };
  }

  • code: "LEGACY_FORMAT_ID_DROPPED_UNMAPPED"

    SDK-local code: canonical-only projection (toCanonicalOnlyProduct / toCanonicalOnlyResponse) found legacy routing metadata that no canonical format option covers. Emitted only on the v2-native pass-through path — a seller that sent format_options[] directly but also carried a format_ids[] entry with no canonical representation. Without it, canonical-only mode would silently discard a format the buyer could still have acted on via the v1 path.

    On the v1 → v2 projection path an unmappable ref is already surfaced as FORMAT_PROJECTION_FAILED; this code covers the gap the projection path can't see (no projection runs when the seller is already v2-native).

  • error: {
        details: {
            product_id: string;
            resolution_failure: "unmapped_legacy_format";
        };
    }

    • details: { product_id: string; resolution_failure: "unmapped_legacy_format" }

      • product_id: string

      • resolution_failure: "unmapped_legacy_format"

        Stable category only; canonical diagnostics never echo routing identifiers.