Struct Tag Validation

Relevant source files

• go.mod
• go.sum
• rule/filename_format.go
• rule/struct_tag.go
• test/struct_tag_test.go
• testdata/go.mod
• testdata/go.sum
• testdata/go1.24/go.mod
• testdata/go1.24/struct_tag.go
• testdata/struct_tag.go
• testdata/struct_tag_user_options.go
• testdata/struct_tag_user_options_omit.go
• tools/go.mod
• tools/go.sum

The struct-tag rule validates struct field tags in Go code to ensure they conform to the expected syntax and semantics for various serialization, validation, and mapping libraries. This rule detects malformed tags, unknown options, duplicated tag names, type mismatches, and other tag-related issues across 17 different tag types.

For information about creating custom rules, see Creating Custom Rules. For other correctness and safety rules, see Correctness and Safety Rules.

Sources: rule/struct_tag.go16-157

Supported Tag Types

The struct-tag rule validates tags for the following libraries and frameworks:

Tag Key	Purpose	Common Options	Validation Features
json	JSON serialization	omitempty, string, omitzero (Go 1.24+)	Duplicate name detection, option validation
xml	XML serialization	attr, chardata, innerxml, omitempty, cdata, comment, any, typeattr	Duplicate name detection, option validation
yaml	YAML serialization	omitempty, flow, inline	Duplicate name detection, option validation
bson	BSON (MongoDB)	omitempty, minsize, inline	Duplicate name detection, option validation
toml	TOML configuration	omitempty	Option validation
protobuf	Protocol Buffers	varint, bytes, fixed32, fixed64, zigzag32, zigzag64, req, opt, rep, name=, json	Duplicate number detection, mandatory name option
validate	Validation (go-playground/validator)	150+ validators like required, email, min, max, dive, keys, endkeys	Complex nested validation, alternative validators
datastore	Google Cloud Datastore	noindex, flatten, omitempty	Option validation
mapstructure	Map decoding	squash, reminder, omitempty	Option validation
url	URL encoding	comma, semicolon, space, brackets, numbered, omitempty, int	Delimiter conflict detection
properties	Properties file format	default=, layout=	Type matching, time.Time layout validation
spanner	Google Cloud Spanner	User-defined	Duplicate name detection
codec	Codec serialization	omitempty, toarray, int, uint, float, -, omitemptyarray	Special _struct field handling, redundancy detection
cbor	CBOR serialization	omitempty, omitzero, toarray, keyasint	Integer key validation, option conflict detection
asn1	ASN.1 encoding	explicit, optional, set, utf8, ia5, omitempty, tag:	Tag number validation, type matching for defaults
default	Default values	Value specification	Type matching validation
required	Required fields	true, false	Boolean value validation

Sources: rule/struct_tag.go24-64 rule/struct_tag.go823-1060

Configuration

Basic Configuration

Enable the rule in your revive.toml without arguments to use default validation:

Custom Tag Options

You can configure custom options for specific tag types by providing a list of comma-separated strings. Each argument specifies a tag key followed by custom options:

Omitting Tags from Validation

Prefix a tag key with ! to completely skip validation for that tag type:

Sources: rule/struct_tag.go100-132 test/struct_tag_test.go14-44

Architecture Overview

Sources: rule/struct_tag.go16-233 rule/struct_tag.go46-64

Validation Process Flow

Sources: rule/struct_tag.go167-232 rule/struct_tag.go66-98

Core Data Structures

StructTagRule

The main rule implementation that holds configuration:

StructTagRule {
    userDefined: map[tagKey][]string  // Custom options per tag type
    omittedTags: map[tagKey]struct{}  // Tags to skip validation
}

Sources: rule/struct_tag.go17-20

checkContext

Validation state maintained across all fields in a struct:

checkContext {
    userDefined:    map[tagKey][]string  // Custom options configuration
    usedTagNbr:     map[int]bool         // Tracks used tag numbers (protobuf, asn1, cbor)
    usedTagName:    map[string]bool      // Tracks used tag names (prevents duplicates)
    commonOptions:  map[string]bool      // Options set for all fields (codec _struct field)
    isAtLeastGo124: bool                 // Go version flag for omitzero support
}

Sources: rule/struct_tag.go66-98

lintStructTagRule

The AST visitor that walks struct definitions:

lintStructTagRule {
    onFailure:      func(lint.Failure)  // Callback to report failures
    userDefined:    map[tagKey][]string // From StructTagRule
    omittedTags:    map[tagKey]struct{} // From StructTagRule
    isAtLeastGo124: bool                // Go version detection
    tagCheckers:    map[tagKey]tagChecker // Validation function map
}

Sources: rule/struct_tag.go159-165

Tag-Specific Validation

JSON Tags (json)

Validates JSON serialization tags with these rules:

• Valid options: omitempty, string, omitzero (Go 1.24+)
• Special case: Tag name - with empty option (-,) is allowed
• Duplicate detection: Prevents multiple fields with same JSON name
• Version-specific: Rejects omitzero before Go 1.24

Example validations:

Sources: rule/struct_tag.go470-493 testdata/struct_tag.go7-31

Protobuf Tags (protobuf)

Validates Protocol Buffer tags with strict requirements:

• Valid tag names: bytes, fixed32, fixed64, group, varint, zigzag32, zigzag64
• Mandatory option: name=<field_name> must be present
• Valid options: json, opt, proto3, rep, req, name=
• Duplicate detection: Tag numbers and names must be unique
• Format: First element is type, second is number, rest are options

Example validations:

Sources: rule/struct_tag.go556-607 testdata/struct_tag.go117-133

Validate Tags (validate)

Validates go-playground/validator tags with 150+ validators:

• Single validators: required, email, min=, max=, alpha, numeric, etc.
• Compound validators: gt=, gte=, lt=, lte=, eq=, ne=, etc.
• Alternative validators: Use | for OR logic: eq=1|eq=2
• Nested validation: dive for slices/maps, keys/endkeys for map keys
• Validation rules:
  • keys must follow dive
  • endkeys must have preceding keys
  • Proper nesting of dive/keys/endkeys

Example validations:

Sources: rule/struct_tag.go656-683 rule/struct_tag.go747-768 rule/struct_tag.go823-1060

ASN.1 Tags (asn1)

Validates ASN.1 encoding tags:

• Simple options: application, explicit, generalized, ia5, omitempty, optional, set, utf8
• Compound options:
  • tag:<number> - Must be unique across struct
  • default:<value> - Type must match field type
• Type matching: Validates default values match field type (bool, int, float64, string)

Example validations:

Sources: rule/struct_tag.go305-345 testdata/struct_tag.go47-55

CBOR Tags (cbor)

Validates CBOR (Concise Binary Object Representation) tags:

• Options: omitempty, omitzero, toarray, keyasint
• Key rules:
  • keyasint requires integer tag name
  • Integer tag names require keyasint option
  • Tag names and integer keys must be unique
  • toarray makes omitempty/omitzero ignored
  • toarray requires empty tag name

Example validations:

Sources: rule/struct_tag.go385-443 testdata/struct_tag.go221-240

Codec Tags (codec)

Validates codec serialization tags with special _struct field handling:

• Options: omitempty, toarray, int, uint, float, -, omitemptyarray
• Special field _struct: Options set on _struct field apply to all fields
• Redundancy check: Warns if option is already set via _struct

Example validations:

Sources: rule/struct_tag.go445-468 testdata/struct_tag.go203-219

URL Tags (url)

Validates URL encoding tags:

• Options: omitempty, int, numbered, brackets
• Delimiters (mutually exclusive): comma, semicolon, space
• Time options: unix, unixmilli, unixnano
• Conflict detection: Cannot specify multiple delimiters

Example validations:

Sources: rule/struct_tag.go633-654 testdata/struct_tag.go135-146

Properties Tags (properties)

Validates Java properties file format tags:

• Options with values: default=<value>, layout=<format>
• Validation rules:
  • default value type must match field type
  • layout only valid for time.Time fields
  • Options must use = format (not :)
  • No duplicate options allowed

Example validations:

Sources: rule/struct_tag.go510-554 testdata/struct_tag.go179-193

Common Validation Checks

Duplicate Tag Name Detection

For tags that support duplicate detection (json, xml, yaml, bson, protobuf, spanner, codec, cbor), the rule tracks used tag names within each struct:

Implementation: The context maintains a map with key:name format to allow same names across different tag types.

Sources: rule/struct_tag.go260-288

Unexported Field Tag Detection

Tags on unexported fields are usually useless (except special cases like codec's _struct):

Sources: rule/struct_tag.go229-258

Useless Options on Ignored Fields

When a field has tag name - (ignored), options are typically useless:

Sources: rule/struct_tag.go725-745

Type Matching for Default Values

Tags that specify default values (default, asn1, properties) validate type compatibility:

Supported types: bool, int, float64, string

Sources: rule/struct_tag.go770-791

Integration with Go Version Detection

The rule adapts its validation based on the detected Go version:

This enables:

• Go 1.24+: Accept omitzero option in json tags
• Go < 1.24: Reject omitzero with error message

Sources: rule/struct_tag.go145 rule/struct_tag.go479-483

Error Messages

The rule generates specific, actionable error messages:

Error Pattern	Example
Unknown option	unknown option "inline" in json tag
Duplicated name	duplicated tag name "field" in json tag
Duplicated number	duplicated tag number 1 in protobuf tag
Type mismatch	type mismatch between field type and default value type in default tag
Missing mandatory	mandatory option "name" not found in protobuf tag
Useless option	useless option omitempty for ignored field in json tag
Tag on unexported	tag on not-exported field fieldName
Malformed tag	malformed tag (parsing error)

Sources: rule/struct_tag.go793-821

External Dependencies

The rule uses the github.com/fatih/structtag library for parsing struct tags:

structtag.Parse() -> *structtag.Tags
    Tags.Tags() -> []*structtag.Tag
        Tag.Key    (e.g., "json")
        Tag.Name   (e.g., "fieldName")
        Tag.Options (e.g., ["omitempty"])

Sources: go.mod9 rule/struct_tag.go10 rule/struct_tag.go194

Testing

The rule includes comprehensive test coverage with three test scenarios:

1. Basic validation: Default tag validation without configuration
2. Custom options: Validation with user-defined options
3. Omitted tags: Validation with certain tag types excluded
4. Go version-specific: Tests for Go 1.24+ features

Test files use inline MATCH comments to specify expected failures:

Sources: test/struct_tag_test.go10-48 testdata/struct_tag.go1-241