Schema for API Style Guides

Google’s API style guide is described at https://aip.dev and can be applied to API designs using checks implemented in the open source api-linter. The correspondence between the text of the AIPs and the linter rules is largely implicit. For analysis and reporting, it is helpful to have a machine-readable representation, which we describe in style_guide.proto and represent externally in YAML.

This style guide representation has a two-level structure that matches the AIPs. The top level is a list of guidelines, each corresponding to a numbered AIP, and each guideline has an associated list of one or more rules that represent it. Alternate style guides can be written for different API styles and to represent different design priorities.

Style guides are stored in the registry as project-level artifacts and their descriptions include a list of mime types that indicate the design styles to which they apply. As an example, here is an excerpt from our style guide for Protocol Buffer-based APIs:

id: apihub-styleguide
kind: StyleGuide
mimeTypes:
    - application/x.protobuf+zip
guidelines:
    - id: aip122
      rules:
        - id: camel-case-uris
          description: All resource names must use camel case in collection identifiers.
          linter: api-linter
          linterRulename: core::0122::camel-case-uris
          severity: ERROR
          docUri: linter.aip.dev/122/camel-case-uris
        - id: name-suffix
          description: Fields should not use the suffix `_name`.
          linter: api-linter
          linterRulename: core::0122::name-suffix
          severity: ERROR
          docUri: linter.aip.dev/122/name-suffix
        - id: resource-collection-identifiers
          description: Resource patterns must use lowerCamelCase for collection identifiers.
          linter: api-linter
          linterRulename: core::0122::resource-collection-identifiers
          severity: ERROR
          docUri: linter.aip.dev/122/resource-collection-identifiers
        - id: resource-reference-type
          description: All resource references must be strings.
          linter: api-linter
          linterRulename: core::0122::resource-reference-type
          severity: ERROR
          docUri: linter.aip.dev/122/resource-reference-type
      state: ACTIVE

This section describes a guideline that has four rules, and each is checked with a rule in the API linter, which is described in a linters section in the styleguide:

linters:
    - name: api-linter
      uri: https://github.com/googleapis/api-linter