Google Analytics · API Governance Rules

Google Analytics API Rules

Spectral linting rules defining API design standards and conventions for Google Analytics.

66 Rules error 18 warn 22 info 26
View Rules File View on GitHub

Rule Categories

delete deprecated external get info no openapi operation parameter patch paths post put request response schema security servers tags

Rules

error
info-title-required
API title must be present and non-empty.
$.info
warn
info-title-format
API title should follow the pattern "Google Analytics [Name]".
$.info.title
error
info-description-required
API description must be present and meaningful.
$.info
warn
info-description-min-length
API description should be at least 50 characters to be meaningful.
$.info.description
error
info-version-required
API version must be specified.
$.info
warn
info-contact-required
Contact information should be provided.
$.info
info
info-contact-name
Contact name should be provided.
$.info.contact
info
info-contact-url
Contact URL should be provided.
$.info.contact
warn
info-license-required
License information should be provided.
$.info
info
info-terms-of-service
Terms of service URL should be provided.
$.info
error
openapi-version-3
OpenAPI version must be 3.0.x.
$
error
servers-defined
At least one server must be defined.
$
error
servers-https-only
Server URLs must use HTTPS.
$.servers[*].url
info
servers-description
Server entries should have descriptions.
$.servers[*]
info
servers-google-domain
Server URLs should use googleapis.com or google-analytics.com domains.
$.servers[*].url
error
paths-no-trailing-slash
Paths must not have trailing slashes.
$.paths
error
paths-no-query-strings
Paths must not contain query strings.
$.paths
info
paths-version-prefix
Paths should include a version prefix (e.g., /v1beta/, /v1/, /v3/).
$.paths
info
paths-no-uppercase-in-segments
Path segments (excluding parameters and custom actions) should use lowercase.
$.paths
warn
paths-path-params-camelcase
Path parameters should use camelCase.
$.paths
error
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,patch,delete]
warn
operation-description-min-length
Operation descriptions should be at least 20 characters.
$.paths[*][get,post,put,patch,delete].description
error
operation-operationid-required
Every operation must have an operationId.
$.paths[*][get,post,put,patch,delete]
error
operation-operationid-unique
Operation IDs must be unique across the API.
$
warn
operation-operationid-format
Operation IDs should use dot-notation (service.resource.action) or camelCase.
$.paths[*][get,post,put,patch,delete].operationId
warn
operation-tags-required
Every operation must have at least one tag.
$.paths[*][get,post,put,patch,delete]
info
operation-tags-single
Operations should have exactly one tag for clean grouping.
$.paths[*][get,post,put,patch,delete].tags
warn
tags-defined
Global tags array should be defined.
$
info
tags-title-case
Tag names should use Title Case (e.g., "Account Summaries", "Data Streams").
$.tags[*].name
error
parameter-description-required
All parameters must have a description.
$.paths[*][get,post,put,patch,delete].parameters[*]
warn
parameter-query-camelcase
Query parameters should use camelCase.
$.paths[*][get,post,put,patch,delete].parameters[?(@.in=='query')]
warn
parameter-path-camelcase
Path parameters should use camelCase.
$.paths[*][get,post,put,patch,delete].parameters[?(@.in=='path')]
error
parameter-schema-type-required
Parameters must have a schema with a type defined.
$.paths[*][get,post,put,patch,delete].parameters[*].schema
info
parameter-pagination-page-size
Pagination limit parameters should be named pageSize.
$.paths[*].get.parameters[?(@.in=='query')]
info
parameter-pagination-page-token
Pagination cursor parameters should be named pageToken.
$.paths[*].get.parameters[?(@.in=='query')]
info
parameter-no-api-key-in-query
API keys should be passed in headers, not query parameters.
$.components.securitySchemes[?(@.type=='apiKey')]
warn
request-body-json-content
Request bodies should use application/json content type.
$.paths[*][post,put,patch].requestBody.content
info
request-body-description
Request bodies should have a description.
$.paths[*][post,put,patch].requestBody
error
response-success-required
Every operation must define a success response (2xx).
$.paths[*][get,post,put,patch,delete].responses
error
response-description-required
All responses must have a description.
$.paths[*][get,post,put,patch,delete].responses[*]
warn
response-success-json-content
Success responses with bodies should use application/json content type.
$.paths[*][get,post,put,patch].responses.200.content
warn
response-success-schema
Success responses with JSON content should have a schema defined.
$.paths[*][get,post,put,patch].responses.200.content.application/json
info
response-401-defined
Operations with security should define a 401 Unauthorized response.
$.paths[*][get,post,put,patch,delete][?(@.security)]
info
response-403-defined
Operations with security should define a 403 Forbidden response.
$.paths[*][get,post,put,patch,delete][?(@.security)]
info
response-400-for-post
POST operations should define a 400 Bad Request response.
$.paths[*].post.responses
warn
schema-names-pascalcase
Schema names should use PascalCase.
$.components.schemas
warn
schema-type-required
Schemas should have a type defined.
$.components.schemas[*]
info
schema-properties-snake-case
Schema properties should use snake_case or camelCase consistently.
$.components.schemas[*].properties
info
schema-description-top-level
Top-level schemas should have a description.
$.components.schemas[*]
info
schema-enum-uppercase
Enum values should use UPPER_CASE_WITH_UNDERSCORES.
$.components.schemas[*].properties[*].enum[*]
warn
security-global-defined
Global security should be defined or operations should have individual security.
$
warn
security-schemes-defined
Security schemes should be defined in components.
$.components
info
security-scheme-description
Security schemes should have descriptions.
$.components.securitySchemes[*]
error
security-oauth2-flows
OAuth2 security schemes should have properly defined flows.
$.components.securitySchemes[?(@.type=='oauth2')]
warn
security-oauth2-scopes
OAuth2 flows should define scopes.
$.components.securitySchemes[?(@.type=='oauth2')].flows[*]
error
get-no-request-body
GET operations must not have a request body.
$.paths[*].get
warn
delete-no-request-body
DELETE operations should not have a request body.
$.paths[*].delete
info
post-request-body
POST operations should have a request body.
$.paths[*].post
info
put-request-body
PUT operations should have a request body.
$.paths[*].put
info
patch-request-body
PATCH operations should have a request body.
$.paths[*].patch
error
no-empty-descriptions
Descriptions must not be empty strings.
$..description
info
external-docs-encouraged
External documentation link should be provided.
$
warn
external-docs-url
External documentation should have a URL.
$.externalDocs
warn
deprecated-description
Deprecated operations should explain the deprecation in their description.
$.paths[*][get,post,put,patch,delete][?(@.deprecated==true)]
info
schema-deprecated-description
Deprecated schema properties should explain the deprecation.
$.components.schemas[*].properties[?(@.deprecated==true)]
info
response-examples-encouraged
Success responses should include examples.
$.paths[*][get,post,put,patch].responses.200.content.application/json

Spectral Ruleset

Raw ↑ 
rules:

  # ============================================================
  # INFO / METADATA
  # ============================================================

  info-title-required:
    description: API title must be present and non-empty.
    severity: error
    given: $.info
    then:
      field: title
      function: truthy

  info-title-format:
    description: API title should follow the pattern "Google Analytics [Name]".
    severity: warn
    given: $.info.title
    then:
      function: pattern
      functionOptions:
        match: "^Google Analytics "

  info-description-required:
    description: API description must be present and meaningful.
    severity: error
    given: $.info
    then:
      field: description
      function: truthy

  info-description-min-length:
    description: API description should be at least 50 characters to be meaningful.
    severity: warn
    given: $.info.description
    then:
      function: length
      functionOptions:
        min: 50

  info-version-required:
    description: API version must be specified.
    severity: error
    given: $.info
    then:
      field: version
      function: truthy

  info-contact-required:
    description: Contact information should be provided.
    severity: warn
    given: $.info
    then:
      field: contact
      function: truthy

  info-contact-name:
    description: Contact name should be provided.
    severity: info
    given: $.info.contact
    then:
      field: name
      function: truthy

  info-contact-url:
    description: Contact URL should be provided.
    severity: info
    given: $.info.contact
    then:
      field: url
      function: truthy

  info-license-required:
    description: License information should be provided.
    severity: warn
    given: $.info
    then:
      field: license
      function: truthy

  info-terms-of-service:
    description: Terms of service URL should be provided.
    severity: info
    given: $.info
    then:
      field: termsOfService
      function: truthy

  # ============================================================
  # OPENAPI VERSION
  # ============================================================

  openapi-version-3:
    description: OpenAPI version must be 3.0.x.
    severity: error
    given: $
    then:
      field: openapi
      function: pattern
      functionOptions:
        match: "^3\\.0\\."

  # ============================================================
  # SERVERS
  # ============================================================

  servers-defined:
    description: At least one server must be defined.
    severity: error
    given: $
    then:
      field: servers
      function: truthy

  servers-https-only:
    description: Server URLs must use HTTPS.
    severity: error
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  servers-description:
    description: Server entries should have descriptions.
    severity: info
    given: $.servers[*]
    then:
      field: description
      function: truthy

  servers-google-domain:
    description: Server URLs should use googleapis.com or google-analytics.com domains.
    severity: info
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "(googleapis\\.com|google-analytics\\.com)"

  # ============================================================
  # PATHS — NAMING CONVENTIONS
  # ============================================================

  paths-no-trailing-slash:
    description: Paths must not have trailing slashes.
    severity: error
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "\\/$"

  paths-no-query-strings:
    description: Paths must not contain query strings.
    severity: error
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "\\?"

  paths-version-prefix:
    description: Paths should include a version prefix (e.g., /v1beta/, /v1/, /v3/).
    severity: info
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^\\/v[0-9]"

  paths-no-uppercase-in-segments:
    description: Path segments (excluding parameters and custom actions) should use lowercase.
    severity: info
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "\\/[A-Z][^\\/\\{:]*(\\/|$)"

  paths-path-params-camelcase:
    description: Path parameters should use camelCase.
    severity: warn
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "\\{[a-z]+_[a-z]"

  # ============================================================
  # OPERATIONS
  # ============================================================

  operation-description-required:
    description: Every operation must have a description.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: description
      function: truthy

  operation-description-min-length:
    description: Operation descriptions should be at least 20 characters.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].description
    then:
      function: length
      functionOptions:
        min: 20

  operation-operationid-required:
    description: Every operation must have an operationId.
    severity: error
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: operationId
      function: truthy

  operation-operationid-unique:
    description: Operation IDs must be unique across the API.
    severity: error
    given: $
    then:
      function: oasOpId

  operation-operationid-format:
    description: Operation IDs should use dot-notation (service.resource.action) or camelCase.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].operationId
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*(\\.[a-z][a-zA-Z0-9]*)*$"

  operation-tags-required:
    description: Every operation must have at least one tag.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: tags
      function: truthy

  operation-tags-single:
    description: Operations should have exactly one tag for clean grouping.
    severity: info
    given: $.paths[*][get,post,put,patch,delete].tags
    then:
      function: length
      functionOptions:
        max: 1

  # ============================================================
  # TAGS
  # ============================================================

  tags-defined:
    description: Global tags array should be defined.
    severity: warn
    given: $
    then:
      field: tags
      function: truthy

  tags-title-case:
    description: Tag names should use Title Case (e.g., "Account Summaries", "Data Streams").
    severity: info
    given: $.tags[*].name
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*(\\s[A-Za-z0-9]+)*$"

  # ============================================================
  # PARAMETERS
  # ============================================================

  parameter-description-required:
    description: All parameters must have a description.
    severity: error
    given: $.paths[*][get,post,put,patch,delete].parameters[*]
    then:
      field: description
      function: truthy

  parameter-query-camelcase:
    description: Query parameters should use camelCase.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.in=='query')]
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9_$.]*$"

  parameter-path-camelcase:
    description: Path parameters should use camelCase.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[?(@.in=='path')]
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  parameter-schema-type-required:
    description: Parameters must have a schema with a type defined.
    severity: error
    given: $.paths[*][get,post,put,patch,delete].parameters[*].schema
    then:
      field: type
      function: truthy

  parameter-pagination-page-size:
    description: Pagination limit parameters should be named pageSize.
    severity: info
    given: $.paths[*].get.parameters[?(@.in=='query')]
    then:
      field: name
      function: pattern
      functionOptions:
        notMatch: "^(page_size|per_page|limit|count|size)$"

  parameter-pagination-page-token:
    description: Pagination cursor parameters should be named pageToken.
    severity: info
    given: $.paths[*].get.parameters[?(@.in=='query')]
    then:
      field: name
      function: pattern
      functionOptions:
        notMatch: "^(page_token|cursor|next_token|continuation_token)$"

  parameter-no-api-key-in-query:
    description: API keys should be passed in headers, not query parameters.
    severity: info
    given: $.components.securitySchemes[?(@.type=='apiKey')]
    then:
      field: in
      function: pattern
      functionOptions:
        match: "header"

  # ============================================================
  # REQUEST BODIES
  # ============================================================

  request-body-json-content:
    description: Request bodies should use application/json content type.
    severity: warn
    given: $.paths[*][post,put,patch].requestBody.content
    then:
      field: application/json
      function: truthy

  request-body-description:
    description: Request bodies should have a description.
    severity: info
    given: $.paths[*][post,put,patch].requestBody
    then:
      field: description
      function: truthy

  # ============================================================
  # RESPONSES
  # ============================================================

  response-success-required:
    description: Every operation must define a success response (2xx).
    severity: error
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["200"]
            - required: ["201"]
            - required: ["202"]
            - required: ["204"]

  response-description-required:
    description: All responses must have a description.
    severity: error
    given: $.paths[*][get,post,put,patch,delete].responses[*]
    then:
      field: description
      function: truthy

  response-success-json-content:
    description: Success responses with bodies should use application/json content type.
    severity: warn
    given: $.paths[*][get,post,put,patch].responses.200.content
    then:
      field: application/json
      function: truthy

  response-success-schema:
    description: Success responses with JSON content should have a schema defined.
    severity: warn
    given: $.paths[*][get,post,put,patch].responses.200.content.application/json
    then:
      field: schema
      function: truthy

  response-401-defined:
    description: Operations with security should define a 401 Unauthorized response.
    severity: info
    given: $.paths[*][get,post,put,patch,delete][?(@.security)]
    then:
      field: responses.401
      function: truthy

  response-403-defined:
    description: Operations with security should define a 403 Forbidden response.
    severity: info
    given: $.paths[*][get,post,put,patch,delete][?(@.security)]
    then:
      field: responses.403
      function: truthy

  response-400-for-post:
    description: POST operations should define a 400 Bad Request response.
    severity: info
    given: $.paths[*].post.responses
    then:
      field: "400"
      function: truthy

  # ============================================================
  # SCHEMAS — PROPERTY NAMING
  # ============================================================

  schema-names-pascalcase:
    description: Schema names should use PascalCase.
    severity: warn
    given: $.components.schemas
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9]*$"

  schema-type-required:
    description: Schemas should have a type defined.
    severity: warn
    given: $.components.schemas[*]
    then:
      field: type
      function: truthy

  schema-properties-snake-case:
    description: Schema properties should use snake_case or camelCase consistently.
    severity: info
    given: $.components.schemas[*].properties
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9]*([A-Z][a-z0-9]*|_[a-z0-9]+)*$"

  schema-description-top-level:
    description: Top-level schemas should have a description.
    severity: info
    given: $.components.schemas[*]
    then:
      field: description
      function: truthy

  schema-enum-uppercase:
    description: Enum values should use UPPER_CASE_WITH_UNDERSCORES.
    severity: info
    given: $.components.schemas[*].properties[*].enum[*]
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][A-Z0-9_]*$"

  # ============================================================
  # SECURITY
  # ============================================================

  security-global-defined:
    description: Global security should be defined or operations should have individual security.
    severity: warn
    given: $
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["security"]
            - not:
                required: ["security"]

  security-schemes-defined:
    description: Security schemes should be defined in components.
    severity: warn
    given: $.components
    then:
      field: securitySchemes
      function: truthy

  security-scheme-description:
    description: Security schemes should have descriptions.
    severity: info
    given: $.components.securitySchemes[*]
    then:
      field: description
      function: truthy

  security-oauth2-flows:
    description: OAuth2 security schemes should have properly defined flows.
    severity: error
    given: $.components.securitySchemes[?(@.type=='oauth2')]
    then:
      field: flows
      function: truthy

  security-oauth2-scopes:
    description: OAuth2 flows should define scopes.
    severity: warn
    given: $.components.securitySchemes[?(@.type=='oauth2')].flows[*]
    then:
      field: scopes
      function: truthy

  # ============================================================
  # HTTP METHOD CONVENTIONS
  # ============================================================

  get-no-request-body:
    description: GET operations must not have a request body.
    severity: error
    given: $.paths[*].get
    then:
      field: requestBody
      function: falsy

  delete-no-request-body:
    description: DELETE operations should not have a request body.
    severity: warn
    given: $.paths[*].delete
    then:
      field: requestBody
      function: falsy

  post-request-body:
    description: POST operations should have a request body.
    severity: info
    given: $.paths[*].post
    then:
      field: requestBody
      function: truthy

  put-request-body:
    description: PUT operations should have a request body.
    severity: info
    given: $.paths[*].put
    then:
      field: requestBody
      function: truthy

  patch-request-body:
    description: PATCH operations should have a request body.
    severity: info
    given: $.paths[*].patch
    then:
      field: requestBody
      function: truthy

  # ============================================================
  # GENERAL QUALITY
  # ============================================================

  no-empty-descriptions:
    description: Descriptions must not be empty strings.
    severity: error
    given: "$..description"
    then:
      function: truthy

  external-docs-encouraged:
    description: External documentation link should be provided.
    severity: info
    given: $
    then:
      field: externalDocs
      function: truthy

  external-docs-url:
    description: External documentation should have a URL.
    severity: warn
    given: $.externalDocs
    then:
      field: url
      function: truthy

  deprecated-description:
    description: Deprecated operations should explain the deprecation in their description.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete][?(@.deprecated==true)]
    then:
      field: description
      function: pattern
      functionOptions:
        match: "[Dd]eprecated|[Ss]unset|[Rr]etired|[Rr]eplaced|[Mm]igrat"

  schema-deprecated-description:
    description: Deprecated schema properties should explain the deprecation.
    severity: info
    given: $.components.schemas[*].properties[?(@.deprecated==true)]
    then:
      field: description
      function: pattern
      functionOptions:
        match: "[Dd]eprecated|[Rr]eplaced|[Uu]se .* instead"

  response-examples-encouraged:
    description: Success responses should include examples.
    severity: info
    given: $.paths[*][get,post,put,patch].responses.200.content.application/json
    then:
      function: schema
      functionOptions:
        schema:
          anyOf:
            - required: ["example"]
            - required: ["examples"]
            - not:
                required: ["example"]