Microsoft Active Directory · API Governance Rules
Microsoft Active Directory API Rules
Spectral linting rules defining API design standards and conventions for Microsoft Active Directory.
33 Rules
error 14
warn 15
info 4
Rule Categories
ad
Rules
error
ad-graph-server-url
Microsoft Graph APIs must use graph.microsoft.com as the server URL
$.servers[*].url
error
ad-https-only
All Microsoft Graph servers must use HTTPS
$.servers[*].url
error
ad-operation-summary-required
Every operation must have a non-empty summary
$.paths[*][get,post,patch,put,delete]
warn
ad-operation-summary-title-case
Operation summaries must use Title Case (each word capitalized)
$.paths[*][get,post,patch,put,delete].summary
warn
ad-operation-summary-prefix
Operation summaries must be prefixed with 'Active Directory'
$.paths[*][get,post,patch,put,delete].summary
warn
ad-operation-description-required
Every operation should have a detailed description
$.paths[*][get,post,patch,put,delete]
error
ad-operation-id-required
Every operation must have an operationId
$.paths[*][get,post,patch,put,delete]
warn
ad-operation-id-kebab-case
Operation IDs must use kebab-case
$.paths[*][get,post,patch,put,delete].operationId
warn
ad-operation-tags-required
Every operation must have at least one tag
$.paths[*][get,post,patch,put,delete]
warn
ad-tags-defined
All tags used in operations must be declared in the global tags list
$.paths[*][get,post,patch,put,delete].tags[*]
error
ad-oauth2-security-scheme
APIs must declare an OAuth2 security scheme
$.components.securitySchemes
error
ad-security-required
Every operation must declare security requirements
$.paths[*][get,post,patch,put,delete]
error
ad-get-200-response
GET operations must return a 200 response
$.paths[*].get
warn
ad-post-201-response
POST operations creating resources should return 201
$.paths[*].post
error
ad-delete-204-response
DELETE operations must return 204 No Content
$.paths[*].delete
warn
ad-patch-204-response
PATCH operations must return 204 No Content
$.paths[*].patch
warn
ad-401-response
All operations must define a 401 Unauthorized response
$.paths[*][get,post,patch,put,delete]
warn
ad-list-filter-param
List operations should support $filter OData parameter
$.paths[?([email protected](/{[^}]+}$/))].get
info
ad-list-top-param
List operations should support $top pagination parameter
$.paths[*].get.parameters[*]
error
ad-post-request-body
POST operations must define a request body
$.paths[*].post
error
ad-patch-request-body
PATCH operations must define a request body
$.paths[*].patch
error
ad-request-body-json
Request bodies must use application/json content type
$.paths[*][post,patch,put].requestBody.content
warn
ad-schema-id-uuid
ID properties should be documented as UUID format
$.components.schemas[*].properties.id
warn
ad-schemas-have-descriptions
All schemas must have descriptions
$.components.schemas[*]
info
ad-properties-have-descriptions
Schema properties should have descriptions
$.components.schemas[*].properties[*]
error
ad-path-lowercase
API paths must use lowercase letters
$.paths[*]~
error
ad-path-no-trailing-slash
API paths must not end with a trailing slash
$.paths[*]~
warn
ad-path-id-parameter
Path parameters for resource IDs should use descriptive names ending in 'Id'
$.paths[*][get,patch,delete].parameters[?(@.in=='path')].name
warn
ad-info-contact
API info must include a contact object
$.info
warn
ad-info-license
API info must include license information
$.info
info
ad-info-terms-of-service
API info should include terms of service URL
$.info
error
ad-response-json-content
Successful responses must include application/json content type
$.paths[*][get,post].responses[200,201].content
info
ad-microcks-operation
Operations should include x-microcks-operation for mock generation
$.paths[*][get,post,patch,put,delete]