openrtb

OpenRTB, AdCOM and OpenRTB Dynamic Native Ads types for Go programming language

• openrtb2 - OpenRTB 2.5, 2.6
• openrtb3 - OpenRTB 3.0 (can lag behind because official spec is constantly updated without version bump, feel free to PR)
• adcom1 - AdCOM 1.0 (can lag behind because official spec is constantly updated without version bump, feel free to PR)
• native1 - OpenRTB Dynamic Native Ads API 1.2

Requires Go 1.16+

This library uses Go modules (tl;dr) and requires Go 1.16+ for the ability to issue release retractions.

Using

go get -u "github.com/prebid/openrtb/v20/..."

import (
	openrtb2 "github.com/prebid/openrtb/v20/openrtb2"

	openrtb3 "github.com/prebid/openrtb/v20/openrtb3"
	adcom1 "github.com/prebid/openrtb/v20/adcom1"

	native1 "github.com/prebid/openrtb/v20/native1"
	nreq "github.com/prebid/openrtb/v20/native1/request"
	nres "github.com/prebid/openrtb/v20/native1/response"
)

This repo follows semver - see releases. The main branch always contains latest code, so better use some package manager to vendor specific version.

Guidelines

Naming convention

• UpperCamelCase
• Capitalized abbreviations (e.g., AT, COPPA, PMP etc.)
• Capitalized ID keys
• Enum items with versions should include minor/patch zeros, i.e. "Foo 1.0" -> Foo10 (and not just Foo1), "Foo 1.1" -> Foo11 etc

Types

• Key types should be chosen according to OpenRTB specification (attribute types)
• Numeric types:
  • int8 - short enums (with values <= 127), boolean-like attributes (like BidRequest.test)
  • int64 - other integral types
  • float64 - coordinates, prices etc.
• Enums:
  • all enums, described in section 5, must be typed with section name singularized (e.g., "5.2 Banner Ad Types" -> type BannerAdType int8)
  • all typed enums must have constants for each element, prefixed with type name (e.g., "5.2 Banner Ad Types - XHTML Text Ad (usually mobile)" -> const BannerAdTypeXHTMLTextAd BannerAdType = 1)
  • never use iota for enum constants
  • OpenRTB (2.x) "content categories" should remain untyped and have no constants

Pointers/omitempty

Pointer | Omitempty | When to use | Example ------- | --------- | -------------------------------------------------------------------- | --------------------------------- no | no | required in spec | Audio.MIMEs yes | yes | required in spec, but is a part of mutually-exclusive group | Imp.{Banner,Video,Audio,Native} no | yes | zero value ("", 0) has no meaning, is defined in the spec as the default value, or represents time / duration | Device.UA yes | yes | zero value ("", 0) or value absence (null) has special meaning | Device.{DNT,Lmt}

Using both pointer and omitempty is mostly just to save traffic / generate more "canonical" (strict) JSON.

Documentation (pkg.go.dev)

• Godoc: documenting Go code
• Each entity (type, struct key or constant) should be documented
• Ideally, copy-paste descriptions as-is, but feel free to omit section numbers, so just <GoTypeName> defines <copy-pasted description from spec>

Code organization

• Each RTB type should be kept in its own file, named after type
• File names are in underscore_case, e.g., type BidRequest should be declared in bid_request.go
• go fmt your code
• EditorConfig (not required, but useful)

Acknowledgments

This library was originally developed by mxmCherry under The Unlicense license, still available at https://github.com/mxmCherry/openrtb but no longer maintained. Prebid.org's efforts to continue development are offered under the Apache 2.0 license.