adformat

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: Apache-2.0 Imports: 16 Imported by: 0

Documentation

Index

Constants

View Source
const (
	AssetNameBanner = "banner"
	AssetNameMain   = "main"
	AssetNameIcon   = "icon"
)

Well-known asset names, kept for parity with the old model (admodels/types.FormatAsset* constants).

View Source
const (
	NavigateBack  = "$back"
	NavigateClose = "$close"
)

Reserved NavigateTo commands (§3.2.11) — not screen names.

View Source
const (
	FieldNameTitle       = "title"
	FieldNameDescription = "description"
	FieldNameBrandname   = "brandname"
	FieldNamePhone       = "phone"
	FieldNameURL         = "url"
	FieldNameContent     = "content"
	FieldNameRating      = "rating"
	FieldNameLikes       = "likes"
	FieldNameAddress     = "address"
	FieldNameSponsored   = "sponsored"
)

Well-known field names, kept for parity with the old model (admodels/types.FormatField* constants).

View Source
const Unlimited = -1

Unlimited is the sentinel MaxCount/GetMaxCount value meaning "no upper bound on the number of instances".

Variables

View Source
var (
	ErrFieldIsRequired  = errors.New("adformat: field is required")
	ErrFieldInvalidType = errors.New("adformat: field value has invalid type")
)

Errors returned by Field.Prepare.

Functions

func DecodeBindingParams

func DecodeBindingParams[P any](bindings []Binding, target string) (P, bool)

DecodeBindingParams finds the first binding in bindings matching target and decodes its Params into a value of type P via an encoding/json round-trip. It is the shared implementation behind every adapter package's own typed Get*/GetImage/GetData/... helpers (see adformat/openrtbnative, adformat/openrtbvideo, adformat/tracking, adformat/vasttracking), so none of them need to touch map[string]any by hand. Returns false when no binding for target is present or decoding fails.

func ParseAspectRatio

func ParseAspectRatio(s string) (w, h float64, err error)

ParseAspectRatio parses a "W:H" proportion string (e.g. "1.91:1", "16:9") into its numeric components. Both parts must be positive numbers.

Types

type Accessor

type Accessor interface {
	// Formats list collection.
	Formats() []*Format

	// FormatsBySize returns the list of formats whose Sizes accept
	// width/height (§3.2.13); direct formats are always included, same
	// convention as the old model.
	FormatsBySize(width, height int) []*Format

	// FormatByID of the model.
	FormatByID(id uint64) *Format

	// FormatByCode of the model.
	FormatByCode(code string) *Format

	// DirectFormatSet to search.
	DirectFormatSet() *searchtypes.NumberBitset[uint]
}

Accessor object interface (was admodels/types.FormatsAccessor).

type AltTextRequirement

type AltTextRequirement struct {
	Required  bool `json:"required,omitempty" yaml:"required,omitempty"`
	MaxLength int  `json:"max_length,omitempty" yaml:"max_length,omitempty"`
}

AltTextRequirement declares whether this asset role must be accompanied by an accessibility description supplied together with the file, and how long that description may be (§3.2.1 gap #3, increasingly required by exchanges). Just like FocalPoint's default anchor, this only describes the *requirement*; the actual text for one uploaded file is data of that creative instance, not part of the format schema.

type AssetRequirement

type AssetRequirement struct {
	// Required marks the asset as mandatory when it is active (see
	// Condition below).
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`

	// Name of the asset (optional for the first/only asset, defaults to
	// "main").
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Resizable: the platform may scale this file to fit the target size
	// (was "adjust_size" — renamed for clarity, §3.2.1).
	Resizable bool `json:"resizable,omitempty" yaml:"resizable,omitempty"`

	// Width/Height: a "preferred" exact size for preview/fit purposes —
	// does not participate in range validation, that is always the
	// explicit Min/Max* pair below (§3.2.1). Left unset when only a
	// range is meaningful.
	Width  int `json:"width,omitempty" yaml:"width,omitempty"`
	Height int `json:"height,omitempty" yaml:"height,omitempty"`

	// MinWidth/MaxWidth, MinHeight/MaxHeight: explicit allowed size
	// range in pixels for image/video content (renamed from the
	// old ambiguous width/min_width pair, §3.2.1).
	MinWidth  int `json:"min_width,omitempty" yaml:"min_width,omitempty"`
	MaxWidth  int `json:"max_width,omitempty" yaml:"max_width,omitempty"`
	MinHeight int `json:"min_height,omitempty" yaml:"min_height,omitempty"`
	MaxHeight int `json:"max_height,omitempty" yaml:"max_height,omitempty"`

	// AspectRatio is a direct "W:H" proportion (e.g. "1.91:1", "16:9")
	// offered as a more readable alternative/addition to a Min/MaxWidth
	// + Min/MaxHeight range, matching how many real-world exchange specs
	// (Facebook/Google-style) describe size constraints (§3.2.1 gap #1).
	// When set together with a width/height range, both must be
	// satisfied. See AspectRatioValue/MatchesAspectRatio.
	AspectRatio string `json:"aspect_ratio,omitempty" yaml:"aspect_ratio,omitempty"`

	// AllowAnimated/AllowSound: permissions for the asset content (was
	// "animated"/"sound" — renamed since these describe a requirement,
	// not a fact about a specific uploaded file, §3.2.1).
	AllowAnimated bool `json:"allow_animated,omitempty" yaml:"allow_animated,omitempty"`
	AllowSound    bool `json:"allow_sound,omitempty" yaml:"allow_sound,omitempty"`

	// DurationMin/DurationMax: allowed video/audio duration range in
	// seconds. Zero means "no constraint" on that bound.
	DurationMin float64 `json:"duration_min,omitempty" yaml:"duration_min,omitempty"`
	DurationMax float64 `json:"duration_max,omitempty" yaml:"duration_max,omitempty"`

	// BitrateMin/BitrateMax: allowed video/audio bitrate range in kbps
	// (0 = no constraint on that bound). Closes the §3.2.1 gap #4 found
	// in stricter TV/VAST specs, which the old duration-only model could
	// not express.
	BitrateMin int `json:"bitrate_min,omitempty" yaml:"bitrate_min,omitempty"`
	BitrateMax int `json:"bitrate_max,omitempty" yaml:"bitrate_max,omitempty"`

	// AllowedCodecs restricts video/audio encoding (e.g. "h264", "vp9",
	// "av1", "aac") — empty means "any codec is allowed" (§3.2.1 gap #4).
	AllowedCodecs []string `json:"allowed_codecs,omitempty" yaml:"allowed_codecs,omitempty"`

	// AllowedFramerates restricts video frame rate to one of the given
	// values in fps — empty means "any frame rate is allowed" (§3.2.1
	// gap #4; several TV/VAST specs only accept exact rates like
	// 25/29.97/30 rather than a free-form range).
	AllowedFramerates []float64 `json:"allowed_framerates,omitempty" yaml:"allowed_framerates,omitempty"`

	// MaxFileSize: maximum allowed file weight in bytes (0 = no limit) —
	// closes a real gap found while researching playable/rich-media
	// specs (§3.2.2), which almost universally cap file size.
	MaxFileSize int64 `json:"max_file_size,omitempty" yaml:"max_file_size,omitempty"`

	// FocalPoint: optional focus-point metadata (§3.2.1).
	FocalPoint *FocalPoint `json:"focal_point,omitempty" yaml:"focal_point,omitempty"`

	// SafeZone: optional edge-inset metadata, symmetric to FocalPoint
	// (§3.2.1 gap #2).
	SafeZone *SafeZone `json:"safe_zone,omitempty" yaml:"safe_zone,omitempty"`

	// AltText: optional accessibility-text requirement (§3.2.1 gap #3).
	AltText *AltTextRequirement `json:"alt_text,omitempty" yaml:"alt_text,omitempty"`

	// Thumbs: structured autogenerated thumbnail sizes (§3.2.1).
	Thumbs []Thumb `json:"thumbs,omitempty" yaml:"thumbs,omitempty"`

	// AllowedTypes of files for this particular asset — either a short
	// category (image/video/html5/sound) or an exact MIME type
	// (image/jpeg) — both forms are intentionally supported.
	AllowedTypes []string `json:"allowed_types,omitempty" yaml:"allowed_types,omitempty"`

	// MinCount/MaxCount: how many instances of this asset one ad
	// creative carries (§3.2, п.2). See
	// GetMinCount/GetMaxCount/IsMultiple/RangeCount. MaxCount == -1
	// means unlimited. Only legitimate when every instance is
	// guaranteed to be part of one advertiser's single submission —
	// see §3.0.
	MinCount int `json:"min_count,omitempty" yaml:"min_count,omitempty"`
	MaxCount int `json:"max_count,omitempty" yaml:"max_count,omitempty"`

	// Condition controls when this asset is active (§3.2.5).
	Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`

	// NavigateTo names the screen this asset (e.g. a tappable hotspot
	// image) switches the creative to when activated (§3.2.11).
	// "$back"/"$close" are reserved commands, not screen names.
	NavigateTo string `json:"navigate_to,omitempty" yaml:"navigate_to,omitempty"`

	// Bindings associate this asset with external protocol
	// representations (OpenRTB Native image/video asset, ...) —
	// §3.2.12. Replaces the old, always-empty FormatFileRequirement.ID.
	Bindings []Binding `json:"bindings,omitempty" yaml:"bindings,omitempty"`
}

AssetRequirement describes a requirement for one media file within an ad creative (was admodels/types.FormatFileRequirement).

func Asset

func Asset(name string) AssetRequirement

Asset starts a new AssetRequirement builder chain with the given name.

func (AssetRequirement) Animated

func (a AssetRequirement) Animated() AssetRequirement

Animated allows animated content for this asset.

func (AssetRequirement) AspectRatioValue

func (a AssetRequirement) AspectRatioValue() (w, h float64, ok bool)

AspectRatioValue parses AssetRequirement.AspectRatio, reporting ok=false when it is empty or malformed.

func (AssetRequirement) Bind

Bind attaches an external-protocol association to this asset (§3.2.12).

func (AssetRequirement) Bitrate

func (a AssetRequirement) Bitrate(min, max int) AssetRequirement

Bitrate sets the allowed video/audio bitrate range in kbps (§3.2.1 gap #4).

func (AssetRequirement) Codecs

func (a AssetRequirement) Codecs(codecs ...string) AssetRequirement

Codecs restricts the allowed video/audio codecs (§3.2.1 gap #4).

func (AssetRequirement) Count

func (a AssetRequirement) Count(min, max int) AssetRequirement

Count sets the MinCount/MaxCount instance-count bounds (§3.2, п.2).

func (AssetRequirement) Duration

func (a AssetRequirement) Duration(min, max float64) AssetRequirement

Duration sets the allowed video/audio duration range in seconds.

func (AssetRequirement) ExactSize

func (a AssetRequirement) ExactSize(width, height int) AssetRequirement

ExactSize sets a single preferred exact size (Width/Height only, no range) — the common case for a classic fixed-size asset.

func (AssetRequirement) Focal

Focal enables a focal point on this asset with the given default anchor (§3.2.1).

func (AssetRequirement) Framerates

func (a AssetRequirement) Framerates(fps ...float64) AssetRequirement

Framerates restricts the allowed video frame rates in fps (§3.2.1 gap #4).

func (AssetRequirement) GetMaxCount

func (a AssetRequirement) GetMaxCount() int

GetMaxCount effective maximal number of instances (-1 = unlimited).

func (AssetRequirement) GetMinCount

func (a AssetRequirement) GetMinCount() int

GetMinCount effective minimal number of instances of this asset within one ad creative (§3.2, п.2).

func (AssetRequirement) GetName

func (a AssetRequirement) GetName() string

GetName of the asset, defaulting to "main".

func (AssetRequirement) IsFixedSize

func (a AssetRequirement) IsFixedSize() bool

IsFixedSize reports whether this asset requires an exact size (no range).

func (AssetRequirement) IsHTML5Support

func (a AssetRequirement) IsHTML5Support() bool

IsHTML5Support of the file.

func (AssetRequirement) IsImageSupport

func (a AssetRequirement) IsImageSupport() bool

IsImageSupport of the file.

func (AssetRequirement) IsMain

func (a AssetRequirement) IsMain() bool

IsMain asset (the default asset of a Config when no explicit name is given elsewhere).

func (AssetRequirement) IsMimeTypeSupport

func (a AssetRequirement) IsMimeTypeSupport(mimePrefix string) bool

IsMimeTypeSupport of the file — allowed_types is either a short category ("image") or an exact MIME type ("image/jpeg"); an empty list means "any type is allowed" (§3.2.1).

func (AssetRequirement) IsMultiple

func (a AssetRequirement) IsMultiple() bool

IsMultiple reports whether this asset may have more than one instance.

func (AssetRequirement) IsRequired

func (a AssetRequirement) IsRequired() bool

IsRequired asset — unlike the old model, this is a pure getter derived from Required || MinCount>0 (no more mutating IsMain() side effect on first call, see the bug noted in §2).

func (AssetRequirement) IsSoundSupport

func (a AssetRequirement) IsSoundSupport() bool

IsSoundSupport of the file.

func (AssetRequirement) IsVideoSupport

func (a AssetRequirement) IsVideoSupport() bool

IsVideoSupport of the file.

func (AssetRequirement) MatchesAspectRatio

func (a AssetRequirement) MatchesAspectRatio(width, height int) bool

MatchesAspectRatio reports whether the given pixel dimensions satisfy AspectRatio within a small relative tolerance (to tolerate integer rounding of real image dimensions). Always true when AspectRatio is not set.

func (AssetRequirement) MaxSize

func (a AssetRequirement) MaxSize(bytes int64) AssetRequirement

MaxSize sets the maximum allowed file weight in bytes (§3.2.2).

func (AssetRequirement) MinMaxHeight

func (a AssetRequirement) MinMaxHeight() (mn, mx int)

MinMaxHeight sizes, symmetric to MinMaxWidth.

func (AssetRequirement) MinMaxWidth

func (a AssetRequirement) MinMaxWidth() (mn, mx int)

MinMaxWidth sizes, mirroring the semantics of the old model's method of the same name (a bare Width with no MinWidth means an exact size).

func (AssetRequirement) RangeCount

func (a AssetRequirement) RangeCount() (min, max int)

RangeCount returns the effective (min, max) instance-count range.

func (AssetRequirement) Require

func (a AssetRequirement) Require() AssetRequirement

Require marks the asset as mandatory.

func (AssetRequirement) RequireAltText

func (a AssetRequirement) RequireAltText(maxLength int) AssetRequirement

RequireAltText marks this asset as needing an accessibility text description of at most maxLength characters (0 = unbounded), §3.2.1 gap #3.

func (AssetRequirement) Size

func (a AssetRequirement) Size(minW, maxW, minH, maxH int) AssetRequirement

Size sets the allowed width/height range of the asset file.

func (AssetRequirement) SoftEqual

func (a AssetRequirement) SoftEqual(asset AssetRequirement) bool

SoftEqual compares two asset requirements for compatibility purposes (used by Config.Intersec), same relaxed matching rules as the old model plus a symmetric comparison of the effective instance-count ranges via compareAspect.

func (AssetRequirement) Sound

Sound allows sound for this asset.

func (AssetRequirement) SupportsCodec

func (a AssetRequirement) SupportsCodec(codec string) bool

SupportsCodec reports whether codec is allowed by AllowedCodecs (empty list means any codec is allowed).

func (AssetRequirement) SupportsFramerate

func (a AssetRequirement) SupportsFramerate(fps float64) bool

SupportsFramerate reports whether fps is allowed by AllowedFramerates (empty list means any frame rate is allowed).

func (AssetRequirement) Types

func (a AssetRequirement) Types(types ...string) AssetRequirement

Types sets the allowed asset content types (short category or exact MIME type, §3.2.1).

func (AssetRequirement) When

When attaches a Condition controlling this asset's activity (§3.2.5).

func (AssetRequirement) WithAspectRatio

func (a AssetRequirement) WithAspectRatio(ratio string) AssetRequirement

WithAspectRatio sets a direct "W:H" proportion constraint, e.g. "1.91:1" (§3.2.1 gap #1). Named WithAspectRatio, not AspectRatio, because the latter would collide with the struct field of the same name (see the package-level deviation note above).

func (AssetRequirement) WithNavigateTo

func (a AssetRequirement) WithNavigateTo(screen string) AssetRequirement

WithNavigateTo marks activating this asset (e.g. a tappable hotspot image) as a fixed transition to the named sibling screen — or to the reserved "$back"/"$close" commands (§3.2.11). Named WithNavigateTo, not NavigateTo, because the latter would collide with the struct field of the same name (see the package-level deviation note above).

func (AssetRequirement) WithSafeZone

func (a AssetRequirement) WithSafeZone(top, right, bottom, left float64) AssetRequirement

WithSafeZone sets the edge-inset metadata, symmetric to Focal (§3.2.1 gap #2). Insets are fractions (0..1) of the asset's own width/height.

type Binding

type Binding struct {
	Target string         `json:"target" yaml:"target"`                     // "openrtb_native", "vast", "mraid", or a partner-specific name
	Params map[string]any `json:"params,omitempty" yaml:"params,omitempty"` // shape defined by the adapter package for Target
}

Binding associates a Node (asset/field) or a whole Format with a concrete element of some external target representation — a bidding protocol's markup (OpenRTB Native asset, OpenRTB Video/VAST object, MRAID feature, a specific partner's proprietary JSON), by an opaque target-defined key. adformat itself has zero knowledge of what "openrtb_native" or "vast" mean — that semantics lives entirely in a small adapter package per target (see adformat/openrtbnative, adformat/openrtbvideo, adformat/tracking, adformat/vasttracking). One asset/field can carry several Bindings for several targets at once — e.g. the same "main" image asset is simultaneously the OpenRTB Native "main image" AND, for a partner that doesn't speak OpenRTB, a specific field path in their proprietary JSON.

func FindBinding

func FindBinding(bindings []Binding, target string) (Binding, bool)

FindBinding returns the first binding in bindings matching target.

func NewBinding

func NewBinding(target string, params any) Binding

NewBinding builds a Binding for target from an arbitrary params value by round-tripping it through encoding/json into map[string]any — used by adapter packages' constructors (ImageAsset, TitleField, Video, Tracker, ...).

type Condition

type Condition struct {
	// Leaf predicate: name of the controlling field/asset + one of
	// In/NotIn/Present. Ignored when All/Any/Not below are non-empty.
	Field   string `json:"field,omitempty" yaml:"field,omitempty"`
	In      []any  `json:"in,omitempty" yaml:"in,omitempty"`
	NotIn   []any  `json:"not_in,omitempty" yaml:"not_in,omitempty"`
	Present *bool  `json:"present,omitempty" yaml:"present,omitempty"`

	// Composition: combine leaf/nested conditions with boolean logic. The
	// plain leaf form above still works unchanged for the common
	// single-field case.
	All []Condition `json:"all,omitempty" yaml:"all,omitempty"`
	Any []Condition `json:"any,omitempty" yaml:"any,omitempty"`
	Not *Condition  `json:"not,omitempty" yaml:"not,omitempty"`
}

Condition describes when a Field, AssetRequirement or nested Config (group/param) is active (shown + eligible to be required), based on the current value of another field/asset in the same Config. Absent Condition = always active. Zero value is a valid empty leaf (matches nothing in particular — always true) so Condition can be composed by value, not just by pointer.

It replaces the old, never-implemented FormatField.Exclude: instead of declaring "if I am filled — hide them" from the controlling field's side, the dependent field declares "I am active when it equals X" from its own side — easier to read top-to-bottom when generating a form (the field's own description already tells you when it appears).

func And

func And(conds ...Condition) Condition

And combines conditions with boolean AND.

func FieldAbsent

func FieldAbsent(field string) Condition

FieldAbsent builds a Condition that is true when the named field has no value (or an empty one).

func FieldIn

func FieldIn(field string, values ...any) Condition

FieldIn builds a Condition that is true when the named field's value is (or, for a repeatable field, includes) one of values.

func FieldNotIn

func FieldNotIn(field string, values ...any) Condition

FieldNotIn builds a Condition that is true when the named field's value is not (or, for a repeatable field, does not include) any of values.

func FieldPresent

func FieldPresent(field string) Condition

FieldPresent builds a Condition that is true when the named field has a non-empty value.

func Not

func Not(c Condition) Condition

Not negates c.

func Or

func Or(conds ...Condition) Condition

Or combines conditions with boolean OR.

func (Condition) Eval

func (c Condition) Eval(values map[string]any) bool

Eval evaluates the condition tree against the current set of field/asset values (keyed by name, same map shape as used for Config.ActiveFields/ActiveAssets). It is a pure function without side effects — the schema (Condition) and the engine (Eval) stay separate, same principle as Field.Prepare.

If the referenced value is a slice (i.e. the field it points to is a repeatable/multi-select Field or AssetRequirement, see MinCount/MaxCount and IsMultiple), In/NotIn match element-wise ("at least one of the selected elements intersects with the given set", like an element-wise SQL IN rather than a whole-slice comparison) and Present means "the slice is non-empty".

func (Condition) IsZero

func (c Condition) IsZero() bool

IsZero reports whether c carries no predicate at all (always true).

type Config

type Config struct {
	// Name of this group (empty for the root Config).
	Name string `json:"name,omitempty" yaml:"name,omitempty"`

	// Title of this group for the UI.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`

	// MinCount/MaxCount: how many instances of this group one ad
	// creative carries (§3.4/§3.5) — same effective semantics as
	// AssetRequirement/Field (see GetMinCount/GetMaxCount/RangeCount).
	// Only legitimate when every instance is guaranteed to be part of
	// one advertiser's single submission — see §3.0.
	MinCount int `json:"min_count,omitempty" yaml:"min_count,omitempty"`
	MaxCount int `json:"max_count,omitempty" yaml:"max_count,omitempty"`

	// Entry marks this group as the starting screen of a multi-screen
	// creative (§3.2.11). If no nested group is marked Entry, the first
	// one in Children is assumed to be the start screen.
	Entry bool `json:"entry,omitempty" yaml:"entry,omitempty"`

	// Condition controls when this group is active (§3.2.5) — e.g. a
	// nested "panel" that only applies for a certain layout choice.
	Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`

	// Children holds assets, fields, groups and params together, in
	// authoring order.
	Children []Node `json:"children,omitempty" yaml:"children,omitempty"`
}

Config is the recursive structure describing an ad format's creative (was admodels/types.FormatConfig). It is built on top of a single Children []Node list (assets + fields + groups + params, in the order the author declared them) instead of three parallel typed slices — see node.go and §3.2.7 for the rationale. There is no separate "Group" type: a nested group is simply another Config referenced by a Node of Kind NodeGroup.

Name/MinCount/MaxCount/Condition/Entry are meaningless on the root Config hanging off Format.Config — they only matter for a Config used as a nested group/screen (a Node's Group field).

func Group

func Group(name string) Config

Group starts a new nested Config ("screen"/group) builder chain with the given name.

func (Config) ActiveAssets

func (c Config) ActiveAssets(values map[string]any) []AssetRequirement

ActiveAssets returns the top-level assets whose Condition (if any) evaluates to true against values (§3.2.5).

func (Config) ActiveFields

func (c Config) ActiveFields(values map[string]any) []Field

ActiveFields returns the top-level fields whose Condition (if any) evaluates to true against values (§3.2.5).

func (Config) ActiveGroups

func (c Config) ActiveGroups(values map[string]any) []Config

ActiveGroups returns the top-level nested groups whose Condition (if any) evaluates to true against values.

func (Config) ActiveParams

func (c Config) ActiveParams(values map[string]any) []Param

ActiveParams returns the top-level params whose Condition (if any) evaluates to true against values.

func (Config) AsEntry

func (c Config) AsEntry() Config

AsEntry marks this group as the starting screen of a multi-screen creative (§3.2.11).

func (Config) AssetByName

func (c Config) AssetByName(name string) *AssetRequirement

AssetByName from config; an empty name matches the main asset.

func (Config) Assets

func (c Config) Assets() []AssetRequirement

Assets returns the top-level asset requirements of this Config (does not recurse into nested groups).

func (Config) ContainsAsset

func (c Config) ContainsAsset(asset AssetRequirement, revers ...bool) bool

ContainsAsset in the list of top-level assets.

func (Config) Count

func (c Config) Count(min, max int) Config

Count sets the MinCount/MaxCount instance-count bounds of this group (§3.4/§3.5).

func (Config) EntryGroup

func (c Config) EntryGroup() (Config, bool)

EntryGroup returns the nested group explicitly marked Entry, or, failing that, the first nested group in Children — the default "convention over configuration" start-screen rule from §3.2.11. The second return value is false only when there are no nested groups at all.

func (Config) Fields

func (c Config) Fields() []Field

Fields returns the top-level fields of this Config (does not recurse into nested groups).

func (Config) GetField

func (c Config) GetField(name string) *Field

GetField by name.

func (Config) GetMaxCount

func (c Config) GetMaxCount() int

GetMaxCount effective maximal number of instances (-1 = unlimited).

func (Config) GetMinCount

func (c Config) GetMinCount() int

GetMinCount effective minimal number of instances of this group.

func (Config) GetParam

func (c Config) GetParam(name string) (Param, bool)

GetParam by name (§3.2.14).

func (Config) Groups

func (c Config) Groups() []Config

Groups returns the top-level nested groups of this Config.

func (Config) Intersec

func (c Config) Intersec(other Config) bool

Intersec reports whether c and other are compatible: every required top-level asset/field of one config is satisfiable by the other. Only considers top-level assets/fields, same as the old flat model — nested groups are a new structural feature and are not part of this comparison.

func (Config) IsEmpty

func (c Config) IsEmpty() bool

IsEmpty config.

func (Config) IsMultiple

func (c Config) IsMultiple() bool

IsMultiple reports whether this group may have more than one instance.

func (Config) MainAsset

func (c Config) MainAsset() *AssetRequirement

MainAsset returns the main asset if it exists.

func (Config) Params

func (c Config) Params() []Param

Params returns the top-level params of this Config.

func (Config) RangeCount

func (c Config) RangeCount() (min, max int)

RangeCount returns the effective (min, max) instance-count range.

func (Config) RequiredField

func (c Config) RequiredField(fields ...string) *Field

RequiredField returns a required field, optionally restricted to one of the given names — same lookup semantics as the old model.

func (Config) RequiredFieldExcept

func (c Config) RequiredFieldExcept(fields ...string) *Field

RequiredFieldExcept returns any required field not present in the given exception list.

func (Config) SimilarField

func (c Config) SimilarField(field Field, revers ...bool) *Field

SimilarField in the list of top-level fields.

func (Config) SimpleAsset

func (c Config) SimpleAsset() *AssetRequirement

SimpleAsset returns the main asset in case it is the only required asset in the config.

func (Config) Validate

func (c Config) Validate() error

Validate walks the whole Config tree once and checks everything that could otherwise fail silently at first use (§3.2.6):

  1. Every Field.RegExp compiles.
  2. Every Condition.Field (on a Field/AssetRequirement/nested Config/ Param) references an existing sibling name at the same tree level.
  3. No cycles in Condition dependencies at a given level.
  4. Every NavigateTo (other than the reserved "$back"/"$close") and every screen_ref Field.Options value references an existing screen (named nested group) — the set of screen names is the nearest enclosing level of group siblings: a field/asset nested directly inside one named screen (e.g. "intro") targets the screen's own siblings ("offer", ...), not something inside "intro" itself — see the worked example in multiscreen.yaml (§3.2.11).
  5. Every AssetRequirement.AspectRatio parses as "W:H", and BitrateMin does not exceed BitrateMax when both are set (§3.2.1 gaps #1/#4).

Call this once when a Format/Config is loaded (codec.go does this automatically for LoadYAML/LoadJSON), not on every use.

func (Config) Walk

func (c Config) Walk(fn func(path string, n Node) error) error

Walk calls fn for every Node in the tree rooted at c, passing a stable dotted path (e.g. "panel.headline", "offer.hotspot.target_screen") usable for error messages and for addressing a specific node from a UI editor. Recurses into nested groups depth-first, in Children order.

func (Config) When

func (c Config) When(cond Condition) Config

When attaches a Condition controlling this group's activity (§3.2.5).

func (Config) WithAssets

func (c Config) WithAssets(assets ...AssetRequirement) Config

WithAssets appends the given asset requirements to Children, wrapping each into a Node — the NodeKind discriminator never surfaces to the caller.

func (Config) WithFields

func (c Config) WithFields(fields ...Field) Config

WithFields appends the given fields to Children, wrapping each into a Node.

func (Config) WithGroups

func (c Config) WithGroups(groups ...Config) Config

WithGroups appends the given nested Config groups to Children, wrapping each into a Node.

func (Config) WithParams

func (c Config) WithParams(params ...Param) Config

WithParams appends the given params to Children, wrapping each into a Node (§3.2.14).

func (Config) WithTitle

func (c Config) WithTitle(t string) Config

WithTitle sets the UI title of the group.

type Field

type Field struct {
	// Required marks the field as mandatory when it is active (see
	// Condition below) — a Condition never overrides Required, it only
	// controls whether the field participates at all.
	Required bool `json:"required,omitempty" yaml:"required,omitempty"`

	// Title of the field for the UI.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`

	// Description is helper text shown under the title in the edit UI.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`

	// Name of the field (required, used for addressing/Condition/Binding).
	Name string `json:"name" yaml:"name"`

	// Type of the field data.
	Type FieldType `json:"type,omitempty" yaml:"type,omitempty"`

	// Options is the list of selectable values, used both for a
	// single-select field and, combined with MaxCount > 1, for a
	// multi-select field (§3.2.3/§3.2.15). Empty = free-form input.
	Options []Option `json:"options,omitempty" yaml:"options,omitempty"`

	// Min/Max: length bounds for string-like types, value bounds for
	// int/float types.
	Min float64 `json:"min,omitempty" yaml:"min,omitempty"`
	Max float64 `json:"max,omitempty" yaml:"max,omitempty"`

	// MinCount/MaxCount: how many instances of this field one ad creative
	// carries — repeatable text variants (e.g. Google Responsive Ads
	// style headlines) or a multi-select out of Options (§3.2.15). See
	// GetMinCount/GetMaxCount/IsMultiple/RangeCount for the effective
	// semantics. MaxCount == -1 means unlimited.
	MinCount int `json:"min_count,omitempty" yaml:"min_count,omitempty"`
	MaxCount int `json:"max_count,omitempty" yaml:"max_count,omitempty"`

	// Mask is a pure UI hint for rendering a masked input (e.g.
	// "+1 (999) 999-9999") — it is never used for server-side validation,
	// unlike RegExp below.
	Mask string `json:"mask,omitempty" yaml:"mask,omitempty"`

	// RegExp is an additional/overriding validation pattern (e.g. a
	// stricter phone format for a specific exchange). Unlike the old
	// model, this is actually applied by Prepare (§3.2.4).
	RegExp string `json:"regexp,omitempty" yaml:"regexp,omitempty"`

	// Condition controls when this field is active (shown + eligible to
	// be required) — replaces the dead FormatField.Exclude (§3.2.5).
	Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`

	// NavigateTo names the screen (sibling Config/group) this field
	// switches the creative to when activated (e.g. a button) — for
	// structural multi-screen creatives (§3.2.11). "$back"/"$close" are
	// reserved commands, not screen names.
	NavigateTo string `json:"navigate_to,omitempty" yaml:"navigate_to,omitempty"`

	// Bindings associate this field with external protocol
	// representations (OpenRTB Native data/title asset, tracking pixel
	// event, ...) — §3.2.12.
	Bindings []Binding `json:"bindings,omitempty" yaml:"bindings,omitempty"`

	// Multiline is the minimum textarea row count; 0 means a single-line input.
	Multiline int `json:"multiline,omitempty" yaml:"multiline,omitempty"`

	// Editable controls whether the field is shown in the general edit UI.
	// Omitted (Valid=false) or true = shown; false = hidden.
	Editable null.Bool `json:"editable,omitzero" yaml:"editable,omitempty"`

	// Multilang marks the field as supporting multiple languages when editing.
	Multilang bool `json:"multilang,omitempty" yaml:"multilang,omitempty"`
}

Field describes a requirement for a text/numeric/boolean value that is part of one ad creative (was admodels/types.FormatField).

func BoolField

func BoolField(name string) Field

BoolField starts a bool Field builder chain.

func EmailField

func EmailField(name string) Field

EmailField starts an email Field builder chain.

func FloatField

func FloatField(name string) Field

FloatField starts a float Field builder chain.

func GeoField

func GeoField(name string) Field

GeoField starts a geo Field builder chain.

func IntField

func IntField(name string) Field

IntField starts an int Field builder chain.

func PhoneField

func PhoneField(name string) Field

PhoneField starts a phone Field builder chain.

func ScreenRefField

func ScreenRefField(name string) Field

ScreenRefField starts a screen_ref Field builder chain — the advertiser picks the target screen from Options (§3.2.11).

func StringField

func StringField(name string) Field

StringField starts a string Field builder chain.

func URLField

func URLField(name string) Field

URLField starts a url Field builder chain.

func (Field) Bind

func (f Field) Bind(b Binding) Field

Bind attaches an external-protocol association to this field (§3.2.12).

func (Field) Count

func (f Field) Count(min, max int) Field

Count sets the MinCount/MaxCount instance-count bounds — repeatable text variants or a multi-select out of Options (§3.2.15).

func (Field) GetMaxCount

func (f Field) GetMaxCount() int

GetMaxCount effective maximal number of instances (-1 = unlimited).

func (Field) GetMinCount

func (f Field) GetMinCount() int

GetMinCount effective minimal number of instances of this field within one ad creative (§3.2.15).

func (Field) GetName

func (f Field) GetName() string

GetName of the field.

func (Field) GetType

func (f Field) GetType() FieldType

GetType of the field, defaulting to FieldDefaultType.

func (Field) HasOptions

func (f Field) HasOptions() bool

HasOptions reports whether the field restricts values to a fixed list.

func (Field) IsEditable

func (f Field) IsEditable() bool

IsEditable reports whether the field is shown in the general edit UI. Omitted JSON (Valid=false) defaults to true.

func (Field) IsMultilang

func (f Field) IsMultilang() bool

IsMultilang reports whether the field supports multiple languages when editing.

func (Field) IsMultiple

func (f Field) IsMultiple() bool

IsMultiple reports whether this field may have more than one instance (repeatable field or multi-select out of Options).

func (Field) IsRequired

func (f Field) IsRequired() bool

IsRequired field value. Bool fields are never "required" in the validation sense (false is a perfectly valid value), same as the old model.

func (Field) IsValidOption

func (f Field) IsValidOption(v any) bool

IsValidOption reports whether v equals one of Options[i].Value. Always true when the field has no Options (free-form input).

func (Field) Len

func (f Field) Len(min, max int) Field

Len sets the Min/Max length bounds for a string-like field.

func (Field) MaxLength

func (f Field) MaxLength() int

MaxLength of the field limit, for length-bounded types only.

func (Field) MultilineRows

func (f Field) MultilineRows() int

MultilineRows is the minimum textarea row count; 0 means a single-line input.

func (Field) Prepare

func (f Field) Prepare(value any) (result any, err error)

Prepare validates and normalizes a single input value according to the field's Type/Min/Max/RegExp/Options. Unlike the old FormatField.Prepare, the float upper bound is actually checked, boolean and phone values are no longer silently dropped, and "url" is a real type. For a repeatable/multi-select field (IsMultiple), call Prepare once per element and use RangeCount to validate the element count separately (Prepare itself only validates one value at a time).

func (Field) Range

func (f Field) Range(min, max float64) Field

Range sets the Min/Max value bounds for an int/float field.

func (Field) RangeCount

func (f Field) RangeCount() (min, max int)

RangeCount returns the effective (min, max) instance-count range.

func (Field) ReadOnly

func (f Field) ReadOnly() Field

ReadOnly hides the field from the general edit UI (editable: false).

func (Field) Require

func (f Field) Require() Field

Require marks the field as mandatory (when active, see When).

func (Field) SoftEqual

func (f Field) SoftEqual(field Field) bool

SoftEqual compares two fields for compatibility purposes (used by Config.Intersec), same relaxed semantics as the old model: same name and either both are string-typed or both share the exact same type.

func (Field) When

func (f Field) When(c Condition) Field

When attaches a Condition controlling this field's activity (§3.2.5).

func (Field) WithDescription

func (f Field) WithDescription(s string) Field

WithDescription sets helper text shown under the title in the edit UI.

func (Field) WithMask

func (f Field) WithMask(mask string) Field

WithMask sets the UI-only input mask hint.

func (Field) WithMultilang

func (f Field) WithMultilang() Field

WithMultilang marks the field as supporting multiple languages when editing.

func (Field) WithMultiline

func (f Field) WithMultiline(rows int) Field

WithMultiline sets the minimum textarea row count (0 = single-line input).

func (Field) WithNavigateTo

func (f Field) WithNavigateTo(screen string) Field

WithNavigateTo marks activating this field (e.g. a button) as a fixed transition to the named sibling screen — or to the reserved "$back"/"$close" commands (§3.2.11). Named WithNavigateTo, not NavigateTo, because the latter would collide with the struct field of the same name (see the package-level deviation note above).

func (Field) WithOptions

func (f Field) WithOptions(opts ...Option) Field

WithOptions sets the list of selectable values (§3.2.3).

func (Field) WithRegExp

func (f Field) WithRegExp(pattern string) Field

WithRegExp sets an additional/overriding validation pattern (§3.2.4).

func (Field) WithTitle

func (f Field) WithTitle(t string) Field

WithTitle sets the UI title of the field. Named WithTitle, not Title, because the latter would collide with the struct field of the same name (see the package-level deviation note above).

type FieldType

type FieldType string

FieldType is the data type of a Field value. It is a plain string, open for extension the same way Kind is.

const (
	FieldStringType    FieldType = "string"
	FieldIntType       FieldType = "int"
	FieldFloatType     FieldType = "float"
	FieldBoolType      FieldType = "bool"
	FieldPhoneType     FieldType = "phone"
	FieldEmailType     FieldType = "email"
	FieldURLType       FieldType = "url"
	FieldGeoType       FieldType = "geo"
	FieldScreenRefType FieldType = "screen_ref" // §3.2.11 — advertiser picks a target screen from Options
	FieldDefaultType             = FieldStringType
)

Field type values.

type FocalPoint

type FocalPoint struct {
	// Enabled: whether the advertiser/editor may pin a focal point for
	// this asset.
	Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"`

	// Default anchor used when the advertiser did not specify one.
	// [0,0] = top-left, [0.5,0.5] = center, [1,1] = bottom-right.
	Default [2]float64 `json:"default,omitempty" yaml:"default,omitempty"`
}

FocalPoint declares whether this asset role supports attaching an anchor point on the image/video content, and what to assume if the advertiser did not provide one. This is purely positioning metadata — the file itself is never modified or cropped by adformat or the ad server; the display client (widget/app) uses the anchor (typically via a CSS object-position-like mechanism) to keep the important area in frame when rendering the same file at a different aspect ratio (MGID-style native "focus point", §3.2.1). The actual anchor chosen for one particular uploaded file is data of that creative, not part of the format schema.

type Format

type Format struct {
	ID       uint64 `json:"id,omitempty" yaml:"id,omitempty"`
	Codename string `json:"codename,omitempty" yaml:"codename,omitempty"`
	Title    string `json:"title,omitempty" yaml:"title,omitempty"`

	// Kind is the primary media/content type; Tags is the open-ended
	// list of secondary classifiers (§3.2, п.1).
	Kind Kind     `json:"kind,omitempty" yaml:"kind,omitempty"`
	Tags []string `json:"tags,omitempty" yaml:"tags,omitempty"`

	// Orientations supported by this creative as a whole — empty means
	// "any" (§3.2.2).
	Orientations []Orientation `json:"orientations,omitempty" yaml:"orientations,omitempty"`

	// Version of the schema this Format was authored against — empty is
	// treated as "1" (§3.2.9). Purely informational: it does not affect
	// current validation, but gives future incompatible changes a place
	// to branch on instead of guessing from field presence.
	Version string `json:"version,omitempty" yaml:"version,omitempty"`

	// Bindings associate the whole format (not any single asset/field)
	// with an external protocol representation — e.g. OpenRTB Video
	// Protocols/APIs/Linearity/PlaybackMethod, which have no
	// protocol-agnostic equivalent on any single AssetRequirement
	// (§3.2.12).
	Bindings []Binding `json:"bindings,omitempty" yaml:"bindings,omitempty"`

	// Sizes is the multiselect of overall display-area sizes, replacing
	// the old single Width/Height/MinWidth/MinHeight pair (§3.2.13).
	Sizes []SizeOption `json:"sizes,omitempty" yaml:"sizes,omitempty"`

	// Config is the recursive structure of assets/fields/groups/params
	// that make up this creative.
	Config *Config `json:"config,omitempty" yaml:"config,omitempty"`
}

Format describes the creative that one advertiser prepares and uploads for one ad (was admodels/types.Format) — see §3.0 for the exact scope boundary (one creative of one advertiser, never a placement-level composition of several ads).

func DecodeAny

func DecodeAny(name string, data []byte) (*Format, error)

DecodeAny decodes a Format from data, choosing the JSON or YAML decoder based on the file extension of name (".json" vs anything else, treated as YAML — a superset of JSON). Useful together with embed.FS, where the file name/extension is already known.

func LoadJSON

func LoadJSON(data []byte) (*Format, error)

LoadJSON decodes a single Format from JSON data and validates it.

func LoadYAML

func LoadYAML(data []byte) (*Format, error)

LoadYAML decodes a single Format from YAML data and validates it (§3.2.6). Since Node/Config use plain yaml tags with no custom (Un)Marshal code, the YAML shape is a direct mirror of the Go structures — see node.go.

func ReadJSON

func ReadJSON(r io.Reader) (*Format, error)

ReadJSON reads and decodes a single Format from r.

func ReadYAML

func ReadYAML(r io.Reader) (*Format, error)

ReadYAML reads and decodes a single Format from r.

func (Format) DefaultSize

func (f Format) DefaultSize() (SizeOption, bool)

DefaultSize returns the SizeOption explicitly marked Default; if none is marked and there is exactly one option, that one is the default; otherwise the first option is returned. ok is false only when Sizes is empty.

func (*Format) GetConfig

func (f *Format) GetConfig() *Config

GetConfig of the format object, safe on a nil Format.

func (Format) HasTag

func (f Format) HasTag(tag string) bool

HasTag reports whether the format carries the given tag.

func (Format) IsAudio

func (f Format) IsAudio() bool

IsAudio format kind.

func (Format) IsBanner

func (f Format) IsBanner() bool

IsBanner format kind.

func (Format) IsDirect

func (f Format) IsDirect() bool

IsDirect format kind (popunder/proxy-click).

func (Format) IsFixedSize

func (f Format) IsFixedSize() bool

IsFixedSize reports whether every SizeOption is a plain exact size (none Flexible) — helps a UI decide whether a size picker is needed at all.

func (Format) IsNative

func (f Format) IsNative() bool

IsNative format kind.

func (Format) IsPush

func (f Format) IsPush() bool

IsPush format kind.

func (Format) IsVideo

func (f Format) IsVideo() bool

IsVideo format kind.

func (Format) String

func (f Format) String() string

String representation of the format, preferring its default size when one is set.

func (Format) Suits

func (f Format) Suits(width, height int) bool

Suits reports whether width/height matches at least one of f.Sizes. A Format with no Sizes at all (e.g. direct/popunder, native "strip" with no fixed container) suits any size — it has no display-area constraint to check.

func (Format) SupportsOrientation

func (f Format) SupportsOrientation(o Orientation) bool

SupportsOrientation reports whether o is supported — an empty Orientations list means "supports any orientation" (§3.2.2).

func (Format) Validate

func (f Format) Validate() error

Validate the whole format: its Config tree (§3.2.6) plus every Format-level SizeOption bound.

type GeoValue

type GeoValue struct {
	Lat float64 `json:"lat" yaml:"lat"`
	Lng float64 `json:"lng" yaml:"lng"`
}

GeoValue is the value shape of a FieldGeoType field.

func (GeoValue) Validate

func (g GeoValue) Validate() error

Validate reports whether the coordinates are within valid ranges.

type Kind

type Kind string

Kind is the primary media/content type of an ad format (banner, video, native, ...). It is a plain, open-ended string instead of a bitmask (the old admodels/types.FormatTypeBitset was capped at 32 flags and mixed two independent axes — media type and display surface/behavior) so new values can be added without any change to this package. The secondary, open-ended axis (display surface/behavior: interstitial, dooh, tv, ingame, vr, preroll, push-notification, product-card, mraid, playable, interactive-end-card, expandable, rewarded, ...) lives in Format.Tags.

const (
	KindDirect Kind = "direct" // popunder / proxy-click
	KindBanner Kind = "banner"
	KindVideo  Kind = "video"
	KindAudio  Kind = "audio"
	KindNative Kind = "native"
	KindPush   Kind = "push"
	KindCustom Kind = "custom"
)

Kind values covering all media types of the old model.

func (Kind) String

func (k Kind) String() string

String implements fmt.Stringer.

type Node

type Node struct {
	Kind  NodeKind          `json:"kind" yaml:"kind"`
	Asset *AssetRequirement `json:"asset,omitempty" yaml:"asset,omitempty"`
	Field *Field            `json:"field,omitempty" yaml:"field,omitempty"`
	Group *Config           `json:"group,omitempty" yaml:"group,omitempty"` // recursion
	Param *Param            `json:"param,omitempty" yaml:"param,omitempty"`
}

Node is the single recursive element of the format-structure tree. Exactly one of Asset/Field/Group/Param is set, matching Kind. It replaces three parallel typed slices (Assets/Fields/Groups) that used to live directly on Config — see §3.2.7 for the rationale. Node/Config use plain json/yaml tags (no custom (Un)Marshal): the wire format is a direct mirror of this Go structure — a "children" list where every element carries an explicit "kind" plus a nested "asset"/"field"/ "group"/"param" object.

Application code is not expected to build Node values by hand — see builder.go, which exposes Asset()/StringField()/Group()/Param() constructors plus Config.WithAssets/WithFields/WithGroups/WithParams that wrap values into Node internally.

func AssetNode

func AssetNode(a AssetRequirement) Node

AssetNode wraps an AssetRequirement into a Node — a small helper for the rare bare Go literal that does not go through builder.go.

func FieldNode

func FieldNode(f Field) Node

FieldNode wraps a Field into a Node.

func GroupNode

func GroupNode(c Config) Node

GroupNode wraps a Config into a Node.

func ParamNode

func ParamNode(p Param) Node

ParamNode wraps a Param into a Node.

func (Node) Condition

func (n Node) Condition() *Condition

Condition is a read-only proxy returning the Condition of whichever spec is set, or nil if none/not applicable.

func (Node) IsActive

func (n Node) IsActive(values map[string]any) bool

IsActive reports whether the node is active given the current set of field/asset values — true when the node carries no Condition, or its Condition evaluates to true against values.

func (Node) Name

func (n Node) Name() string

Name is a read-only proxy that returns the name of whichever spec (Asset/Field/Group/Param) is set — a single point of access for generic engine code (Validate, Walk, ActiveNodes) that does not need to know Kind to read this common attribute. Returns "" for a zero Node.

func (Node) NavigateTo

func (n Node) NavigateTo() string

NavigateTo is a read-only proxy returning the fixed screen-navigation target of whichever spec is set (only meaningful for asset/field, §3.2.11) — empty string means "no navigation".

type NodeKind

type NodeKind string

NodeKind discriminates which field of Node is populated.

const (
	NodeAsset NodeKind = "asset"
	NodeField NodeKind = "field"
	NodeGroup NodeKind = "group"
	NodeParam NodeKind = "param" // §3.2.14 — hidden, non-editable value
)

Node kinds.

type Option

type Option struct {
	Value any    `json:"value" yaml:"value"`
	Title string `json:"title,omitempty" yaml:"title,omitempty"` // if empty, a UI shows Value as-is
}

Option is a single selectable choice for a Field, rendered as a dropdown/checkbox/select control by a UI builder. Works for both string and numeric field types — Value's concrete type should match Field.Type (e.g. a string for FieldStringType, a number for FieldIntType/FieldFloatType). Replaces the old, inconsistently-shaped FormatField.Select []any (§3.2.3).

func Opt

func Opt(value any, title string) Option

Opt builds a single Option for Field.WithOptions.

type Orientation

type Orientation string

Orientation is a supported screen orientation for a creative (§3.2.2).

const (
	OrientationPortrait  Orientation = "portrait"
	OrientationLandscape Orientation = "landscape"
)

Orientation values.

type Param

type Param struct {
	Name      string     `json:"name" yaml:"name"`
	Value     any        `json:"value" yaml:"value"`
	Condition *Condition `json:"condition,omitempty" yaml:"condition,omitempty"`
}

Param is a fixed, author-supplied value embedded directly in the Config tree — unlike Field, never shown to or editable by whoever fills in the ad creative. Used to carry hidden/internal context alongside the visible structure: a fixed template/layout id, a partner-specific tag, a hardcoded default consumed by the rendering engine, or any other constant that needs to travel WITH a specific group/screen (so nested Param values inside different named groups/screens can differ) rather than living as a single Format-level constant (§3.2.14).

func NewParam

func NewParam(name string, value any) Param

NewParam builds a Param with the given name/value. Named NewParam, not Param, because a top-level function cannot share its name with the Param type (see the package-level deviation note above).

func (Param) GetName

func (p Param) GetName() string

GetName of the param.

func (Param) When

func (p Param) When(c Condition) Param

When attaches a Condition controlling this param's activity (§3.2.5).

type SafeZone

type SafeZone struct {
	Top    float64 `json:"top,omitempty" yaml:"top,omitempty"`
	Right  float64 `json:"right,omitempty" yaml:"right,omitempty"`
	Bottom float64 `json:"bottom,omitempty" yaml:"bottom,omitempty"`
	Left   float64 `json:"left,omitempty" yaml:"left,omitempty"`
}

SafeZone declares edge insets (as fractions of the asset's own width/height, 0..1) that the display client must keep free of overlaid interface chrome (logo, countdown timer, skip/close/CTA button, §3.2.1 gap #2). Exactly like FocalPoint, this is pure positioning metadata: the asset file itself is never cropped or modified by adformat or the ad server, the display client is responsible for keeping this area in mind when compositing its own controls over the creative.

type SimpleAccessor

type SimpleAccessor struct {
	// contains filtered or unexported fields
}

SimpleAccessor implements a basic in-memory Accessor (was admodels/types.SimpleFormatAccessor). It accepts either a static Go slice/var-table of Format values (§3.2.10) or the result of loading codec.go-produced YAML/JSON — both paths produce the same Format type, so the accessor (and any downstream validation engine) never needs to know how a Format was built.

func NewSimpleAccessor

func NewSimpleAccessor(formats ...*Format) *SimpleAccessor

NewSimpleAccessor from a fixed list of formats. Accepts value or pointer formats for convenience with both Go var-table literals and codec.go decode results.

func (*SimpleAccessor) DirectFormatSet

func (fa *SimpleAccessor) DirectFormatSet() *searchtypes.NumberBitset[uint]

DirectFormatSet to search.

func (*SimpleAccessor) FormatByCode

func (fa *SimpleAccessor) FormatByCode(code string) *Format

FormatByCode of the model.

func (*SimpleAccessor) FormatByID

func (fa *SimpleAccessor) FormatByID(id uint64) *Format

FormatByID of the model — requires Prepare (called by NewSimpleAccessor) to have run first, otherwise the binary search may silently return the wrong result.

func (*SimpleAccessor) Formats

func (fa *SimpleAccessor) Formats() []*Format

Formats list collection.

func (*SimpleAccessor) FormatsBySize

func (fa *SimpleAccessor) FormatsBySize(width, height int) []*Format

FormatsBySize returns the list of formats whose Sizes accept width/height; direct formats are always included, since they carry no display area at all.

func (*SimpleAccessor) Prepare

func (fa *SimpleAccessor) Prepare()

Prepare sorts the format list by ID — required for FormatByID's binary search to work; called automatically by NewSimpleAccessor, but exposed for callers that mutate Formats() directly afterwards.

type SizeOption

type SizeOption struct {
	Title string `json:"title,omitempty" yaml:"title,omitempty"` // optional, for a UI label ("Medium Rectangle")

	// Exact size, when Flexible == false (the common case — a classic
	// fixed-size banner, a standard IAB size, a fixed native strip).
	Width  int `json:"width,omitempty" yaml:"width,omitempty"`
	Height int `json:"height,omitempty" yaml:"height,omitempty"`

	// Flexible: the concrete size is picked not by the format's author
	// but by whoever creates a particular creative from this format
	// (same principle as FocalPoint — the concrete value is data of a
	// particular creative, not part of the format schema). The Min/Max*
	// fields below are optional bounds on that free choice (needed for
	// an iframe banner, which still must match a reasonable range of
	// third-party slots rather than being fully unbounded); unset = no
	// bound.
	Flexible  bool `json:"flexible,omitempty" yaml:"flexible,omitempty"`
	MinWidth  int  `json:"min_width,omitempty" yaml:"min_width,omitempty"`
	MaxWidth  int  `json:"max_width,omitempty" yaml:"max_width,omitempty"`
	MinHeight int  `json:"min_height,omitempty" yaml:"min_height,omitempty"`
	MaxHeight int  `json:"max_height,omitempty" yaml:"max_height,omitempty"`

	// Default marks this option as pre-selected when there is more than
	// one. Not needed when Sizes has exactly one element — the only
	// option is unambiguously the default without an explicit flag.
	Default bool `json:"default,omitempty" yaml:"default,omitempty"`
}

SizeOption is one selectable overall display-area size for a Format (the ad unit's outer container) — not any individual asset's file dimensions, which stay on AssetRequirement (see MinWidth/MaxWidth there). Generalizes: a single classic fixed-size banner (one exact-size SizeOption), an IAB "multi-size" ad unit (several exact-size options), and a stretchable iframe/native container (a Flexible option with its own optional bounds) — under one mechanism, for any Kind, not only banner (§3.2.13).

func FixedSize

func FixedSize(title string, width, height int) SizeOption

FixedSize builds a single exact-size SizeOption (§3.2.13).

func FlexibleSize

func FlexibleSize(title string, minW, maxW, minH, maxH int) SizeOption

FlexibleSize builds a flexible SizeOption with optional bounds — pass 0 for an unbounded side (§3.2.13).

func (SizeOption) AsDefault

func (s SizeOption) AsDefault() SizeOption

AsDefault marks this SizeOption as pre-selected when a Format has more than one.

func (SizeOption) IsFixed

func (s SizeOption) IsFixed() bool

IsFixed reports whether this option describes a single exact size (not Flexible, with both Width/Height set).

func (SizeOption) Suits

func (s SizeOption) Suits(width, height int) bool

Suits reports whether the given width/height matches this size option — an exact match for a non-flexible option, or falling within Min/MaxWidth/Height for a flexible one (unset bounds = unbounded on that side).

type Thumb

type Thumb struct {
	Width  int `json:"width,omitempty" yaml:"width,omitempty"`
	Height int `json:"height,omitempty" yaml:"height,omitempty"`
}

Thumb describes one autogenerated thumbnail size for an asset — structured replacement for the old undocumented mini-DSL (`thumbs: ["250x", "350x", "500x"]`, §3.2.1). Height is optional (0 = auto, keep the source aspect ratio).

Directories

Path Synopsis
Package adformattest provides test fixtures for adformat — the counterpart of admodels/types.MockFormats(), but backed by embed.FS (via adformat/examples) instead of the old, fragile runtime.Caller(1) + os.Open("../assets/...") pair, which broke when a package was moved or vendored.
Package adformattest provides test fixtures for adformat — the counterpart of admodels/types.MockFormats(), but backed by embed.FS (via adformat/examples) instead of the old, fragile runtime.Caller(1) + os.Open("../assets/...") pair, which broke when a package was moved or vendored.
Package examples embeds the adformat/examples/*.yaml sample formats (§4 of the design plan) via embed.FS, so they can be loaded without a fragile runtime.Caller + os.Open dance (the old admodels/types/format_mock.go approach) and reused both by tests and by adformat/adformattest.
Package examples embeds the adformat/examples/*.yaml sample formats (§4 of the design plan) via embed.FS, so they can be loaded without a fragile runtime.Caller + os.Open dance (the old admodels/types/format_mock.go approach) and reused both by tests and by adformat/adformattest.
Package openrtbnative is a reference adformat.Binding adapter (§3.2.12) associating adformat assets/fields with OpenRTB Native 1.2 asset objects — a concrete, typed replacement for the name-based guessing that adsource-openrtb currently does (see adsource-openrtb/request/v2/builder.go), and for the always-empty FormatFileRequirement.ID/FormatField.ID of the old model.
Package openrtbnative is a reference adformat.Binding adapter (§3.2.12) associating adformat assets/fields with OpenRTB Native 1.2 asset objects — a concrete, typed replacement for the name-based guessing that adsource-openrtb currently does (see adsource-openrtb/request/v2/builder.go), and for the always-empty FormatFileRequirement.ID/FormatField.ID of the old model.
Package openrtbvideo is a reference adformat.Binding adapter (§3.2.12) associating a whole adformat.Format with an OpenRTB Video object's properties.
Package openrtbvideo is a reference adformat.Binding adapter (§3.2.12) associating a whole adformat.Format with an OpenRTB Video object's properties.
Package tracking is a reference adformat.Binding adapter (§3.2.16) for protocol-agnostic fire-and-forget impression/click tracking pixels, applicable to any Format.Kind (native/banner/push/direct).
Package tracking is a reference adformat.Binding adapter (§3.2.16) for protocol-agnostic fire-and-forget impression/click tracking pixels, applicable to any Format.Kind (native/banner/push/direct).
Package vasttracking is a reference adformat.Binding adapter (§3.2.16) for the full VAST 4.x tracking-event dictionary, used by in-stream video creatives (Format.Kind == KindVideo).
Package vasttracking is a reference adformat.Binding adapter (§3.2.16) for the full VAST 4.x tracking-event dictionary, used by in-stream video creatives (Format.Kind == KindVideo).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL