Schema Structure for Guideline Entries in guidelines.json: Complete Reference

The schema for guideline entries in guidelines.json is defined by the Guideline struct in internal/guidelines/schema/schema.go, enforcing fields for unique IDs, Go version constraints, severity levels, and paired before/after code examples.

The JetBrains/go-modern-guidelines repository stores its machine-readable Go best practices in internal/guidelines/guidelines.json. Understanding the precise schema structure for guideline entries is essential for contributors writing new rules and developers building tooling that consumes these recommendations.

Core Schema Definition in schema.go

The canonical schema for each guideline entry is declared in internal/guidelines/schema/schema.go. The primary Guideline struct defines eight required fields, while a nested Example struct standardizes code demonstrations.

Guideline Struct Fields

Each JSON object in the guidelines array must conform to these field specifications as implemented in schema.go:

• id (string): A unique identifier restricted to lower-case letters, digits, and underscores. Validated by the validID helper.
• since_version (string): The Go version (in major.minor format) from which the guideline applies. Validated using goversion.IsMajorMinor.
• modernizer (*bool): A pointer boolean indicating whether the guideline is handled by the automated modernizer tool. This field is mandatory and cannot be null.
• category (string): High-level grouping such as Naming, Concurrency, or Error Handling.
• impact (string): Severity classification restricted to Critical, High, Medium, or Low.
• guideline (string): The concise rule statement presented to users.
• details (string): Expanded explanation including rationale and external references.
• examples ([]Example): A non-empty array containing one or more code comparisons illustrating the refactoring.

Nested Example Structure

The Example struct (also defined in internal/guidelines/schema/schema.go) requires two string slices:

• before ([]string): Original code snippet that violates the guideline. Must be non-empty.
• after ([]string): Refactored code snippet that satisfies the guideline. Must be non-empty.

Each string in these arrays represents one line of code, allowing the JSON to store multi-line snippets in a readable array format rather than escaped strings.

Validation Logic in Parse

The Parse function (lines 30‑88 in schema.go) enforces strict integrity rules when unmarshaling guidelines.json:

1. Identifier Format: Validates id against validID regex constraints.
2. Version Format: Confirms since_version matches major.minor using goversion.IsMajorMinor.
3. Ordering Constraint: Ensures entries are sorted newest-first by Go version using goversion.Compare.
4. Required Fields: Verifies presence of modernizer, category, impact, guideline, details, and at least one example.
5. Example Integrity: Checks that every Example contains non-empty before and after slices.

These validations guarantee that the toolchain processing these guidelines receives consistent, machine-readable data structures.

Practical JSON Example

Below is a valid guideline entry demonstrating the schema structure:

{
  "id": "use_context_with_timeout",
  "since_version": "1.7",
  "modernizer": true,
  "category": "Concurrency",
  "impact": "High",
  "guideline": "Prefer context with timeout for long‑running operations",
  "details": "Using a cancellable context with an appropriate timeout prevents goroutine leaks and makes cancellation deterministic.",
  "examples": [
    {
      "before": [
        "func fetch(url string) ([]byte, error) {",
        "    resp, err := http.Get(url)",
        "    if err != nil { return nil, err }",
        "    defer resp.Body.Close()",
        "    return io.ReadAll(resp.Body)",
        "}"
      ],
      "after": [
        "func fetch(ctx context.Context, url string) ([]byte, error) {",
        "    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)",
        "    defer cancel()",
        "    req, _ := http.NewRequestWithContext(ctx, http.MethodGet, url, nil)",
        "    resp, err := http.DefaultClient.Do(req)",
        "    if err != nil { return nil, err }",
        "    defer resp.Body.Close()",
        "    return io.ReadAll(resp.Body)",
        "}"
      ]
    }
  ]
}

Loading Guidelines in Go

To parse guidelines.json according to the official schema, use the schema.Parse function:

import (
    "os"
    "github.com/JetBrains/go-modern-guidelines/internal/guidelines/schema"
)

func loadGuidelines() ([]schema.Guideline, error) {
    data, err := os.ReadFile("internal/guidelines/guidelines.json")
    if err != nil {
        return nil, err
    }
    return schema.Parse(data)
}

The internal/guidelines/guidelines.go file embeds the JSON file and exposes a public Load API that wraps this parsing logic, ensuring consumers always receive validated struct instances.

Summary

• The schema for guideline entries is defined by the Guideline and Example structs in internal/guidelines/schema/schema.go.
• Each entry requires eight fields: id, since_version, modernizer, category, impact, guideline, details, and examples.
• The modernizer field is a mandatory boolean pointer indicating automation support.
• Examples must contain non-empty before and after string arrays representing code snippets.
• The Parse function enforces validation including version formatting, ID constraints, and newest-first ordering.

Frequently Asked Questions

What is the purpose of the Modernizer field in the schema?

The modernizer field is a pointer boolean (*bool) that indicates whether the guideline can be automatically fixed by the project's modernizer tool. It must be explicitly set to true or false and cannot be null, allowing the toolchain to distinguish between manually-applied recommendations and automated refactorings.

How are guideline entries ordered in the guidelines.json file?

Entries must follow strict newest-first ordering by Go version. The Parse function validates this sequence using goversion.Compare, ensuring that guidelines targeting Go 1.21 appear before those for Go 1.20, maintaining a consistent logical flow for version-based tooling queries.

Can a single guideline entry contain multiple before/after examples?

Yes. The examples field is a slice ([]Example), allowing multiple code comparisons to illustrate different variations of the same guideline. However, each Example object must contain non-empty before and after arrays, and the parent guideline must include at least one example to pass validation.

What validation ensures the ID format is correct?

The validID function validates that the id field contains only lower-case letters, digits, and underscores. This constraint ensures machine-readable identifiers that work safely in JSON keys, filenames, and generated code across the JetBrains/go-modern-guidelines toolchain.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}