AEP-0191 Linter Rules

File layout

This rule attempts to enforce a consistent file layout for proto files, as mandated in AEP-191.

Details

This rule checks for common file layout mistakes, but does not currently check the exhaustive file layout in AEP-191. This rule currently complains if within a file:

…services appear below messages.
…top-level enums appear above messages.

Examples

Incorrect code for this rule:

// Incorrect.
// Services should appear before messages.
message Book {
  string path = 1;
}

service Library {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{path=publishers/*/books/*}"
    };
  }
}

message GetBookRequest {
  string path = 1;
}

Correct code for this rule:

// Correct.
service Library {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{path=publishers/*/books/*}"
    };
  }
}

message Book {
  string path = 1;
}

message GetBookRequest {
  string path = 1;
}

Disabling

If you need to violate this rule, use a comment at the top of the file. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0191::file-layout=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
syntax = "proto3";

import "google/api/anotations.proto";

message Book {
  string path = 1;
}

service Library {
  rpc GetBook(GetBookRequest) returns (Book) {
    option (google.api.http) = {
      get: "/v1/{path=publishers/*/books/*}"
    };
  }
}

message GetBookRequest {
  string path = 1;
}

Filenames

This rule attempts to enforce reasonable filenames for proto files, as mandated in AEP-191.

Details

Because proto filenames show up in client libraries (for example, as import paths), it is important not to have odd paths.

This rule currently complains if the filename:

…is set to the proto version.
…contains invalid cahracters.

Examples

Incorrect filenames for this rule:

v1.proto
v1beta1.proto
library.service.proto
library#.proto
library$.proto
library service.proto
library_Service.proto

Correct filenames for this rule:

library.proto
library_service.proto

Disabling

If you need to violate this rule, use a comment at the top of the file. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0191::filenames=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
syntax = "proto3";

Protobuf Package

This rule attempts to enforce that the proto package and the directory structure match, as mandated in AEP-191.

Details

Accordig to the Protobuf Style Guide, the package name must correspond to the directory structure.

This rule currently complains if the package and the directory structure do not correspond.

Examples

Incorrect directory structures and proto packages for this rule:

example/v1 example.library.v1
example/library/v1 example.librarian.v1

Correct directory structures and proto packages for this rule:

example/library/v1 example.library.v1
example/library/v1/types example.library.v1.types

Disabling

If you need to violate this rule, use a comment at the top of the file. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0191::proto-package=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
syntax = "proto3";

Proto3 syntax

This rule enforces that every proto file for a public API surface uses proto3, as mandated in AEP-191.

Details

This rule looks at each proto file, and complains if the syntax is set to proto2 (or missing, which means it defaults to proto2).

Examples

Incorrect code for this rule:

// Incorrect.
syntax = "proto2";  // Should be proto3.

Correct code for this rule:

// Correct.
syntax = "proto3";

Disabling

If you need to violate this rule, use a comment at the top of the file. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0191::proto-version=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
syntax = "proto2";