Palo Alto Networks · API Governance Rules

Palo Alto Networks API Rules

Spectral linting rules defining API design standards and conventions for Palo Alto Networks.

69 Rules error 16 warn 29 info 24
View Rules File View on GitHub

Rule Categories

components delete deprecated error external get info no openapi operation pagination parameter paths post put request response schema security server servers tag tags

Rules

error
info-title-required
Every API must have a title in the info object.
$.info
warn
info-title-prefix
Titles should start with "Palo Alto Networks" for portfolio consistency.
$.info.title
error
info-description-required
The info object must include a description explaining the API purpose.
$.info
warn
info-description-min-length
Info descriptions should be at least 50 characters to be meaningful.
$.info.description
error
info-version-required
A version string is required in the info object.
$.info
warn
info-contact-required
Contact information must be provided in the info object.
$.info
warn
info-contact-name
Contact should include a name field.
$.info.contact
warn
info-contact-url
Contact should include a URL (e.g. https://pan.dev/).
$.info.contact
warn
info-license-required
License information must be provided in the info object.
$.info
warn
openapi-version-3-1
APIs should use OpenAPI 3.1.0 or later.
$
error
servers-defined
At least one server must be defined.
$
error
server-url-https
Server URLs must use HTTPS.
$.servers[*].url
warn
server-description-required
Each server should have a description.
$.servers[*]
warn
paths-kebab-case
Path segments should use kebab-case (lowercase with hyphens), not camelCase, PascalCase, or snake_case.
$.paths
error
paths-no-trailing-slash
Paths must not end with a trailing slash.
$.paths
error
paths-no-query-string
Paths must not contain query strings — use parameters instead.
$.paths
info
paths-version-prefix
Paths should include a version prefix (e.g. /v1/, /v2/).
$.paths
info
paths-plural-resources
Resource collection paths should use plural nouns (e.g. /addresses not /address).
$.paths
error
operation-summary-required
Every operation must have a summary.
$.paths[*][get,post,put,patch,delete]
warn
operation-summary-prefix
Operation summaries should start with "Palo Alto Networks" for consistency.
$.paths[*][get,post,put,patch,delete].summary
warn
operation-summary-max-length
Operation summaries should be concise — under 80 characters.
$.paths[*][get,post,put,patch,delete].summary
warn
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]
warn
operation-operationid-camelcase
Operation IDs must use camelCase (e.g. listAddresses, getIncident).
$.paths[*][get,post,put,patch,delete].operationId
info
operation-operationid-verb-prefix
Operation IDs should start with a standard verb (get, list, create, update, delete, search, submit, start, stop, run, commit, isolate, scan, dismiss, reopen).
$.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-one-only
Operations should have exactly one tag for clean documentation grouping.
$.paths[*][get,post,put,patch,delete].tags
warn
tags-defined
Global tags array must be defined.
$
warn
tag-description-required
Each global tag should have a description.
$.tags[*]
info
tags-title-case
Tag names should use Title Case (e.g., "Network Security", "Cloud NGFW").
$.tags[*].name
info
tag-name-pascal-case
Tag names should use PascalCase or Title Case (e.g. Alerts, SecurityRules).
$.tags[*].name
warn
parameter-description-required
Every parameter must have a description.
$..parameters[*]
warn
parameter-name-snake-case
Parameter names should use snake_case for consistency.
$..parameters[*].name
error
parameter-query-no-api-key
API keys should be passed in headers, not query parameters.
$..parameters[?(@.in=='query')]
info
pagination-offset-name
Offset-based pagination should use "offset" as the parameter name.
$..parameters[?(@.in=='query')]
info
pagination-limit-name
Limit-based pagination should use "limit" as the parameter name.
$..parameters[?(@.in=='query')]
warn
request-body-json
Request bodies should support application/json.
$..requestBody.content
info
request-body-description
Request bodies should have a description.
$..requestBody
error
response-success-defined
Every operation must define at least one success response (2xx).
$.paths[*][get,post,put,patch,delete].responses
warn
response-error-401-defined
Operations with security should define a 401 Unauthorized response.
$.paths[*][get,post,put,patch,delete].responses
info
response-error-403-defined
Operations should define a 403 Forbidden response.
$.paths[*][get,post,put,patch,delete].responses
info
response-error-404-on-get
GET operations with path parameters should define a 404 Not Found response.
$.paths[*/{*}].get.responses
info
response-error-400-on-post
POST operations should define a 400 Bad Request response.
$.paths[*].post.responses
info
response-error-500-defined
Operations should define a 500 Internal Server Error response.
$.paths[*][get,post,put,patch,delete].responses
error
response-description-required
Every response must have a description.
$..responses[*]
warn
response-json-content
Success responses (except 204) should return application/json content.
$.paths[*][get,post,put,patch,delete].responses[200,201,202].content
warn
schema-property-snake-case
Schema properties should use snake_case for consistency across the portfolio.
$..properties
warn
schema-description-required
Top-level schemas in components should have a description.
$.components.schemas[*]
error
schema-property-type-defined
Schema properties must define a type or use a reference.
$..properties[*]
info
schema-id-property-name
Identifier properties should use "id" or be suffixed with "_id" (not "Id", "ID", or "identifier").
$..properties
info
schema-timestamp-property-name
Timestamp properties should use snake_case with standard suffixes (_at, _time, _timestamp).
$..properties
warn
security-defined-globally
A global security requirement should be defined.
$
error
security-schemes-defined
At least one security scheme must be defined in components.
$.components
warn
security-scheme-description
Security schemes should have a description explaining how to authenticate.
$.components.securitySchemes[*]
info
security-api-key-header-naming
API key header names should use X- prefix convention (e.g. X-PAN-KEY, X-API-KEY).
$.components.securitySchemes[?(@.type=='apiKey' && @.in=='header')]
info
components-schemas-defined
APIs should define reusable schemas in components.
$.components
info
error-response-has-message
Error responses (4xx, 5xx) should include a message or error field in the schema.
$.paths[*][get,post,put,patch,delete].responses[400,401,403,404,409,500].content.application/json.schema
error
no-empty-descriptions
Descriptions must not be empty strings.
$..description
info
no-x-headers-in-parameters
Custom headers in parameters should be moved to security schemes where possible.
$..parameters[?(@.in=='header')].name
warn
schema-no-additional-properties-false-alone
Schemas with additionalProperties false should also define properties.
$..schema[?(@.additionalProperties===false)]
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-required
POST operations should have a request body.
$.paths[*].post
info
put-request-body-required
PUT operations should have a request body.
$.paths[*].put
info
delete-response-204
DELETE operations should return 204 No Content on success.
$.paths[*].delete.responses
info
schema-examples-defined
Top-level request/response schemas should include examples.
$.paths[*][get,post,put,patch,delete]..content.application/json.schema
warn
deprecated-operations-documented
Deprecated operations must include a description explaining the deprecation.
$.paths[*][get,post,put,patch,delete][?(@.deprecated===true)]
info
external-docs-defined
APIs should link to external documentation (e.g. pan.dev).
$
warn
external-docs-url
External docs must include a URL.
$.externalDocs