Implementation:Mage ai Mage ai Google Ads Ads Schema

Knowledge Sources	Mage Integrations Google Ads API
Domains	Data_Integration, Google_Ads, Schema
Last Updated	2026-02-09 00:00 GMT

Overview

JSON Schema definition for Google Ads ad records used by the Singer-based Google Ads source connector.

Description

The ads.json schema file defines the complete data structure for Google Ads ad entities as consumed by the tap_google_ads Singer-based source connector within Mage Integrations. At 1759 lines, this is a comprehensive schema covering all Google Ads ad types and their associated metadata.

The schema is typed as ["null", "object"] at the top level and defines the following key properties:

Scalar properties (simple types):

addedByGoogleAds -- boolean indicating if the ad was auto-created by Google
devicePreference -- string for device targeting preference
displayUrl -- string for the display URL shown in the ad
id -- integer unique identifier for the ad
name -- string name of the ad
resourceName -- string Google Ads API resource name
systemManagedResourceSource -- string source identifier for system-managed resources
trackingUrlTemplate -- string URL template for click tracking
type -- string ad type enumeration

Array properties:

finalAppUrls -- array of FinalAppUrl objects for app deep links
finalMobileUrls -- array of strings for mobile landing page URLs
finalUrls -- array of strings for landing page URLs
urlCollections -- array of UrlCollection objects
urlCustomParameters -- array of CustomParameter objects
finalUrlSuffix -- string suffix appended to final URLs

Ad type sub-objects (via $ref definitions):

appAd -- AppAdInfo
appEngagementAd -- AppEngagementAdInfo
appPreRegistrationAd -- AppPreRegistrationAdInfo
callAd -- CallAdInfo
displayUploadAd -- DisplayUploadAdInfo
expandedDynamicSearchAd -- ExpandedDynamicSearchAdInfo
expandedTextAd -- ExpandedTextAdInfo
gmailAd -- GmailAdInfo
hotelAd -- HotelAdInfo
imageAd -- ImageAdInfo
legacyAppInstallAd -- LegacyAppInstallAdInfo
legacyResponsiveDisplayAd -- LegacyResponsiveDisplayAdInfo
localAd -- LocalAdInfo
responsiveDisplayAd -- ResponsiveDisplayAdInfo
responsiveSearchAd -- ResponsiveSearchAdInfo
shoppingComparisonListingAd -- ShoppingComparisonListingAdInfo
shoppingProductAd -- ShoppingProductAdInfo
shoppingSmartAd -- ShoppingSmartAdInfo
smartCampaignAd -- SmartCampaignAdInfo
textAd -- TextAdInfo
videoAd -- VideoAdInfo
videoResponsiveAd -- VideoResponsiveAdInfo

The definitions section includes detailed sub-schemas for each ad type, URL constraints (CountryConstraint, CountryConstraintList), and other nested structures.

Usage

This schema is automatically loaded by the Google Ads source connector during stream discovery. It is read from disk by the Source.load_schemas_from_folder() method and used to define the Singer catalog entry for the ads stream.

Code Reference

Source Location

Repository: mage-ai
File: mage_integrations/mage_integrations/sources/google_ads/tap_google_ads/schemas/ads.json
Lines: 1-1759

Signature

{
  "type": ["null", "object"],
  "properties": {
    "addedByGoogleAds": { "type": ["null", "boolean"] },
    "appAd": { "$ref": "#/definitions/AppAdInfo" },
    "appEngagementAd": { "$ref": "#/definitions/AppEngagementAdInfo" },
    "callAd": { "$ref": "#/definitions/CallAdInfo" },
    "devicePreference": { "type": ["null", "string"] },
    "displayUploadAd": { "$ref": "#/definitions/DisplayUploadAdInfo" },
    "displayUrl": { "type": ["null", "string"] },
    "expandedDynamicSearchAd": { "$ref": "#/definitions/ExpandedDynamicSearchAdInfo" },
    "expandedTextAd": { "$ref": "#/definitions/ExpandedTextAdInfo" },
    "finalAppUrls": { "type": ["null", "array"], "items": { "$ref": "#/definitions/FinalAppUrl" } },
    "finalMobileUrls": { "type": ["null", "array"] },
    "finalUrls": { "type": ["null", "array"] },
    "gmailAd": { "$ref": "#/definitions/GmailAdInfo" },
    "hotelAd": { "$ref": "#/definitions/HotelAdInfo" },
    "id": { "type": ["null", "integer"] },
    "imageAd": { "$ref": "#/definitions/ImageAdInfo" },
    "name": { "type": ["null", "string"] },
    "resourceName": { "type": ["null", "string"] },
    "responsiveDisplayAd": { "$ref": "#/definitions/ResponsiveDisplayAdInfo" },
    "responsiveSearchAd": { "$ref": "#/definitions/ResponsiveSearchAdInfo" },
    "shoppingComparisonListingAd": { "$ref": "#/definitions/ShoppingComparisonListingAdInfo" },
    "shoppingProductAd": { "$ref": "#/definitions/ShoppingProductAdInfo" },
    "smartCampaignAd": { "$ref": "#/definitions/SmartCampaignAdInfo" },
    "textAd": { "$ref": "#/definitions/TextAdInfo" },
    "trackingUrlTemplate": { "type": ["null", "string"] },
    "type": { "type": ["null", "string"] },
    "videoAd": { "$ref": "#/definitions/VideoAdInfo" },
    "videoResponsiveAd": { "$ref": "#/definitions/VideoResponsiveAdInfo" }
  },
  "definitions": {
    "CountryConstraint": { "countryCriterion": { "type": ["null", "string"] } },
    "CountryConstraintList": { "type": ["null", "object"], "properties": { "..." : "..." } }
    // ... additional ad type definitions (AppAdInfo, CallAdInfo, etc.)
  }
}

Import

# Loaded automatically by Source.load_schemas_from_folder()
# The schema file is discovered by convention from the schemas/ directory

I/O Contract

Inputs

Name	Type	Required	Description
(none)	JSON file	Yes	Loaded from disk by the schema loader during stream discovery

Outputs

Name	Type	Description
schema	dict	JSON Schema object defining property names, types (null, boolean, string, integer, array, object), format constraints, and $ref definitions for all Google Ads ad types

Usage Examples

import json

schema_path = "mage_integrations/mage_integrations/sources/google_ads/tap_google_ads/schemas/ads.json"
with open(schema_path) as f:
    schema = json.load(f)

# List top-level properties
print(list(schema["properties"].keys())[:10])
# ['addedByGoogleAds', 'appAd', 'appEngagementAd', 'appPreRegistrationAd',
#  'callAd', 'devicePreference', 'displayUploadAd', 'displayUrl',
#  'expandedDynamicSearchAd', 'expandedTextAd']

# Check the type of a specific property
print(schema["properties"]["id"])
# {'type': ['null', 'integer']}

# List all ad type definitions
print(list(schema.get("definitions", {}).keys())[:5])
# ['CountryConstraint', 'CountryConstraintList', 'AppAdInfo', ...]

Related Pages

Implements Principle

Principle:Mage_ai_Mage_ai_JSON_Schema_Loading

Requires Environment

Environment:Mage_ai_Mage_ai_Python_3_9_Runtime

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment