strfmt

---

Golang support for string formats defined by JSON Schema and OpenAPI.

Announcements

• 2026-03-07 : v0.26.0 dropped dependency to the mongodb driver
  • mongodb users can still use this package without any change
  • however, we have frozen the back-compatible support for mongodb driver at v2.5.0
  • users who want to keep-up with future evolutions (possibly incompatible) of this driver can do so by adding a blank import in their program: import _ "github.com/go-openapi/strfmt/enable/mongodb". This will switch the behavior to the actual driver, which remains regularly updated as an independent module.

Status

API is stable.

Import this library in your project

go get github.com/go-openapi/strfmt

Contents

This package exposes a registry of data types to support string formats in the go-openapi toolkit.

strfmt represents a well known string format such as hostname or email.

This package provides a few extra formats such as credit card (US), color, etc.

Format types can serialize and deserialize JSON or from a SQL database.

BSON is also supported (MongoDB).

Supported formats

go-openapi/strfmt follows the swagger 2.0 specification with the following formats defined here.

It also provides convenient extensions to go-openapi users.

• JSON-schema draft 4 formats
  • date-time
  • email
  • hostname
  • ipv4
  • ipv6
  • uri
• swagger 2.0 format extensions
  • binary
  • byte (e.g. base64 encoded string)
  • date (e.g. "1970-01-01")
  • password
• go-openapi custom format extensions
  • bsonobjectid (BSON objectID)
  • creditcard
  • duration (e.g. "3 weeks", "1ms") (aka "duration-human")
  • hexcolor (e.g. "#FFFFFF")
  • isbn, isbn10, isbn13
  • mac (e.g "01:02:03:04:05:06")
  • rgbcolor (e.g. "rgb(100,100,100)")
  • ssn
  • uuid, uuid3, uuid4, uuid5, uuid7
  • cidr (e.g. "192.0.2.1/24", "2001:db8:a0b:12f0::1/32")
  • ulid (e.g. "00000PP9HGSBSSDZ1JTEXBJ0PW", spec)
• JSON-schema draft 2020 formats
  • duration-iso8601 B(e.g. "P2W")

NOTE: as the name stands for, this package is intended to support string formatting only. It does not provide validation for numerical values with swagger format extension for JSON types "number" or "integer" (e.g. float, double, int32...).

Durations

We have 2 very different definitions of the "duration" format: the "human-readable" duration that used to be just "duration", and the new "duration-iso8601". There is no "dual" parser that accepts both formats: types are specialized.

To clarify the situation, a new alias for the duration format is introduced "duration-human" (e.g. "1 ms"), as opposed to "duration-iso8601".

The Default format registry wires "duration-human" as the default mapping for "duration" (preexisting behavior, no breaking change - aligned with Swagger 2.0 which did not define "duration").

A new JSONSchema2020 registry wires "duration-iso8601" as the default mapping for "duration".

Type conversion

All types defined here are stringers and may be converted to strings with .String(). Note that most types defined by this package may be converted directly to string like string(Email{}).

Date and DateTime may be converted directly to time.Time like time.Time(Time{}). Similarly, you can convert Duration to time.Duration as in time.Duration(Duration{})

Using pointers

The conv subpackage provides helpers to convert the types to and from pointers, just like go-openapi/swag does with primitive types.

Format types

Types defined in strfmt expose marshaling and validation capabilities.

List of defined types:

• Base64
• CreditCard
• Date
• DateTime
• Duration
• DurationISO8601 and ISODuration[P ISODurationPolicy] (for optional behavior)
• Email
• HexColor
• Hostname
• IPv4
• IPv6
• CIDR
• ISBN
• ISBN10
• ISBN13
• MAC
• ObjectId
• Password
• RGBColor
• SSN
• URI
• UUID
• UUID3
• UUID4
• UUID5
• UUID7
• ULID

Database support

All format types implement the database/sql interfaces sql.Scanner and driver.Valuer, so they work out of the box with Go's standard database/sql package and any SQL driver.

All format types also implement BSON marshaling/unmarshaling for use with MongoDB. By default, a built-in minimal codec is used (compatible with mongo-driver v2.5.0). For full driver support, add import _ "github.com/go-openapi/strfmt/enable/mongodb".

MySQL / MariaDB caveat for DateTime: The go-sql-driver/mysql driver has hard-coded handling for time.Time but does not intercept type redefinitions like strfmt.DateTime. As a result, DateTime.Value() sends an RFC 3339 string (e.g. "2024-06-15T12:30:45.123Z") that MySQL/MariaDB rejects for DATETIME columns.

Workaround: set strfmt.MarshalFormat to a MySQL-compatible format such as strfmt.ISO8601LocalTime and normalize to UTC before marshaling:

strfmt.MarshalFormat = strfmt.ISO8601LocalTime
strfmt.NormalizeTimeForMarshal = func(t time.Time) time.Time { return t.UTC() }

See #174 for details.

Integration tests for MongoDB, MariaDB, and PostgreSQL run in CI to verify database roundtrip compatibility for all format types. See internal/testintegration/.

Change log

See https://github.com/go-openapi/strfmt/releases

References

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md

Licensing

This library ships under the SPDX-License-Identifier: Apache-2.0.

Other documentation

• All-time contributors
• Contributing guidelines
• Maintainers documentation
• Code style

Cutting a new release

Maintainers can cut a new release by either:

• running this workflow
• or pushing a semver tag
  • signed tags are preferred
  • The tag message is prepended to release notes