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

> Understand the schema structure for guideline entries in guidelines.json. Explore the Guideline struct's fields for IDs, version constraints, severity, and code examples.

- Repository: [JetBrains/go-modern-guidelines](https://github.com/jetbrains/go-modern-guidelines)
- Tags: api-reference
- Published: 2026-09-04

---

**The schema for guideline entries in [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) is defined by the `Guideline` struct in [`internal/guidelines/schema/schema.go`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/schema.go)) enforces strict integrity rules when unmarshaling [`guidelines.json`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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:

```json
{
  "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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/guidelines.json) according to the official schema, use the `schema.Parse` function:

```go
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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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`](https://github.com/JetBrains/go-modern-guidelines/blob/main/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.