X (Twitter) · API Governance Rules

X (Twitter) API Rules

Spectral linting rules defining API design standards and conventions for X (Twitter).

53 Rules error 17 warn 18 info 18
View Rules File View on GitHub

Rule Categories

delete deprecated external get info no openapi operation parameter paths post 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 "X API" or "X [Name] API".
$.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.
$.info.description
error
info-version-required
API version must be specified.
$.info
warn
info-contact-required
Contact information should be provided.
$.info
info
info-license-required
License information 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-x-domain
Server URLs should use api.x.com or ads-api.x.com domains.
$.servers[*].url
warn
paths-version-prefix
Paths should start with a version prefix (e.g., /2/).
$.paths
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-snake-case
Path segments should use snake_case (the dominant X API convention).
$.paths
warn
paths-path-params-snake-case
Path parameters should use snake_case.
$.paths
warn
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,patch,delete]
error
operation-description-required
Every operation must have a description.
$.paths[*][get,post,put,patch,delete]
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-camelcase
Operation IDs should use camelCase with verb prefixes (e.g., getTweets, createPost, deleteUser).
$.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]
warn
tags-defined
Global tags array should be defined.
$
info
tags-title-case
Tag names should use Title Case (e.g., "Direct Messages", "Community Notes").
$.tags[*].name
error
parameter-description-required
All parameters must have a description.
$.paths[*][get,post,put,patch,delete].parameters[*]
warn
parameter-snake-case
Parameter names should use snake_case (the dominant X API convention).
$.paths[*][get,post,put,patch,delete].parameters[*]
error
parameter-schema-type
Parameters must have a schema with a type defined.
$.paths[*][get,post,put,patch,delete].parameters[*].schema
info
parameter-pagination-max-results
Pagination limit parameters should be named max_results.
$.paths[*].get.parameters[?(@.in=='query')]
info
parameter-pagination-token
Pagination cursor parameters should use next_token or pagination_token.
$.paths[*].get.parameters[?(@.in=='query')]
info
parameter-expansions
Expansion parameters should be named expansions for including related objects.
$.paths[*].get.parameters[?(@.in=='query')]
warn
request-body-json-content
Request bodies should use application/json content type.
$.paths[*][post,put,patch].requestBody.content
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[*]
info
response-default-error
Operations should define a default error response for unexpected errors.
$.paths[*][get,post,put,patch,delete].responses
warn
response-success-json
Success responses should use application/json content type.
$.paths[*][get,post,put,patch].responses.200.content
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 (the dominant X API convention).
$.components.schemas[*].properties
info
schema-description-top-level
Top-level schemas should have a description.
$.components.schemas[*]
warn
security-schemes-defined
Security schemes should be defined in components.
$.components
info
security-bearer-token
A BearerToken security scheme should be defined for app-only auth.
$.components.securitySchemes
info
security-oauth2-user
An OAuth2UserToken security scheme should be defined for user context auth.
$.components.securitySchemes
warn
security-operation-defined
Every operation should define its security requirements.
$.paths[*][get,post,put,patch,delete]
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
response-data-wrapper
Success responses should use a data wrapper object for consistency.
$.paths[*][get,post].responses.200.content.application/json.schema.properties
info
response-errors-array
Error responses should include an errors array.
$.components.schemas[?(@.properties.errors)]
info
parameter-fields-dot-notation
Field selection parameters should use dot notation (e.g., tweet.fields, user.fields, media.fields).
$.paths[*].get.parameters[?(@.name)]
error
no-empty-descriptions
Descriptions must not be empty strings.
$..description
info
external-docs-encouraged
External documentation link should be provided.
$
warn
deprecated-description
Deprecated operations should explain the deprecation in their description.
$.paths[*][get,post,put,patch,delete][?(@.deprecated==true)]

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 "X API" or "X [Name] API".
    severity: warn
    given: $.info.title
    then:
      function: pattern
      functionOptions:
        match: "^X "

  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.
    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-license-required:
    description: License information should be provided.
    severity: info
    given: $.info
    then:
      field: license
      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-x-domain:
    description: Server URLs should use api.x.com or ads-api.x.com domains.
    severity: info
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "(api\\.x\\.com|ads-api\\.x\\.com)"

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

  paths-version-prefix:
    description: Paths should start with a version prefix (e.g., /2/).
    severity: warn
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^\\/[0-9]"

  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-snake-case:
    description: Path segments should use snake_case (the dominant X API convention).
    severity: info
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "\\/[a-z]+[A-Z]"

  paths-path-params-snake-case:
    description: Path parameters should use snake_case.
    severity: warn
    given: $.paths
    then:
      field: "@key"
      function: pattern
      functionOptions:
        notMatch: "\\{[a-z]+[A-Z]"

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

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

  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-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-camelcase:
    description: Operation IDs should use camelCase with verb prefixes (e.g., getTweets, createPost, deleteUser).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].operationId
    then:
      function: pattern
      functionOptions:
        match: "^[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

  # ============================================================
  # 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., "Direct Messages", "Community Notes").
    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-snake-case:
    description: Parameter names should use snake_case (the dominant X API convention).
    severity: warn
    given: $.paths[*][get,post,put,patch,delete].parameters[*]
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^[a-z][a-z0-9_]*(\\.[a-z][a-z0-9_]*)*$"

  parameter-schema-type:
    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-max-results:
    description: Pagination limit parameters should be named max_results.
    severity: info
    given: $.paths[*].get.parameters[?(@.in=='query')]
    then:
      field: name
      function: pattern
      functionOptions:
        notMatch: "^(page_size|per_page|limit|count|size)$"

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

  parameter-expansions:
    description: Expansion parameters should be named expansions for including related objects.
    severity: info
    given: $.paths[*].get.parameters[?(@.in=='query')]
    then:
      field: name
      function: pattern
      functionOptions:
        notMatch: "^(expand|include|embed)$"

  # ============================================================
  # 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

  # ============================================================
  # 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: ["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-default-error:
    description: Operations should define a default error response for unexpected errors.
    severity: info
    given: $.paths[*][get,post,put,patch,delete].responses
    then:
      field: default
      function: truthy

  response-success-json:
    description: Success responses should use application/json content type.
    severity: warn
    given: $.paths[*][get,post,put,patch].responses.200.content
    then:
      field: application/json
      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 (the dominant X API convention).
    severity: info
    given: $.components.schemas[*].properties
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^[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

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

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

  security-bearer-token:
    description: A BearerToken security scheme should be defined for app-only auth.
    severity: info
    given: $.components.securitySchemes
    then:
      field: BearerToken
      function: truthy

  security-oauth2-user:
    description: An OAuth2UserToken security scheme should be defined for user context auth.
    severity: info
    given: $.components.securitySchemes
    then:
      field: OAuth2UserToken
      function: truthy

  security-operation-defined:
    description: Every operation should define its security requirements.
    severity: warn
    given: $.paths[*][get,post,put,patch,delete]
    then:
      field: security
      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

  # ============================================================
  # X API SPECIFIC PATTERNS
  # ============================================================

  response-data-wrapper:
    description: Success responses should use a data wrapper object for consistency.
    severity: info
    given: $.paths[*][get,post].responses.200.content.application/json.schema.properties
    then:
      field: data
      function: truthy

  response-errors-array:
    description: Error responses should include an errors array.
    severity: info
    given: $.components.schemas[?(@.properties.errors)]
    then:
      field: properties.errors
      function: truthy

  parameter-fields-dot-notation:
    description: Field selection parameters should use dot notation (e.g., tweet.fields, user.fields, media.fields).
    severity: info
    given: $.paths[*].get.parameters[?(@.name)]
    then:
      field: name
      function: pattern
      functionOptions:
        notMatch: "^(fields|select_fields|include_fields)$"

  # ============================================================
  # 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

  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"