AEP-0216 Linter Rules

States

This rule enforces that all lifecycle state enums are nested within their resource, as recommended in AEP-216.

Details

This rule iterates over enumerations and looks for enums with a name of FooState where a corresponding Foo message exists in the same file. If it finds such a case, it recommends that the enum be nested within the message.

Examples

Incorrect code for this rule:

// Incorrect.
message Book {
  BookState book_state = 1;
}

// Should be nested under `Book`.
enum BookState {
  BOOK_STATE_UNSPECIFIED = 0;
}

Correct code for this rule:

// Correct.
message Book {
  enum State {
    STATE_UNSPECIFIED = 0;
  }
  State state = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the enum. Remember to also include an aep.dev/not-precedent comment explaining why.

message Book {
  BookState book_state = 1;
}

// (-- api-linter: core::0216::nesting=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
enum BookState {
  BOOK_STATE_UNSPECIFIED = 0;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

States

This rule requires that all lifecycle state fields whose names end with State are marked as OUTPUT_ONLY, as mandated in AEP-216.

Details

This rule iterates over message fields that have an enum type, and the type name ends with State. Each field should have the annotation [(google.api.field_behavior) = OUTPUT_ONLY].

Note that the field name is ignored for the purposes of this rule.

Examples

Incorrect code for this rule:

// Incorrect.
enum State {  // Should be `State`.
  STATUS_UNSPECIFIED = 0;
}

State state = 1; // Should be marked OUTPUT_ONLY

// Incorrect.
enum BookState {
  BOOK_STATUS_UNSPECIFIED = 0;
  HARDCOVER = 1;
}

BookState state = 1; // Should be marked OUTPUT_ONLY

Correct code for this rule:

// Correct.
enum State {
  STATE_UNSPECIFIED = 0;
}

State state = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

Disabling

If you need to violate this rule, use a leading comment above the field Remember to also include an aep.dev/not-precedent comment explaining why.

enum BookState {
  UNSPECIFIED = 0;
}

// (-- api-linter: core::0216::state-field-output-only=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
BookState state = 1;

If you need to violate this rule for an entire file, place the comment at the top of the file.

States

This rule enforces that all lifecycle state enums are called State rather than Status, as mandated in AEP-216.

Details

This rule iterates over enumerations and looks for enums with a name of Status or ending in Status, and suggests the use of State instead.

Examples

Incorrect code for this rule:

// Incorrect.
enum Status {  // Should be `State`.
  STATUS_UNSPECIFIED = 0;
}

// Incorrect.
enum BookStatus {  // Should be `Book.State` or `BookState`.
  BOOK_STATUS_UNSPECIFIED = 0;
  HARDCOVER = 1;
}

Correct code for this rule:

// Correct.
enum State {
  STATE_UNSPECIFIED = 0;
}

Disabling

If you need to violate this rule, use a leading comment above the enum value. Remember to also include an aep.dev/not-precedent comment explaining why.

// (-- api-linter: core::0216::synonyms=disabled
//     aep.dev/not-precedent: We need to do this because reasons. --)
enum Status {
  STATUS_UNSPECIFIED = 0;
}

If you need to violate this rule for an entire file, place the comment at the top of the file.

Value synonyms

This rule enforces the use of state values enumerated in AEP-216 over common synonyms.

Details

This rule iterates over enumerations that end in State and looks for enum values that are common synonyms or alternate spellings of the states listed at the end of AEP-216, and suggests the use of the canonical value instead.

Examples

Incorrect code for this rule:

// Incorrect.
enum State {
  STATE_UNSPECIFIED = 0;
  SUCCESSFUL = 1;  // Should be `SUCCEEDED`.
}

Correct code for this rule:

// Correct.
enum State {
  STATE_UNSPECIFIED = 0;
  SUCCEEDED = 1;
}

Disabling

If you need to violate this rule, use a leading comment above the enum value. Remember to also include an aep.dev/not-precedent comment explaining why.

// Incorrect.
enum State {
  STATE_UNSPECIFIED = 0;
  // (-- api-linter: core::0216::value-synonyms=disabled
  //     aep.dev/not-precedent: We need to do this because reasons. --)
  SUCCESSFUL = 1;  // Should be `SUCCEEDED`.
}

If you need to violate this rule for an entire file, place the comment at the top of the file.