googleapis/swift-google-wkt

Idiomatic Swift implementations of Protocol Buffers Well-Known Types.

Overview

GoogleWKT provides Swift implementations of Well-Known Types (WKT) for Protocol Buffers and Discovery used across Google Cloud APIs.

While standard Swift and Foundation libraries offer types like Date and Duration, their precision, range, and JSON serialization semantics differ from the Protocol Buffers specifications. This package bridges that gap by providing strongly-typed, high-precision representations that strictly follow Google Cloud API conventions and ProtoJSON mapping rules.

Key Types

WKTTimestamp: UTC point in time with nanosecond resolution covering years

0001-01-01 to 9999-12-31. Serializes to and from RFC 3339 formatted strings (e.g., "2026-09-03T19:48:28.000000000Z"). Avoids the valid range and precision limits of Foundation.Date.

WKTDuration: Signed, fixed-length time span with nanosecond resolution.

Serializes to and from decimal strings with an "s" suffix (e.g., "3.5s").

WKTFieldMask: Represents a set of symbolic field paths for partial update

requests and read projections. Automatically converts to and from comma-separated camelCase strings in JSON (e.g., "displayName,userProfile.avatarUrl").

WKTAny: Container for arbitrary serialized messages accompanied by a

@type URL identifier.

WKTEmpty: An empty request or response message, automatically converted

to Void where appropriate by client libraries.

Embedded JSON Objects

Some APIs use dynamic JSON-compatible data structures to represent parts of their request or response payloads:

WKTStruct, WKTValue, WKTListValue, WKTNullValue

Optional Primitive Values

APIs using Protocol Buffers wrapper types represent optional or nullable fields via:

WKTStringValue, WKTInt32Value, WKTInt64Value, WKTUInt32Value, WKTUInt64Value
WKTFloatValue, WKTDoubleValue, WKTBoolValue, WKTBytesValue

Recursive Field Wrapper

WKTRecursive: Box wrapper enabling self-referential or recursively nested

fields in API models without infinite value type layout size.

API Introspection

WKTApi: Introspection types for services that consume or expose API definitions

as part of their operations.

Requirements

For the minimum supported Swift version and platform requirements, see the Requirements section in the google-cloud-swift repository.

Installation

Add swift-google-wkt as a package dependency:

swift package add-dependency https://github.com/googleapis/swift-google-wkt.git --from 0.1.0

Then add GoogleWKT to your target's dependencies:

swift package add-target-dependency GoogleWKT <target-name> --package swift-google-wkt

Usage

Timestamp (WKTTimestamp)

WKTTimestamp represents a point in time independent of timezone or calendar:

import Foundation
import GoogleWKT

// Create a WKTTimestamp from the current time or a Foundation.Date
let now = WKTTimestamp.now
let fromDate = WKTTimestamp(Date())
print("Date: \(fromDate.date), RFC 3339: \(fromDate)")

// Create a WKTTimestamp with seconds and nanoseconds
let timestamp = try WKTTimestamp(seconds: 1_700_000_000, nanos: 500_000_000)
print("Seconds: \(timestamp.seconds), Nanos: \(timestamp.nanos)")

// Encodes to and decodes from RFC 3339 formatted JSON strings
let encoder = JSONEncoder()
let data = try encoder.encode(timestamp) // "2023-11-14T22:13:20.500Z"

let decoded = try JSONDecoder().decode(WKTTimestamp.self, from: data)

Duration (WKTDuration)

WKTDuration represents a fixed-length span of time:

import Foundation
import GoogleWKT

// Create a WKTDuration of 45.25 seconds
let duration = try WKTDuration(seconds: 45, nanos: 250_000_000)

// Encodes in JSON to "45.250000000s"
let data = try JSONEncoder().encode(duration)
let decoded = try JSONDecoder().decode(WKTDuration.self, from: data)

FieldMask (WKTFieldMask)

WKTFieldMask is used for partial update operations and projection filters:

import Foundation
import GoogleWKT

// Specify the paths to update
let mask: WKTFieldMask = ["display_name", "billing_account.id"]

// Formatted as comma-separated camelCase: "displayName,billingAccountId"
print(mask)

// Encodes in ProtoJSON as comma-separated camelCase: "displayName,billingAccountId"
let data = try JSONEncoder().encode(mask)
let decoded = try JSONDecoder().decode(WKTFieldMask.self, from: data)

Contributing

Contributions to this library are always welcome and highly encouraged.

All development, issues, and pull requests are managed in the google-cloud-swift monorepo. See CONTRIBUTING.md for details on getting started.

License

Apache 2.0 - See LICENSE for more information.

Package Metadata

Repository: googleapis/swift-google-wkt

Default branch: main

README: README.md