documentationUrl: https://spotlight-rules.com/spec/ functions: - baloise-assert-http-codes-for-operation - digitalocean-ensureAllArraysHaveItemTypes - digitalocean-ensureSchemaHasType - digitalocean-ensureSnakeCaseWithDigits - trimble-check-content-type-for-206-get-response-code - trimble-check-for-content-type-in-put-and-post-responses - trimble-check-for-path-parameter - trimble-check-for-query-parameter-in-every-path - trimble-check-for-response-in-every-request - trimble-check-if-application-or-json-in-put-and-post-response - trimble-check-if-response-body-json-in-get-response - trimble-check-standard-for-error-payload - trimble-delete-must-not-return-body - trimble-does-spec-contains-valid-http-verbs - trimble-invalid-symbol-in-path - trimble-no-http-verbs-in-path - trimble-operation-post-201-202-status-code - trimble-valid-http-response - trimble-valid-url-checker - trimble-valid-version-checker functionsDir: ./functions rules: openapi-component-example-keys-snake-case: title: Component Example Keys Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/component-example-keys-snake-case/ description: example key must be snake cased (e.g. snake_case). message: '{{error}}' severity: info given: $.components['examples'].*~ then: function: digitalocean-ensureSnakeCaseWithDigits tags: - format:openapi - spec:components - spec:examples - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''component-example-keys-snake-case'' (Component Example Keys Snake Case). Requirement: example key must be snake cased (e.g. snake_case). This rule is evaluated at the JSONPath `$.components[''examples''].*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-document-require-component-section: title: Document Require Component Section reference: https://spotlight-rules.com/spec/rules/openapi/document-require-component-section/ description: The API contract MUST include a 'components' section. message: '{{description}}: {{error}}' severity: info given: $ then: field: components function: truthy formats: - oas3 tags: - format:openapi - spec:document - experience:consistency - experience:governance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''document-require-component-section'' (Document Require Component Section). Requirement: The API contract MUST include a ''components'' section. To fix: Ensure `components` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-header-names-hyphenated-pascal-case: title: Header Names Hyphenated Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/header-names-hyphenated-pascal-case/ description: All `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation. message: '''HTTP'' headers MUST follow ''Hyphenated-Pascal-Case'' notation' severity: info given: $..parameters[?(@.in == 'header')].name then: function: pattern functionOptions: match: /^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/ tags: - format:openapi - spec:parameters - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''header-names-hyphenated-pascal-case'' (Header Names Hyphenated Pascal Case). Requirement: All `HTTP` headers MUST use `Hyphenated-Pascal-Case` notation. To fix: Ensure the targeted value matches the regular expression `/^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''header'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-header-no-x-prefix: title: Header No X Prefix reference: https://spotlight-rules.com/spec/rules/openapi/header-no-x-prefix/ description: '''HTTP'' headers SHOULD NOT start with ''X-'' RFC6648.' message: HTTP header '{{value}}' SHOULD NOT start with 'X-' in {{path}} severity: info given: - $..parameters[?(@.in == 'header')].name then: function: pattern functionOptions: match: /^([^x]|.[^-])|RateLimit-/i tags: - format:openapi - spec:parameters - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''header-no-x-prefix'' (Header No X Prefix). Requirement: ''HTTP'' headers SHOULD NOT start with ''X-'' RFC6648. To fix: Ensure the targeted value matches the regular expression `/^([^x]|.[^-])|RateLimit-/i`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''header'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-info-description-length-limit: title: Info Description Length Limit reference: https://spotlight-rules.com/spec/rules/openapi/info-description-length-limit/ description: Having a restriction on the length of the API description expressed as the OpenAPI info description helps provide constraints for consumers when adding a description, and keeps portals, landing pages, documentation, and discovery results more consistent. message: Info description MUST be less than 500 characters. severity: info given: $.info then: field: description function: length functionOptions: max: 500 tags: - format:openapi - spec:info - experience:documentation - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''info-description-length-limit'' (Info Description Length Limit). Requirement: Having a restriction on the length of the API description expressed as the OpenAPI info description helps provide constraints for consumers when adding a description, and keeps portals, landing pages, documentation, and discovery results more consistent. To fix: Ensure the length of `description` is at most 500. This rule is evaluated at the JSONPath `$.info` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-info-microcks-extension-valid: title: Info Microcks Extension Valid reference: https://spotlight-rules.com/spec/rules/openapi/info-microcks-extension-valid/ description: x-microcks extension must be valid. message: x-microcks extension must be valid severity: info given: $.info.x-microcks then: function: schema functionOptions: schema: type: object properties: labels: type: object additionalProperties: type: string required: - labels additionalProperties: false formats: - oas3 - aas2 - aas3 tags: - format:openapi - spec:info - experience:governance - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''info-microcks-extension-valid'' (Info Microcks Extension Valid). Requirement: x-microcks extension must be valid. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.info.x-microcks` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-info-title-capitalized: title: Info Title Capitalized reference: https://spotlight-rules.com/spec/rules/openapi/info-title-capitalized/ description: Having a consistent casing for the title for your API helps provide constraints for teams naming the API, but also keep consistent with other APIs from across teams. message: Info Title Has First Characters Capitalized severity: info given: $.info.title then: function: pattern functionOptions: match: '[A-Z]\w*' tags: - format:openapi - spec:info - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''info-title-capitalized'' (Info Title Capitalized). Requirement: Having a consistent casing for the title for your API helps provide constraints for teams naming the API, but also keep consistent with other APIs from across teams. To fix: Ensure the targeted value matches the regular expression `[A-Z]\w*`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.info.title` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-info-title-max-length: title: Info Title Max Length reference: https://spotlight-rules.com/spec/rules/openapi/info-title-max-length/ description: Having a limitation on the length of the title for your API helps provide constraints for teams naming it, but also keep consistent with other APIs from across teams. message: Info Title MUST Be Less Than 50 Characters severity: info given: $.info then: field: title function: length functionOptions: max: 50 tags: - format:openapi - spec:info - experience:consistency - experience:documentation prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''info-title-max-length'' (Info Title Max Length). Requirement: Having a limitation on the length of the title for your API helps provide constraints for teams naming it, but also keep consistent with other APIs from across teams. To fix: Ensure the length of `title` is at most 50. This rule is evaluated at the JSONPath `$.info` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-info-version-must-be-semver: title: Info Version Must Be Semver reference: https://spotlight-rules.com/spec/rules/openapi/info-version-must-be-semver/ description: The API version field should follow [semantic versioning](https://semver.org/#semantic-versioning-specification-semver). message: Specs should follow semantic versioning. {{value}} is not a valid version. severity: info given: $.info.version then: function: pattern functionOptions: match: ^[0-9]+.[0-9]+.[0-9]+(-[a-z0-9+.-]+)? tags: - format:openapi - spec:info - experience:versioning - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''info-version-must-be-semver'' (Info Version Must Be Semver). Requirement: The API version field should follow [semantic versioning](https://semver.org/#semantic-versioning-specification-semver). To fix: Ensure the targeted value matches the regular expression `^[0-9]+.[0-9]+.[0-9]+(-[a-z0-9+.-]+)?`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.info.version` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-info-version-must-use-semver: title: Info Version Must Use Semver reference: https://spotlight-rules.com/spec/rules/openapi/info-version-must-use-semver/ description: Version should use semantic versioning. {{value}} is not a valid version. message: Version should use semantic versioning. {{value}} is not a valid version. severity: info given: $.info.version then: function: pattern functionOptions: match: ^([0-9]+.[0-9]+.[0-9]+)$ tags: - format:openapi - spec:info - experience:versioning - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''info-version-must-use-semver'' (Info Version Must Use Semver). Requirement: Version should use semantic versioning. {{value}} is not a valid version. To fix: Ensure the targeted value matches the regular expression `^([0-9]+.[0-9]+.[0-9]+)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.info.version` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-info-version-semantic-and-stable: title: Info Version Semantic And Stable reference: https://spotlight-rules.com/spec/rules/openapi/info-version-semantic-and-stable/ description: The API contract MUST have a stable version and MUST follow semantic versioning (e.g., '1.0.0'). Words like 'SNAPSHOT' or 'RELEASE' are not allowed. message: '{{description}}: {{error}}' severity: info given: $.info.version then: function: pattern functionOptions: match: ^(?!.*\b(SNAPSHOT|RELEASE)\b)(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$ formats: - oas3 tags: - format:openapi - spec:info - experience:versioning - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''info-version-semantic-and-stable'' (Info Version Semantic And Stable). Requirement: The API contract MUST have a stable version and MUST follow semantic versioning (e.g., ''1.0.0''). Words like ''SNAPSHOT'' or ''RELEASE'' are not allowed. To fix: Ensure the targeted value matches the regular expression `^(?!.*\b(SNAPSHOT|RELEASE)\b)(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.info.version` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-limit-nested-sub-resources: title: Limit Nested Sub Resources reference: https://spotlight-rules.com/spec/rules/openapi/limit-nested-sub-resources/ description: The hierarchy of nested resources SHOULD NOT contain more than 8 resource names in the path. message: The hierarchy of nested resources SHOULD NOT contain more than 8 resource names in the path. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: ^([^/]*/){9,} tags: - format:openapi - spec:paths - experience:usability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''limit-nested-sub-resources'' (Limit Nested Sub Resources). Requirement: The hierarchy of nested resources SHOULD NOT contain more than 8 resource names in the path. To fix: Ensure the targeted value does NOT match the regular expression `^([^/]*/){9,}`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-limit-path-length: title: Limit Path Length reference: https://spotlight-rules.com/spec/rules/openapi/limit-path-length/ description: APIs SHOULD NOT expand their total URL length beyond a few hundred characters. message: APIs SHOULD NOT expand their total URL length beyond a few hundred characters. severity: info given: $.paths.*~ then: function: length functionOptions: max: 100 tags: - format:openapi - spec:paths - experience:usability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''limit-path-length'' (Limit Path Length). Requirement: APIs SHOULD NOT expand their total URL length beyond a few hundred characters. To fix: Ensure the length of the targeted value is at most 100. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-limit-path-parameter: title: Limit Path Parameter reference: https://spotlight-rules.com/spec/rules/openapi/limit-path-parameter/ description: The URL path should not contain more than 3 dynamic path parameters. message: The URL path should not contain more than 3 dynamic path parameters. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: ^(.*{{1}.*){4,} tags: - format:openapi - spec:paths - experience:usability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''limit-path-parameter'' (Limit Path Parameter). Requirement: The URL path should not contain more than 3 dynamic path parameters. To fix: Ensure the targeted value does NOT match the regular expression `^(.*{{1}.*){4,}`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-description-max-length: title: Operation Description Max Length reference: https://spotlight-rules.com/spec/rules/openapi/operation-description-max-length/ severity: info description: Having a length limitation for each description of each API operation helps apply constraints to how you describe your APIs, while helping drive consistency across APIs when it comes to search, documentation, and other ways an API is made available. message: Operation Description MUST Be Less Than 250 Characters given: $.paths.*[get,post,patch,put,delete] then: - field: description function: length functionOptions: max: 250 tags: - format:openapi - spec:paths - spec:operations - experience:documentation - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-description-max-length'' (Operation Description Max Length). Requirement: Having a length limitation for each description of each API operation helps apply constraints to how you describe your APIs, while helping drive consistency across APIs when it comes to search, documentation, and other ways an API is made available. To fix: Ensure the length of `description` is at most 250. This rule is evaluated at the JSONPath `$.paths.*[get,post,patch,put,delete]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-id-camel-case: title: Operation ID Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/operation-id-camel-case/ description: Operation identifiers provide a unique way to identify each individual API, and requiring them to have consistent casing reduces friction when generating SDKs and automating around APIs. message: Operation Identifier MUST Be camelCase severity: info given: $.paths.*[get,post,patch,put,delete].operationId then: - function: pattern functionOptions: match: ^[a-z]+(?:[A-Z][a-z]+)*$ tags: - format:openapi - spec:paths - spec:operations - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-id-camel-case'' (Operation ID Camel Case). Requirement: Operation identifiers provide a unique way to identify each individual API, and requiring them to have consistent casing reduces friction when generating SDKs and automating around APIs. To fix: Ensure the targeted value matches the regular expression `^[a-z]+(?:[A-Z][a-z]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths.*[get,post,patch,put,delete].operationId` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-id-url-safe: title: Operation ID URL Safe reference: https://spotlight-rules.com/spec/rules/openapi/operation-id-url-safe/ description: OperationId must use URL friendly characters. message: OperationId must use URL friendly characters. severity: info given: $.paths[*][*] then: field: operationId function: pattern functionOptions: match: ^[A-Za-z0-9-._~:/?#\[\]@!\$&'()*+,;=]*$ formats: - oas3 - oas3_1 tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-id-url-safe'' (Operation ID URL Safe). Requirement: OperationId must use URL friendly characters. To fix: Ensure `operationId` matches the regular expression `^[A-Za-z0-9-._~:/?#\[\]@!\$&''()*+,;=]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[*][*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-microcks-extension-valid: title: Operation Microcks Extension Valid reference: https://spotlight-rules.com/spec/rules/openapi/operation-microcks-extension-valid/ description: x-microcks-operation extension must be valid. message: x-microcks-operation extension must be valid severity: info given: - $.paths.*.*.x-microcks-operation - $.channels.*.[publish,subscribe].x-microcks-operation - $.operations.*.x-microcks-operation then: function: schema functionOptions: schema: type: object properties: delay: type: number format: int32 frequency: type: number format: int32 dispatcher: type: string dispatcherRules: type: string parameterConstraints: type: array items: type: object properties: name: type: string in: type: string enum: - path - query - header required: type: boolean recopy: type: boolean mustMatchRegexp: type: string required: - name - in additionalProperties: false formats: - oas3 - aas2 - aas3 tags: - format:openapi - spec:channels - spec:paths - experience:governance - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-microcks-extension-valid'' (Operation Microcks Extension Valid). Requirement: x-microcks-operation extension must be valid. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths.*.*.x-microcks-operation | $.channels.*.[publish,subscribe].x-microcks-operation | $.operations.*.x-microcks-operation` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-mutation-support-idempotency-key: title: Operation Mutation Support Idempotency Key reference: https://spotlight-rules.com/spec/rules/openapi/operation-mutation-support-idempotency-key/ description: POST and PATCH operations should accept an Idempotency-Key request header so clients can safely retry without creating duplicates. message: Mutation should accept an Idempotency-Key header for safe retries. given: $.paths[*][post,patch] severity: info then: field: parameters function: schema functionOptions: schema: type: array contains: type: object required: - name - in properties: name: const: Idempotency-Key in: const: header tags: - format:openapi - spec:parameters - topic:idempotency - experience:reliability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-mutation-support-idempotency-key'' (Operation Mutation Support Idempotency Key). Requirement: POST and PATCH operations should accept an Idempotency-Key request header so clients can safely retry without creating duplicates. To fix: Adjust `parameters` so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths[*][post,patch]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-patch-must-have-request-body: title: Operation Patch Must Have Request Body reference: https://spotlight-rules.com/spec/rules/openapi/operation-patch-must-have-request-body/ description: PATCH operations must have a request body. message: PATCH operations must have a request body. severity: info given: $.paths[*].patch then: field: requestBody function: schema functionOptions: schema: type: object tags: - format:openapi - spec:paths - spec:operations - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-patch-must-have-request-body'' (Operation Patch Must Have Request Body). Requirement: PATCH operations must have a request body. To fix: Adjust `requestBody` so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths[*].patch` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-post-not-for-retrieval: title: Operation Post Not For Retrieval reference: https://spotlight-rules.com/spec/rules/openapi/operation-post-not-for-retrieval/ description: POST requests SHOULD NOT be used for retrieving information. Use GET instead. message: POST requests SHOULD NOT be used for retrieving information. severity: info given: $.paths[*].post then: field: summary function: pattern functionOptions: notMatch: (retrieve|fetch|get|read) message: '{{description}}: {{error}}' formats: - oas3 tags: - format:openapi - spec:paths - spec:operations - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-post-not-for-retrieval'' (Operation Post Not For Retrieval). Requirement: POST requests SHOULD NOT be used for retrieving information. Use GET instead. To fix: Ensure `summary` does NOT match the regular expression `(retrieve|fetch|get|read)`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].post` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-post-require-request-body: title: Operation Post Require Request Body reference: https://spotlight-rules.com/spec/rules/openapi/operation-post-require-request-body/ description: POST HTTP methods can have a request body, providing a structured payload for configuring each API request. message: POST Requests MUST Have a Body severity: info given: $.paths.*.post then: field: requestBody function: truthy tags: - format:openapi - spec:paths - spec:operations - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-post-require-request-body'' (Operation Post Require Request Body). Requirement: POST HTTP methods can have a request body, providing a structured payload for configuring each API request. To fix: Ensure `requestBody` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*.post` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-put-require-request-body: title: Operation Put Require Request Body reference: https://spotlight-rules.com/spec/rules/openapi/operation-put-require-request-body/ description: PUT requests MUST have a request body. message: PUT requests MUST have a request body. severity: info given: $.paths[*].put then: field: requestBody function: truthy message: '{{description}}: {{error}}' formats: - oas3 tags: - format:openapi - spec:paths - spec:operations - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-put-require-request-body'' (Operation Put Require Request Body). Requirement: PUT requests MUST have a request body. To fix: Ensure `requestBody` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths[*].put` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-ref-resource-file: title: Operation Ref Resource File reference: https://spotlight-rules.com/spec/rules/openapi/operation-ref-resource-file/ description: Endpoint must a $ref to a file in resources/. message: '{{description}}; {{value}} incorrect' severity: info given: $.paths.*.$ref then: function: pattern functionOptions: match: ^resources/.*yml$ tags: - format:openapi - spec:paths - experience:consistency - experience:governance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-ref-resource-file'' (Operation Ref Resource File). Requirement: Endpoint must a $ref to a file in resources/. To fix: Ensure the targeted value matches the regular expression `^resources/.*yml$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths.*.$ref` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-require-id: title: Operation Require ID reference: https://spotlight-rules.com/spec/rules/openapi/operation-require-id/ description: Every operation should have an operationId for SDK generation and documentation linking. Analysis shows operationId styles across 8878 operations with camelCase dominant at 92%. message: Operation MUST Have operationId severity: info given: $.paths.*[get,post,put,patch,delete] then: field: operationId function: truthy tags: - format:openapi - spec:paths - spec:operations - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-require-id'' (Operation Require ID). Requirement: Every operation should have an operationId for SDK generation and documentation linking. Analysis shows operationId styles across 8878 operations with camelCase dominant at 92%. To fix: Ensure `operationId` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*[get,post,put,patch,delete]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-require-identifier: title: Operation Require Identifier reference: https://spotlight-rules.com/spec/rules/openapi/operation-require-identifier/ description: Operation identifiers provide a unique way to identify each individual API, which then used for SDK generation and other automation. message: Operation MUST Have Identifier severity: info given: $.paths.*[get,post,patch,put,delete] then: - field: operationId function: truthy tags: - format:openapi - spec:paths - spec:operations - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-require-identifier'' (Operation Require Identifier). Requirement: Operation identifiers provide a unique way to identify each individual API, which then used for SDK generation and other automation. To fix: Ensure `operationId` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*[get,post,patch,put,delete]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-require-one-tag: title: Operation Require One Tag reference: https://spotlight-rules.com/spec/rules/openapi/operation-require-one-tag/ description: Having tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available. message: MUST Be At Least One Operation Tag severity: info given: $.paths.*[get,post,patch,put,delete] then: field: tags function: length functionOptions: min: 1 tags: - format:openapi - spec:paths - spec:operations - experience:discoverability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-require-one-tag'' (Operation Require One Tag). Requirement: Having tags applied to each API operations helps organize and group APIs in portals, documentation, search, and other ways in which APIs are made available. To fix: Ensure the length of `tags` is at least 1. This rule is evaluated at the JSONPath `$.paths.*[get,post,patch,put,delete]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-require-response: title: Operation Require Response reference: https://spotlight-rules.com/spec/rules/openapi/operation-require-response/ description: Check if every request has their respective responses. message: '{{error}}' severity: info given: $.paths.* then: function: trimble-check-for-response-in-every-request tags: - format:openapi - spec:paths - experience:documentation - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-require-response'' (Operation Require Response). Requirement: Check if every request has their respective responses. This rule is evaluated at the JSONPath `$.paths.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-security-use-defined-scheme: title: Operation Security Use Defined Scheme reference: https://spotlight-rules.com/spec/rules/openapi/operation-security-use-defined-scheme/ description: Check operation security uses a defined security scheme. message: Check operation security uses a defined security scheme. severity: info given: $.paths[*][*]..security.* then: function: schema functionOptions: schema: anyOf: - required: - bearer_auth - required: - inference_bearer_auth tags: - owasp:api5 - format:openapi - spec:security - spec:paths - experience:security - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-security-use-defined-scheme'' (Operation Security Use Defined Scheme). Requirement: Check operation security uses a defined security scheme. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths[*][*]..security.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-summary-max-length: title: Operation Summary Max Length reference: https://spotlight-rules.com/spec/rules/openapi/operation-summary-max-length/ severity: info description: Apply length constraints to the operation summary helps keep them consistent for publishing in documentation. message: Operation Summary MUST Be Less Than 50 Characters given: $.paths.*[get,post,patch,put,delete] then: - field: summary function: length functionOptions: max: 50 tags: - format:openapi - spec:paths - spec:operations - experience:documentation - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-summary-max-length'' (Operation Summary Max Length). Requirement: Apply length constraints to the operation summary helps keep them consistent for publishing in documentation. To fix: Ensure the length of `summary` is at most 50. This rule is evaluated at the JSONPath `$.paths.*[get,post,patch,put,delete]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-summary-no-period: title: Operation Summary No Period reference: https://spotlight-rules.com/spec/rules/openapi/operation-summary-no-period/ description: Operation summaries should not have a period, keeping the primary summary for each API as consistent as possible for publishing in documentation. message: Operation MUST Not Have a Period. severity: info given: $.paths[*][*].summary then: function: pattern functionOptions: notMatch: \.$ tags: - format:openapi - spec:paths - experience:consistency - experience:documentation prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-summary-no-period'' (Operation Summary No Period). Requirement: Operation summaries should not have a period, keeping the primary summary for each API as consistent as possible for publishing in documentation. To fix: Ensure the targeted value does NOT match the regular expression `\.$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*][*].summary` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-tag-title-case: title: Operation Tag Title Case reference: https://spotlight-rules.com/spec/rules/openapi/operation-tag-title-case/ description: Having the first letter of each word applied as a tag to API operations helps keep a consistent layout when published via search, documentation, and other ways APIs are made available. message: Operation Tag Names MUST Have First Letter in Each Word Capitalized severity: info given: $.paths.*[get,post,patch,put,delete].tags.* then: function: pattern functionOptions: match: '[A-Z]\w*' tags: - format:openapi - spec:paths - spec:operations - spec:tags - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-tag-title-case'' (Operation Tag Title Case). Requirement: Having the first letter of each word applied as a tag to API operations helps keep a consistent layout when published via search, documentation, and other ways APIs are made available. To fix: Ensure the targeted value matches the regular expression `[A-Z]\w*`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths.*[get,post,patch,put,delete].tags.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-use-ref: title: Operation Use Ref reference: https://spotlight-rules.com/spec/rules/openapi/operation-use-ref/ description: Endpoint must be a $ref. message: '{{description}}; {{property}} incorrect' severity: info given: $.paths.*.* then: field: $ref function: truthy tags: - format:openapi - spec:paths - experience:consistency - experience:governance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-use-ref'' (Operation Use Ref). Requirement: Endpoint must be a $ref. To fix: Ensure `$ref` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-operation-well-understood-status-codes: title: Operation Well Understood Status Codes reference: https://spotlight-rules.com/spec/rules/openapi/operation-well-understood-status-codes/ description: MUST use standard HTTP status codes [150]. message: '{{error}}' severity: info given: $.paths.* then: function: baloise-assert-http-codes-for-operation functionOptions: wellUnderstood: '200': - ALL '201': - POST - PUT '202': - POST - PUT - DELETE - PATCH '204': - PUT - DELETE - PATCH '207': - POST '301': - ALL '303': - PATCH - POST - PUT - DELETE '304': - GET - HEAD '400': - ALL '401': - ALL '403': - ALL '404': - ALL '405': - ALL '406': - ALL '408': - ALL '409': - POST - PUT - DELETE - PATCH '410': - ALL '412': - PUT - DELETE - PATCH '415': - POST - PUT - DELETE - PATCH '422': - ALL '423': - PUT - DELETE - PATCH '428': - ALL '429': - ALL '500': - ALL '501': - ALL '503': - ALL default: - ALL tags: - format:openapi - spec:paths - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''operation-well-understood-status-codes'' (Operation Well Understood Status Codes). Requirement: MUST use standard HTTP status codes [150]. This rule is evaluated at the JSONPath `$.paths.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-array-require-items: title: Parameter Array Require Items reference: https://spotlight-rules.com/spec/rules/openapi/parameter-array-require-items/ description: Parameters that are of an array type should always have the items defined, being explicit about what is continued as part of the array. message: Parameter Schema Array MUST Have Items severity: info given: $.components.parameters.schema[?(@.type=='array')] then: field: items function: truthy tags: - format:openapi - spec:parameters - spec:schemas - spec:components - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-array-require-items'' (Parameter Array Require Items). Requirement: Parameters that are of an array type should always have the items defined, being explicit about what is continued as part of the array. To fix: Ensure `items` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.components.parameters.schema[?(@.type==''array'')]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-array-typed-items: title: Parameter Array Typed Items reference: https://spotlight-rules.com/spec/rules/openapi/parameter-array-typed-items/ description: Array parameters must have an items attribute with a type. message: '{{error}}' severity: info given: $..*.parameters[*] then: function: digitalocean-ensureAllArraysHaveItemTypes tags: - format:openapi - spec:parameters - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-array-typed-items'' (Parameter Array Typed Items). Requirement: Array parameters must have an items attribute with a type. This rule is evaluated at the JSONPath `$..*.parameters[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-description-max-length: title: Parameter Description Max Length reference: https://spotlight-rules.com/spec/rules/openapi/parameter-description-max-length/ severity: info description: Limiting the length of parameters description forces us to be more concise in how we describe each parameter, while keeping our documentation and other ways descriptions show up in discovery and portals more consistent. message: Parameters Description MUST Be Less Than 500 Characters given: $.components.parameters.* then: field: summary function: length functionOptions: max: 500 tags: - format:openapi - spec:parameters - spec:components - experience:documentation - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-description-max-length'' (Parameter Description Max Length). Requirement: Limiting the length of parameters description forces us to be more concise in how we describe each parameter, while keeping our documentation and other ways descriptions show up in discovery and portals more consistent. To fix: Ensure the length of `summary` is at most 500. This rule is evaluated at the JSONPath `$.components.parameters.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-enum-upper-snake-case: title: Parameter Enum Upper Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/parameter-enum-upper-snake-case/ description: Keeping parameters enumerator casing consistent across APIs helps reduce confusion by consumers, and can keep aligned with services and applications putting an API to work. message: Parameters Enums MUST Must Be Upper Snake Case severity: info given: $.components.parameters.*.enum.* then: function: pattern functionOptions: notMatch: ^[A-Z]+(?:_[A-Z]+)*$ tags: - format:openapi - spec:parameters - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-enum-upper-snake-case'' (Parameter Enum Upper Snake Case). Requirement: Keeping parameters enumerator casing consistent across APIs helps reduce confusion by consumers, and can keep aligned with services and applications putting an API to work. To fix: Ensure the targeted value does NOT match the regular expression `^[A-Z]+(?:_[A-Z]+)*$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.components.parameters.*.enum.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-filter-param-only-on-get: title: Parameter Filter Param Only On Get reference: https://spotlight-rules.com/spec/rules/openapi/parameter-filter-param-only-on-get/ description: Only GET-based endpoints SHOULD have have the query parameter 'filter'. message: Only GET-based endpoints SHOULD have have the query parameter 'filter'. severity: info given: $.paths.*[?(@property!='get')].parameters.[?(@.in=='query' && @.name=='filter')].name then: function: falsy tags: - format:openapi - spec:paths - spec:operations - spec:parameters - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-filter-param-only-on-get'' (Parameter Filter Param Only On Get). Requirement: Only GET-based endpoints SHOULD have have the query parameter ''filter''. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.*[?(@property!=''get'')].parameters.[?(@.in==''query'' && @.name==''filter'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-keys-snake-case: title: Parameter Keys Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/parameter-keys-snake-case/ description: parameter key must be snake cased (e.g. snake_case). message: '{{error}}' severity: info given: $.components['parameters'].*~ then: function: digitalocean-ensureSnakeCaseWithDigits tags: - format:openapi - spec:parameters - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-keys-snake-case'' (Parameter Keys Snake Case). Requirement: parameter key must be snake cased (e.g. snake_case). This rule is evaluated at the JSONPath `$.components[''parameters''].*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-name-max-length: title: Parameter Name Max Length reference: https://spotlight-rules.com/spec/rules/openapi/parameter-name-max-length/ severity: info description: Providing short and concise names for your parameters helps make it easier for API consumers to understand how they are able to configure their API requests. message: Parameters Name Length MUST Be Less Than 25 Characters given: $.components.parameters[?(@.in=='path')].name then: field: summary function: length functionOptions: max: 25 tags: - format:openapi - spec:parameters - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-name-max-length'' (Parameter Name Max Length). Requirement: Providing short and concise names for your parameters helps make it easier for API consumers to understand how they are able to configure their API requests. To fix: Ensure the length of `summary` is at most 25. This rule is evaluated at the JSONPath `$.components.parameters[?(@.in==''path'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-names-camel-case: title: Parameter Names Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/parameter-names-camel-case/ description: Providing parameters with consistent naming helps make it easier for API consumers to understand how they are able to configure their API requests. message: Parameters Names MUST Be Camel Case severity: info given: $.components.parameters.* then: - field: name function: pattern functionOptions: notMatch: ^[a-z]+(?:[A-Z][a-z]+)*$ - field: name function: pattern functionOptions: match: ^[A-Z](([a-z0-9]+[A-Z]?)*)$ tags: - format:openapi - spec:parameters - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-names-camel-case'' (Parameter Names Camel Case). Requirement: Providing parameters with consistent naming helps make it easier for API consumers to understand how they are able to configure their API requests. To fix: Ensure `name` does NOT match the regular expression `^[a-z]+(?:[A-Z][a-z]+)*$`; rename or rewrite any value that does. Also: Ensure `name` matches the regular expression `^[A-Z](([a-z0-9]+[A-Z]?)*)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.components.parameters.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-no-forbidden-http-header: title: Parameter No Forbidden HTTP Header reference: https://spotlight-rules.com/spec/rules/openapi/parameter-no-forbidden-http-header/ description: 'OAS do not allow using the following HTTP headers in a specification file: Authorization, Content-Type and Accept. You MUST use the associate functionalities provided by OAS, instead.' message: '{{error}} in {{path}} {{value}}' severity: info given: - $..parameters[?(@.in == 'header')].name - $.[responses][*].headers.*~ then: function: pattern functionOptions: notMatch: /^(accept|content-type|authorization)$/i tags: - format:openapi - spec:parameters - spec:responses - spec:headers - experience:consistency - experience:governance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-no-forbidden-http-header'' (Parameter No Forbidden HTTP Header). Requirement: OAS do not allow using the following HTTP headers in a specification file: Authorization, Content-Type and Accept. You MUST use the associate functionalities provided by OAS, instead. To fix: Ensure the targeted value does NOT match the regular expression `/^(accept|content-type|authorization)$/i`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''header'')].name | $.[responses][*].headers.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-no-hybrid-and-root-filtering: title: Parameter No Hybrid And Root Filtering reference: https://spotlight-rules.com/spec/rules/openapi/parameter-no-hybrid-and-root-filtering/ description: Hybrid filtering MAY be offered on multiple attributes, but MUST never exist if a root "filter" query parameter is present. message: Hybrid filtering MAY be offered on multiple attributes, but MUST never exist if a root "filter" query parameter is present. severity: info given: $.paths..get.parameters^ then: function: schema functionOptions: schema: type: object properties: parameters: type: array items: type: object properties: name: type: string in: type: string allOf: - if: properties: parameters: type: array contains: type: object properties: name: const: filter then: not: properties: parameters: type: array contains: type: object properties: name: type: string pattern: \w+Filter tags: - format:openapi - spec:paths - spec:operations - spec:parameters - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-no-hybrid-and-root-filtering'' (Parameter No Hybrid And Root Filtering). Requirement: Hybrid filtering MAY be offered on multiple attributes, but MUST never exist if a root "filter" query parameter is present. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths..get.parameters^` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-no-id-query: title: Parameter No ID Query reference: https://spotlight-rules.com/spec/rules/openapi/parameter-no-id-query/ description: Resource identifier filtering is not allowed as a query parameter. Use the resource identifier in the URL path. message: Resource identifier filtering is not allowed as a query parameter. severity: info given: $.paths..get.parameters.[?(@.in=='query' && @.name=='id')] then: field: name function: pattern functionOptions: notMatch: ^id$ tags: - format:openapi - spec:paths - spec:operations - spec:parameters - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-no-id-query'' (Parameter No ID Query). Requirement: Resource identifier filtering is not allowed as a query parameter. Use the resource identifier in the URL path. To fix: Ensure `name` does NOT match the regular expression `^id$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths..get.parameters.[?(@.in==''query'' && @.name==''id'')]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-no-x-prefixed-request-header: title: Parameter No X Prefixed Request Header reference: https://spotlight-rules.com/spec/rules/openapi/parameter-no-x-prefixed-request-header/ description: Do not use headers with X-. message: 'Headers cannot start with X-. More: https://tools.ietf.org/html/rfc6648' severity: info given: $..parameters.[?(@.in === 'header')].name then: function: pattern functionOptions: notMatch: ^(x|X)- tags: - format:openapi - spec:parameters - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-no-x-prefixed-request-header'' (Parameter No X Prefixed Request Header). Requirement: Do not use headers with X-. To fix: Ensure the targeted value does NOT match the regular expression `^(x|X)-`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..parameters.[?(@.in === ''header'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-pagination-params-in-query: title: Parameter Pagination Params In Query reference: https://spotlight-rules.com/spec/rules/openapi/parameter-pagination-params-in-query/ description: Pagination parameters like page, limit, offset, and cursor should be passed as query parameters, not in headers or path segments. Analysis confirms 100% of pagination parameters observed are query parameters. message: Pagination Parameters MUST Be Query Parameters severity: info given: $.paths[*].get.parameters[?(@.name == 'page' || @.name == 'limit' || @.name == 'offset' || @.name == 'cursor' || @.name == 'per_page' || @.name == 'page_size')] then: field: in function: pattern functionOptions: match: query tags: - format:openapi - spec:paths - spec:operations - spec:parameters - topic:pagination - experience:pagination - experience:consistency - experience:performance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-pagination-params-in-query'' (Parameter Pagination Params In Query). Requirement: Pagination parameters like page, limit, offset, and cursor should be passed as query parameters, not in headers or path segments. Analysis confirms 100% of pagination parameters observed are query parameters. To fix: Ensure `in` matches the regular expression `query`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[*].get.parameters[?(@.name == ''page'' || @.name == ''limit'' || @.name == ''offset'' || @.name == ''cursor'' || @.name == ''per_page'' || @.name == ''page_size'')]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-query-allowed-characters: title: Parameter Query Allowed Characters reference: https://spotlight-rules.com/spec/rules/openapi/parameter-query-allowed-characters/ description: 'Query parameter keys MUST include only alpha-numeric characters and periods: [Aa0-Zz9]''.' message: 'Query parameter keys MUST include only alpha-numeric characters and periods: [Aa0-Zz9]''.' severity: info given: $.paths.*.*.parameters[?(@.in=='query')].name then: function: pattern functionOptions: match: ^[A-Za-z0-9\.]+$ tags: - format:openapi - spec:paths - spec:parameters - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-query-allowed-characters'' (Parameter Query Allowed Characters). Requirement: Query parameter keys MUST include only alpha-numeric characters and periods: [Aa0-Zz9]''. To fix: Ensure the targeted value matches the regular expression `^[A-Za-z0-9\.]+$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths.*.*.parameters[?(@.in==''query'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-query-camel-case: title: Parameter Query Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/parameter-query-camel-case/ description: MUST query parameter names must be ASCII camelCase [130a]. message: Query parameter name has to be ASCII camelCase severity: info given: $.paths.*.*.parameters[?(@ && @.in=='query')].name then: function: pattern functionOptions: match: ^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$ tags: - format:openapi - spec:paths - spec:parameters - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-query-camel-case'' (Parameter Query Camel Case). Requirement: MUST query parameter names must be ASCII camelCase [130a]. To fix: Ensure the targeted value matches the regular expression `^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths.*.*.parameters[?(@ && @.in==''query'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-query-must-be-optional: title: Parameter Query Must Be Optional reference: https://spotlight-rules.com/spec/rules/openapi/parameter-query-must-be-optional/ description: Query parameters MUST be optional. message: Query parameters MUST be optional. severity: info given: $.paths.*.*.parameters[?(@.in=='query')].required then: function: falsy tags: - format:openapi - spec:paths - spec:parameters - experience:usability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-query-must-be-optional'' (Parameter Query Must Be Optional). Requirement: Query parameters MUST be optional. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.*.*.parameters[?(@.in==''query'')].required` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-schema-require-type: title: Parameter Schema Require Type reference: https://spotlight-rules.com/spec/rules/openapi/parameter-schema-require-type/ description: Parameters must always have their schema type defined, being precise about what type of data can be inputted and used to configure an API request. message: Parameter Schema Type severity: info given: $.components.parameters.*.schema then: field: type function: truthy tags: - format:openapi - spec:parameters - spec:schemas - spec:components - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-schema-require-type'' (Parameter Schema Require Type). Requirement: Parameters must always have their schema type defined, being precise about what type of data can be inputted and used to configure an API request. To fix: Ensure `type` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.components.parameters.*.schema` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-schema-use-ref: title: Parameter Schema Use Ref reference: https://spotlight-rules.com/spec/rules/openapi/parameter-schema-use-ref/ description: Parameters must always use a schema reference that utilizes reusable schema that are defined as part of a centralized schema components library. message: Parameters MUST Use Schema Reference severity: info given: $.components.parameters.*.schema then: field: $ref function: falsy tags: - format:openapi - spec:parameters - spec:schemas - spec:components - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-schema-use-ref'' (Parameter Schema Use Ref). Requirement: Parameters must always use a schema reference that utilizes reusable schema that are defined as part of a centralized schema components library. To fix: Ensure `$ref` is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.components.parameters.*.schema` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-parameter-sort-param-only-on-get: title: Parameter Sort Param Only On Get reference: https://spotlight-rules.com/spec/rules/openapi/parameter-sort-param-only-on-get/ description: Non-GET endpoints MUST NOT have sorting query parameters. Parameter names such as sort, sorting, orderBy, etc. message: Non-GET endpoints MUST NOT have sorting query parameters. severity: info given: $.paths.*[?(@property!='get')].parameters.[?(@.in=='query')] then: field: name function: pattern functionOptions: notMatch: ^sort|sorting|sortBy|order|ordering|orderBy$ tags: - format:openapi - spec:paths - spec:operations - spec:parameters - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''parameter-sort-param-only-on-get'' (Parameter Sort Param Only On Get). Requirement: Non-GET endpoints MUST NOT have sorting query parameters. Parameter names such as sort, sorting, orderBy, etc. To fix: Ensure `name` does NOT match the regular expression `^sort|sorting|sortBy|order|ordering|orderBy$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*[?(@property!=''get'')].parameters.[?(@.in==''query'')]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-delete-no-response-body: title: Path Delete No Response Body reference: https://spotlight-rules.com/spec/rules/openapi/path-delete-no-response-body/ description: Check if the delete response does not have any body. message: '{{error}}' severity: info given: $.paths.* then: function: trimble-delete-must-not-return-body tags: - format:openapi - spec:paths - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-delete-no-response-body'' (Path Delete No Response Body). Requirement: Check if the delete response does not have any body. This rule is evaluated at the JSONPath `$.paths.*.` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-get-response-support-json: title: Path Get Response Support JSON reference: https://spotlight-rules.com/spec/rules/openapi/path-get-response-support-json/ description: All APIs returning structured data SHOULD support JSON as the default format. message: '{{error}}' severity: info given: $.paths.* then: function: trimble-check-if-response-body-json-in-get-response tags: - format:openapi - spec:paths - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-get-response-support-json'' (Path Get Response Support JSON). Requirement: All APIs returning structured data SHOULD support JSON as the default format. This rule is evaluated at the JSONPath `$.paths.*.` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-include-version: title: Path Include Version reference: https://spotlight-rules.com/spec/rules/openapi/path-include-version/ description: Path must include the version. message: '{{description}}; {{property}} incorrect' severity: info given: $.paths[?(@property!='/')]~ then: function: pattern functionOptions: match: ^(/v[12]/.*|/api/v[12]/.*)$ tags: - format:openapi - spec:paths - experience:versioning - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-include-version'' (Path Include Version). Requirement: Path must include the version. To fix: Ensure the targeted value matches the regular expression `^(/v[12]/.*|/api/v[12]/.*)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[?(@property!=''/'')]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-max-nesting-depth: title: Path Max Nesting Depth reference: https://spotlight-rules.com/spec/rules/openapi/path-max-nesting-depth/ description: API paths should not exceed 4 levels of nesting depth. Analysis of 6627 paths across 773 specs shows an average depth of 3.04 segments, with deeper paths indicating overly complex resource hierarchies. message: Path Nesting MUST NOT Exceed 4 Levels severity: info given: $.paths then: function: pattern functionOptions: notMatch: ^(/[^/]+){5,} tags: - format:openapi - spec:paths - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-max-nesting-depth'' (Path Max Nesting Depth). Requirement: API paths should not exceed 4 levels of nesting depth. Analysis of 6627 paths across 773 specs shows an average depth of 3.04 segments, with deeper paths indicating overly complex resource hierarchies. To fix: Ensure the targeted value does NOT match the regular expression `^(/[^/]+){5,}`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-api-prefix-in: title: Path No API Prefix In reference: https://spotlight-rules.com/spec/rules/openapi/path-no-api-prefix-in/ description: A resource SHOULD NOT contain 'api' as a prefix in or a part of the path. message: A resource SHOULD NOT contain 'api' as a prefix in or a part of the path. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: /api|/api/|-api/ tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-api-prefix-in'' (Path No API Prefix In). Requirement: A resource SHOULD NOT contain ''api'' as a prefix in or a part of the path. To fix: Ensure the targeted value does NOT match the regular expression `/api|/api/|-api/`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-empty-segment: title: Path No Empty Segment reference: https://spotlight-rules.com/spec/rules/openapi/path-no-empty-segment/ description: A resource MUST use normalized paths without empty path segments. message: A resource MUST use normalized paths without empty path segments. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: // tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-empty-segment'' (Path No Empty Segment). Requirement: A resource MUST use normalized paths without empty path segments. To fix: Ensure the targeted value does NOT match the regular expression `//`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-file-extension-in: title: Path No File Extension In reference: https://spotlight-rules.com/spec/rules/openapi/path-no-file-extension-in/ description: A resource SHOULD NOT make use of an extension at any point in the path. message: A resource SHOULD NOT make use of an extension at any point in the path. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: \. tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-file-extension-in'' (Path No File Extension In). Requirement: A resource SHOULD NOT make use of an extension at any point in the path. To fix: Ensure the targeted value does NOT match the regular expression `\.`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-file-extensions: title: Path No File Extensions reference: https://spotlight-rules.com/spec/rules/openapi/path-no-file-extensions/ description: API paths should not include file extensions like .json or .xml. Content negotiation should be handled through Accept headers rather than path suffixes. message: Paths MUST NOT Contain File Extensions severity: info given: $.paths then: function: pattern functionOptions: notMatch: \.(json|xml|html|yaml|yml|csv|pdf)$ tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-file-extensions'' (Path No File Extensions). Requirement: API paths should not include file extensions like .json or .xml. Content negotiation should be handled through Accept headers rather than path suffixes. To fix: Ensure the targeted value does NOT match the regular expression `\.(json|xml|html|yaml|yml|csv|pdf)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-format-extensions-in: title: Path No Format Extensions In reference: https://spotlight-rules.com/spec/rules/openapi/path-no-format-extensions-in/ description: Request and Response media type formats MUST NOT be implied using extensions on resources (i.e. .json or .xml). Instead, use the standard resource path with the appropriate Content-Type header. message: Request and Response media type formats MUST NOT be implied using extensions on resources (i.e. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: \.json|\.xml|\.yml|\.yaml tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-format-extensions-in'' (Path No Format Extensions In). Requirement: Request and Response media type formats MUST NOT be implied using extensions on resources (i.e. .json or .xml). Instead, use the standard resource path with the appropriate Content-Type header. To fix: Ensure the targeted value does NOT match the regular expression `\.json|\.xml|\.yml|\.yaml`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-http-method-names: title: Path No HTTP Method Names reference: https://spotlight-rules.com/spec/rules/openapi/path-no-http-method-names/ description: 'When you design a REST API, you don''t usually need to mention terms like `get`, `delete` and so on in your `paths`, because this information is conveyed by the HTTP method. Instead of using ``` POST /books/1234/delete HTTP/1.1 Host: api.example ``` You can simply call ``` DELETE /books/1234 HTTP/1.1 Host: api.example ``` Similarly you don''t need verbs like `list` or `create` because the HTTP Semantics RFC7231 supports this kind of actions natively with proper methods and status code. Instead of ``` POST /create/user HTTP/1.1 Host: api.example Content-Type: application/json {"given_name": "Mario"} ``` You can use ``` POST /create/user HTTP/1.1 Host: api.example Content-Type: application/json {"given_name": "Mario"} ``` returning a proper response ``` HTTP/1.1 201 Created Location: /users/1234 ``` This simplifies securing your API as you know beforehand the kind of action which is going to be performed.' message: API "path" contains a name of an http method. {{error}} severity: info given: - $.paths[?(@property.match( /\/(get|post|put|delete|patch)[\/A-Z_\-]?/ ))]~ - $.paths[?(@property.match( /\/(create|remove|list)[\/A-Z_\-]?/ ))]~ then: field: '@key' function: undefined tags: - format:openapi - spec:paths - spec:operations - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-http-method-names'' (Path No HTTP Method Names). Requirement: When you design a REST API, you don''t usually need to mention terms like `get`, `delete` and so on in your `paths`, because this information is conveyed by the HTTP method. Instead of using ``` POST /books/1234/delete HTTP/1.1 Host: api.example ``` You can simply call ``` DELETE /books/1234 HTTP/1.1 Host: api.example ``` Similarly you don''t need verbs like `list` or `create` because the HTTP Semantics RFC7231 supports this kind of actions natively with proper methods and status code. Instead of ``` POST /create/user HTTP/1.1 Host: api.example Content-Type: application/json {"given_name": "Mario"} ``` You can use ``` POST /create/user HTTP/1.1 Host: api.example Content-Type: application/json {"given_name": "Mario"} ``` returning a proper response ``` HTTP/1.1 201 Created Location: /users/1234 ``` This simplifies securing your API as you know beforehand the kind of action which is going to be performed. To fix: Remove `@key` from each matching location. This rule is evaluated at the JSONPath `$.paths[?(@property.match( /\/(get|post|put|delete|patch)[\/A-Z_\-]?/ ))]~ | $.paths[?(@property.match( /\/(create|remove|list)[\/A-Z_\-]?/ ))]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-http-methods-in: title: Path No HTTP Methods In reference: https://spotlight-rules.com/spec/rules/openapi/path-no-http-methods-in/ description: A resource SHOULD NOT contain HTTP methods. message: A resource SHOULD NOT contain HTTP methods. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: (\/get|\/post|\/put|\/delete|\/patch) tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-http-methods-in'' (Path No HTTP Methods In). Requirement: A resource SHOULD NOT contain HTTP methods. To fix: Ensure the targeted value does NOT match the regular expression `(\/get|\/post|\/put|\/delete|\/patch)`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-http-verbs: title: Path No HTTP Verbs reference: https://spotlight-rules.com/spec/rules/openapi/path-no-http-verbs/ severity: info description: HTTP verbs should be not be in URL paths. message: '{{property}} has HTTP verb in path: {{error}}' given: $.paths[*]~ then: function: trimble-no-http-verbs-in-path tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-http-verbs'' (Path No HTTP Verbs). Requirement: HTTP verbs should be not be in URL paths. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-invalid-symbols: title: Path No Invalid Symbols reference: https://spotlight-rules.com/spec/rules/openapi/path-no-invalid-symbols/ description: Check if the given endpoint has queryparameter. message: '{{error}}' severity: info given: $.paths[*]~ then: function: trimble-invalid-symbol-in-path tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-invalid-symbols'' (Path No Invalid Symbols). Requirement: Check if the given endpoint has queryparameter. This rule is evaluated at the JSONPath `$.paths.` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-query-string: title: Path No Query String reference: https://spotlight-rules.com/spec/rules/openapi/path-no-query-string/ description: Path must not include query string. message: Path must not include query string. severity: info given: $.paths then: function: pattern functionOptions: notMatch: \? formats: - oas3 - oas3_1 tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-query-string'' (Path No Query String). Requirement: Path must not include query string. To fix: Ensure the targeted value does NOT match the regular expression `\?`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-query-strings-in: title: Path No Query Strings In reference: https://spotlight-rules.com/spec/rules/openapi/path-no-query-strings-in/ description: Paths SHOULD NOT have query parameters in them. They should be defined separately in the OpenAPI. message: Paths SHOULD NOT have query parameters in them. They should be defined separately in the OpenAPI. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: \? tags: - format:openapi - spec:paths - experience:consistency - experience:naming prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-query-strings-in'' (Path No Query Strings In). Requirement: Paths SHOULD NOT have query parameters in them. They should be defined separately in the OpenAPI. To fix: Ensure the targeted value does NOT match the regular expression `\?`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-trailing-slash: title: Path No Trailing Slash reference: https://spotlight-rules.com/spec/rules/openapi/path-no-trailing-slash/ description: Path must not end with a slash. message: Path must not end with a slash. severity: info given: $.paths then: function: pattern functionOptions: notMatch: .+\/$ formats: - oas3 - oas3_1 tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-trailing-slash'' (Path No Trailing Slash). Requirement: Path must not end with a slash. To fix: Ensure the targeted value does NOT match the regular expression `.+\/$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-trailing-slash-in: title: Path No Trailing Slash In reference: https://spotlight-rules.com/spec/rules/openapi/path-no-trailing-slash-in/ description: A resource MUST be addressable without a trailing slash on the path. message: A resource MUST be addressable without a trailing slash on the path. severity: info given: $.paths.*~ then: function: pattern functionOptions: notMatch: /$ tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-trailing-slash-in'' (Path No Trailing Slash In). Requirement: A resource MUST be addressable without a trailing slash on the path. To fix: Ensure the targeted value does NOT match the regular expression `/$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-verbs: title: Path No Verbs reference: https://spotlight-rules.com/spec/rules/openapi/path-no-verbs/ description: API paths MUST be resource-focused and MUST NOT include verbs like 'get', 'update', 'create', or 'delete'. message: Path '{{path}}' includes a verb (e.g., 'get', 'update', 'create', 'delete'). API paths SHOULD be resource-focused. severity: info given: $.paths[*]~ then: function: pattern functionOptions: notMatch: /\b(get|update|create|delete|fetch|retrieve)\b/ formats: - oas3 tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-verbs'' (Path No Verbs). Requirement: API paths MUST be resource-focused and MUST NOT include verbs like ''get'', ''update'', ''create'', or ''delete''. To fix: Ensure the targeted value does NOT match the regular expression `/\b(get|update|create|delete|fetch|retrieve)\b/`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-version-segment: title: Path No Version Segment reference: https://spotlight-rules.com/spec/rules/openapi/path-no-version-segment/ description: API paths should not contain version numbers like v1 or v2. API versioning should be handled through headers, query parameters, or server URLs rather than embedded in resource paths. message: Paths MUST NOT Contain API Version severity: info given: $.paths then: function: pattern functionOptions: notMatch: /v[0-9] tags: - format:openapi - spec:paths - experience:versioning - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-version-segment'' (Path No Version Segment). Requirement: API paths should not contain version numbers like v1 or v2. API versioning should be handled through headers, query parameters, or server URLs rather than embedded in resource paths. To fix: Ensure the targeted value does NOT match the regular expression `/v[0-9]`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-no-x-prefixed-response-header: title: Path No X Prefixed Response Header reference: https://spotlight-rules.com/spec/rules/openapi/path-no-x-prefixed-response-header/ description: Do not use headers with X-. message: 'Headers cannot start with X-, so please find a new name for {{property}}. More: https://tools.ietf.org/html/rfc6648' severity: info given: $..headers.*~ then: function: pattern functionOptions: notMatch: ^(x|X)- tags: - format:openapi - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-no-x-prefixed-response-header'' (Path No X Prefixed Response Header). Requirement: Do not use headers with X-. To fix: Ensure the targeted value does NOT match the regular expression `^(x|X)-`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..headers.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-parameter-camel-case: title: Path Parameter Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/path-parameter-camel-case/ description: Path parameters MUST follow camelCase. message: '{{property}} path parameter is not camelCase: {{error}}' severity: info given: $..parameters[?(@.in == 'path')].name then: function: pattern functionOptions: match: ^[a-z][a-zA-Z0-9]+$ tags: - format:openapi - spec:parameters - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-parameter-camel-case'' (Path Parameter Camel Case). Requirement: Path parameters MUST follow camelCase. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-zA-Z0-9]+$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''path'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-parameter-constant-case: title: Path Parameter Constant Case reference: https://spotlight-rules.com/spec/rules/openapi/path-parameter-constant-case/ description: Path parameters MUST follow CONSTANT_CASE (screaming snake_case). message: '{{property}} path parameter is not CONSTANT_CASE: {{error}}' severity: info given: $..parameters[?(@.in == 'path')].name then: function: pattern functionOptions: match: ^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ tags: - format:openapi - spec:parameters - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-parameter-constant-case'' (Path Parameter Constant Case). Requirement: Path parameters MUST follow CONSTANT_CASE (screaming snake_case). To fix: Ensure the targeted value matches the regular expression `^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''path'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-parameter-kebab-case: title: Path Parameter Kebab Case reference: https://spotlight-rules.com/spec/rules/openapi/path-parameter-kebab-case/ description: Path parameters MUST follow kebab-case. message: '{{property}} path parameter is not kebab-case: {{error}}' severity: info given: $..parameters[?(@.in == 'path')].name then: function: pattern functionOptions: match: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ tags: - format:openapi - spec:parameters - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-parameter-kebab-case'' (Path Parameter Kebab Case). Requirement: Path parameters MUST follow kebab-case. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''path'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-parameter-not-empty: title: Path Parameter Not Empty reference: https://spotlight-rules.com/spec/rules/openapi/path-parameter-not-empty/ description: Path parameter declarations must not be empty ex. `/api/{}` is invalid. message: Path parameter declarations must not be empty ex. severity: info given: $.paths then: function: pattern functionOptions: notMatch: '{}' formats: - oas3 - oas3_1 tags: - format:openapi - spec:paths - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-parameter-not-empty'' (Path Parameter Not Empty). Requirement: Path parameter declarations must not be empty ex. `/api/{}` is invalid. To fix: Ensure the targeted value does NOT match the regular expression `{}`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-parameter-pascal-case: title: Path Parameter Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/path-parameter-pascal-case/ description: Path parameters MUST follow PascalCase. message: '{{property}} path parameter is not PascalCase: {{error}}' severity: info given: $..parameters[?(@.in == 'path')].name then: function: pattern functionOptions: match: ^[A-Z][a-zA-Z0-9]+$ tags: - format:openapi - spec:parameters - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-parameter-pascal-case'' (Path Parameter Pascal Case). Requirement: Path parameters MUST follow PascalCase. To fix: Ensure the targeted value matches the regular expression `^[A-Z][a-zA-Z0-9]+$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''path'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-parameter-snake-case: title: Path Parameter Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/path-parameter-snake-case/ description: Path parameters MUST follow snake_case. message: '{{property}} path parameter is not snake_case: {{error}}' severity: info given: $..parameters[?(@.in == 'path')].name then: function: pattern functionOptions: match: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$ tags: - format:openapi - spec:parameters - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-parameter-snake-case'' (Path Parameter Snake Case). Requirement: Path parameters MUST follow snake_case. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-z0-9]*(_[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..parameters[?(@.in == ''path'')].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-params-declared-in-block: title: Path Params Declared In Block reference: https://spotlight-rules.com/spec/rules/openapi/path-params-declared-in-block/ description: Check for the path parameter in the parameter block. message: '{{error}}' severity: info given: $.paths then: function: trimble-check-for-path-parameter tags: - format:openapi - spec:paths - experience:consistency - experience:documentation prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-params-declared-in-block'' (Path Params Declared In Block). Requirement: Check for the path parameter in the parameter block. This rule is evaluated at the JSONPath `$.paths.` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-require-query-parameter: title: Path Require Query Parameter reference: https://spotlight-rules.com/spec/rules/openapi/path-require-query-parameter/ description: Check if the given resource path has queryparameter. message: '{{error}}' severity: info given: $.paths[*]~ then: function: trimble-check-for-query-parameter-in-every-path tags: - format:openapi - spec:paths - experience:usability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-require-query-parameter'' (Path Require Query Parameter). Requirement: Check if the given resource path has queryparameter. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-require-valid-http-verb: title: Path Require Valid HTTP Verb reference: https://spotlight-rules.com/spec/rules/openapi/path-require-valid-http-verb/ description: All APIs MUST have a valid http verb. message: '{{error}}' severity: info given: $.paths.* then: field: '@key' function: trimble-does-spec-contains-valid-http-verbs tags: - format:openapi - spec:paths - experience:consistency - experience:governance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-require-valid-http-verb'' (Path Require Valid HTTP Verb). Requirement: All APIs MUST have a valid http verb. This rule is evaluated at the JSONPath `$.paths.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-resources-plural: title: Path Resources Plural reference: https://spotlight-rules.com/spec/rules/openapi/path-resources-plural/ description: Resource names in paths should use plural nouns to maintain consistency and follow REST conventions for collection-oriented resource design. message: Path Resources Should Be Plural severity: info given: $.paths then: function: pattern functionOptions: match: ^(/[a-z].*s(/\{[^}]+\})?)*$ tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-resources-plural'' (Path Resources Plural). Requirement: Resource names in paths should use plural nouns to maintain consistency and follow REST conventions for collection-oriented resource design. To fix: Ensure the targeted value matches the regular expression `^(/[a-z].*s(/\{[^}]+\})?)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-segment-kebab-case: title: Path Segment Kebab Case reference: https://spotlight-rules.com/spec/rules/openapi/path-segment-kebab-case/ description: All YAML/JSON paths MUST follow kebab-case. message: '{{property}} is not kebab-case: {{error}}' severity: info given: $.paths[*]~ then: function: pattern functionOptions: match: ^/([a-z0-9]+(-[a-z0-9]+)*)?(/[a-z0-9]+(-[a-z0-9]+)*|/{.+})*$ tags: - format:openapi - spec:paths - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-segment-kebab-case'' (Path Segment Kebab Case). Requirement: All YAML/JSON paths MUST follow kebab-case. To fix: Ensure the targeted value matches the regular expression `^/([a-z0-9]+(-[a-z0-9]+)*)?(/[a-z0-9]+(-[a-z0-9]+)*|/{.+})*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-uri-versioning-single-version: title: Path URI Versioning Single Version reference: https://spotlight-rules.com/spec/rules/openapi/path-uri-versioning-single-version/ description: CAN use correct URI versioning [115a]. message: Path can contain correct URI versioning severity: info given: $.paths.*~ then: function: pattern functionOptions: match: ^((?!.*\/v\d+(\/.*)?\/v\d+)\/.*)$ tags: - format:openapi - spec:paths - experience:versioning - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-uri-versioning-single-version'' (Path URI Versioning Single Version). Requirement: CAN use correct URI versioning [115a]. To fix: Ensure the targeted value matches the regular expression `^((?!.*\/v\d+(\/.*)?\/v\d+)\/.*)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-use-standard-http-methods: title: Path Use Standard HTTP Methods reference: https://spotlight-rules.com/spec/rules/openapi/path-use-standard-http-methods/ description: Operations MUST use only the common HTTP methods as outlined in the standards guide, and must be in lower-case. message: Operations MUST use only the common HTTP methods as outlined in the standards guide, and must be in lower-case. severity: info given: $.paths[*].*~ then: field: method function: enumeration functionOptions: values: - get - post - put - patch - delete - head - options tags: - format:openapi - spec:paths - experience:consistency - experience:naming prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-use-standard-http-methods'' (Path Use Standard HTTP Methods). Requirement: Operations MUST use only the common HTTP methods as outlined in the standards guide, and must be in lower-case. To fix: Set `method` to one of the allowed values: get, post, put, patch, delete, head, options. This rule is evaluated at the JSONPath `$.paths[*].*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-path-write-response-support-json: title: Path Write Response Support JSON reference: https://spotlight-rules.com/spec/rules/openapi/path-write-response-support-json/ description: All APIs returning structured data SHOULD support JSON as the default format. message: '{{error}}' severity: info given: $.paths.* then: function: trimble-check-if-application-or-json-in-put-and-post-response tags: - format:openapi - spec:paths - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''path-write-response-support-json'' (Path Write Response Support JSON). Requirement: All APIs returning structured data SHOULD support JSON as the default format. This rule is evaluated at the JSONPath `$.paths.*.` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-body-must-use-json-content-type: title: Request Body Must Use JSON Content Type reference: https://spotlight-rules.com/spec/rules/openapi/request-body-must-use-json-content-type/ description: Request bodies should use application/json as the primary content type for consistency across API operations and client implementations. message: Request Body MUST Use application/json Content Type severity: info given: $.paths.*[post,put,patch].requestBody.content then: field: application/json function: truthy tags: - format:openapi - spec:paths - spec:operations - spec:request-body - spec:media-types - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-body-must-use-json-content-type'' (Request Body Must Use JSON Content Type). Requirement: Request bodies should use application/json as the primary content type for consistency across API operations and client implementations. To fix: Ensure `application/json` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*[post,put,patch].requestBody.content` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-delete-must-not-have-body: title: Request Delete Must Not Have Body reference: https://spotlight-rules.com/spec/rules/openapi/request-delete-must-not-have-body/ description: DELETE operations must not accept a request body. message: DELETE operations must not accept a request body. severity: info given: $.paths[*].delete.requestBody then: function: undefined tags: - format:openapi - spec:paths - spec:operations - spec:request-body - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-delete-must-not-have-body'' (Request Delete Must Not Have Body). Requirement: DELETE operations must not accept a request body. To fix: Remove the targeted value from each matching location. This rule is evaluated at the JSONPath `$.paths[*].delete.requestBody` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-delete-no-body: title: Request Delete No Body reference: https://spotlight-rules.com/spec/rules/openapi/request-delete-no-body/ description: DELETE requests MUST NOT have a request body. message: DELETE requests MUST NOT have a request body. severity: info given: $.paths[*].delete.requestBody then: function: falsy message: '{{description}}: {{error}}' formats: - oas3 tags: - format:openapi - spec:paths - spec:operations - spec:request-body - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-delete-no-body'' (Request Delete No Body). Requirement: DELETE requests MUST NOT have a request body. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths[*].delete.requestBody` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-get-must-not-have-body: title: Request Get Must Not Have Body reference: https://spotlight-rules.com/spec/rules/openapi/request-get-must-not-have-body/ description: A `GET` request MUST NOT accept a request body. message: A `GET` request MUST NOT accept a request body. severity: info given: $.paths[*][get].requestBody then: function: undefined tags: - format:openapi - spec:paths - spec:operations - spec:request-body - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-get-must-not-have-body'' (Request Get Must Not Have Body). Requirement: A `GET` request MUST NOT accept a request body. To fix: Remove the targeted value from each matching location. This rule is evaluated at the JSONPath `$.paths[*][get].requestBody` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-get-no-body: title: Request Get No Body reference: https://spotlight-rules.com/spec/rules/openapi/request-get-no-body/ description: GET requests MUST NOT have a request body. message: GET requests MUST NOT have a request body. severity: info given: $.paths[*].get.requestBody then: function: falsy message: '{{description}}: {{error}}' formats: - oas3 tags: - format:openapi - spec:paths - spec:operations - spec:request-body - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-get-no-body'' (Request Get No Body). Requirement: GET requests MUST NOT have a request body. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths[*].get.requestBody` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-head-must-not-have-body: title: Request Head Must Not Have Body reference: https://spotlight-rules.com/spec/rules/openapi/request-head-must-not-have-body/ description: A `HEAD` request MUST NOT accept a request body. message: A `HEAD` request MUST NOT accept a request body. severity: info given: $.paths[*][head].requestBody then: function: undefined tags: - format:openapi - spec:paths - spec:operations - spec:request-body - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-head-must-not-have-body'' (Request Head Must Not Have Body). Requirement: A `HEAD` request MUST NOT accept a request body. To fix: Remove the targeted value from each matching location. This rule is evaluated at the JSONPath `$.paths[*][head].requestBody` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-header-names-pascal-case: title: Request Header Names Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/request-header-names-pascal-case/ description: Headers should be pascal-case. See Italian recommendation RAC_REST_NAME_003. message: '{{value}} {{error}} in {{path}}' severity: info given: - $.[parameters][?(@.in=="header")].name then: function: casing functionOptions: type: pascal separator: char: '-' tags: - format:openapi - spec:parameters - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-header-names-pascal-case'' (Request Header Names Pascal Case). Requirement: Headers should be pascal-case. See Italian recommendation RAC_REST_NAME_003. To fix: Rename the targeted key or value to PascalCase (e.g. `UserName`) at each matching location, updating every reference to it. This rule is evaluated at the JSONPath `$.[parameters][?(@.in=="header")].name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-options-must-not-have-body: title: Request Options Must Not Have Body reference: https://spotlight-rules.com/spec/rules/openapi/request-options-must-not-have-body/ description: An `OPTIONS` request MUST NOT accept a request body. message: An `OPTIONS` request MUST NOT accept a request body. severity: info given: $.paths[*][options].requestBody then: function: undefined tags: - format:openapi - spec:paths - spec:operations - spec:request-body - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-options-must-not-have-body'' (Request Options Must Not Have Body). Requirement: An `OPTIONS` request MUST NOT accept a request body. To fix: Remove the targeted value from each matching location. This rule is evaluated at the JSONPath `$.paths[*][options].requestBody` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-patch-media-type-not-plain-json: title: Request Patch Media Type Not Plain JSON reference: https://spotlight-rules.com/spec/rules/openapi/request-patch-media-type-not-plain-json/ description: 'The PATCH specification explicits that the request body contains a "patch document" describing the changes to be applied to the target resource. To avoid confusion, [this errata](https://www.rfc-editor.org/errata/eid3169) explains that `application/json` is not an appropriate media-type for `PATCH`. A correct example of PATCH using eg. `application/json-patch+json` media-type defined in RFC6902. ``` paths: /books/{book_id}: patch: requestBody: content: application/json-patch+json: schema: type: object example: [{ "op": "add", "path": "/baz", "value": "qux" }] ```.' message: application/json is not an appropriate media-type for PATCH. {{path}} severity: info given: $.[patch][requestBody][content] then: field: application/json function: falsy formats: - oas3 tags: - format:openapi - spec:operations - spec:request-body - spec:media-types - topic:content-negotiation - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-patch-media-type-not-plain-json'' (Request Patch Media Type Not Plain JSON). Requirement: The PATCH specification explicits that the request body contains a "patch document" describing the changes to be applied to the target resource. To avoid confusion, [this errata](https://www.rfc-editor.org/errata/eid3169) explains that `application/json` is not an appropriate media-type for `PATCH`. A correct example of PATCH using eg. `application/json-patch+json` media-type defined in RFC6902. ``` paths: /books/{book_id}: patch: requestBody: content: application/json-patch+json: schema: type: object example: [{ "op": "add", "path": "/baz", "value": "qux" }] ```. To fix: Ensure `application/json` is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.[patch][requestBody][content]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-property-names-camel-case: title: Request Property Names Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/request-property-names-camel-case/ description: MUST property names must be ASCII camelCase [118a]. message: Property name has to be ASCII camelCase severity: info given: $.paths.*.*[responses,requestBody]..content..schema..properties.*~ then: function: pattern functionOptions: match: ^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$ tags: - format:openapi - spec:paths - spec:request-body - spec:responses - spec:media-types - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-property-names-camel-case'' (Request Property Names Camel Case). Requirement: MUST property names must be ASCII camelCase [118a]. To fix: Ensure the targeted value matches the regular expression `^[a-z]+((\d)|([A-Z0-9][a-z0-9]+))*([A-Z])?$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths.*.*[responses,requestBody]..content..schema..properties.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-support-accept-language: title: Request Support Accept Language reference: https://spotlight-rules.com/spec/rules/openapi/request-support-accept-language/ description: Operations should accept an Accept-Language request header so clients can negotiate a localized response (i18n). message: Operation should accept an Accept-Language header. given: $.paths[*][get,post,put,patch,delete] severity: info then: field: parameters function: schema functionOptions: schema: type: array contains: type: object required: - name - in properties: name: const: Accept-Language in: const: header tags: - format:openapi - spec:parameters - topic:content-negotiation - experience:usability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-support-accept-language'' (Request Support Accept Language). Requirement: Operations should accept an Accept-Language request header so clients can negotiate a localized response (i18n). To fix: Adjust `parameters` so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths[*][get,post,put,patch,delete]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-support-form-urlencoded-media-type: title: Request Support Form Urlencoded Media Type reference: https://spotlight-rules.com/spec/rules/openapi/request-support-form-urlencoded-media-type/ description: Every request MUST support `application/x-www-form-urlencoded` media type. message: '{{description}}: {{error}}' severity: info given: $.paths.[*].requestBody.content[?(@property.indexOf('urlencoded') === -1)]^ then: function: falsy formats: - oas3 tags: - format:openapi - spec:paths - spec:request-body - spec:media-types - topic:content-negotiation - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-support-form-urlencoded-media-type'' (Request Support Form Urlencoded Media Type). Requirement: Every request MUST support `application/x-www-form-urlencoded` media type. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.[*].requestBody.content[?(@property.indexOf(''urlencoded'') === -1)]^` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-support-json-media-type: title: Request Support JSON Media Type reference: https://spotlight-rules.com/spec/rules/openapi/request-support-json-media-type/ description: Every request MUST support `application/json` media type. message: '{{description}}: {{error}}' severity: info given: $.paths.[*].requestBody.content[?(@property.indexOf('json') === -1)]^ then: function: falsy formats: - oas3 tags: - format:openapi - spec:paths - spec:request-body - spec:media-types - topic:content-negotiation - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-support-json-media-type'' (Request Support JSON Media Type). Requirement: Every request MUST support `application/json` media type. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.[*].requestBody.content[?(@property.indexOf(''json'') === -1)]^` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-support-json-media-type-2: title: Request Support JSON Media Type 2 reference: https://spotlight-rules.com/spec/rules/openapi/request-support-json-media-type-2/ description: Every request MUST support `application/json` media type. message: Every request MUST support `application/json` media type. severity: info given: $.paths[*][*].requestBody.content then: function: schema functionOptions: schema: type: object properties: application/json: true required: - application/json formats: - oas3 tags: - format:openapi - spec:paths - spec:request-body - spec:media-types - topic:content-negotiation - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-support-json-media-type-2'' (Request Support JSON Media Type 2). Requirement: Every request MUST support `application/json` media type. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths[*][*].requestBody.content` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-support-multipart-media-type: title: Request Support Multipart Media Type reference: https://spotlight-rules.com/spec/rules/openapi/request-support-multipart-media-type/ description: Every request MUST support `multipart/form-data` media type. message: '{{description}}: {{error}}' severity: info given: $.paths.[*].requestBody.content[?(@property.indexOf('multipart') === -1)]^ then: function: falsy formats: - oas3 tags: - format:openapi - spec:paths - spec:request-body - spec:media-types - topic:content-negotiation - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-support-multipart-media-type'' (Request Support Multipart Media Type). Requirement: Every request MUST support `multipart/form-data` media type. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.[*].requestBody.content[?(@property.indexOf(''multipart'') === -1)]^` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-support-text-plain-media-type: title: Request Support Text Plain Media Type reference: https://spotlight-rules.com/spec/rules/openapi/request-support-text-plain-media-type/ description: Every request MUST support `text/plain` media type. message: '{{description}}: {{error}}' severity: info given: $.paths.[*].requestBody.content[?(@property.indexOf('plain') === -1)]^ then: function: falsy formats: - oas3 tags: - format:openapi - spec:paths - spec:request-body - spec:media-types - topic:content-negotiation - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-support-text-plain-media-type'' (Request Support Text Plain Media Type). Requirement: Every request MUST support `text/plain` media type. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.[*].requestBody.content[?(@property.indexOf(''plain'') === -1)]^` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-request-support-xml-media-type: title: Request Support XML Media Type reference: https://spotlight-rules.com/spec/rules/openapi/request-support-xml-media-type/ description: Every request MUST support `application/xml` media type. message: '{{description}}: {{error}}' severity: info given: $.paths.[*].requestBody.content[?(@property.indexOf('xml') === -1)]^ then: function: falsy formats: - oas3 tags: - format:openapi - spec:paths - spec:request-body - spec:media-types - topic:content-negotiation - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''request-support-xml-media-type'' (Request Support XML Media Type). Requirement: Every request MUST support `application/xml` media type. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.[*].requestBody.content[?(@property.indexOf(''xml'') === -1)]^` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-206-require-content-range: title: Response 206 Require Content Range reference: https://spotlight-rules.com/spec/rules/openapi/response-206-require-content-range/ description: Check if the get response code 206 has content-type and content-range. message: '{{error}}' severity: info given: $.paths.* then: function: trimble-check-content-type-for-206-get-response-code tags: - format:openapi - spec:paths - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-206-require-content-range'' (Response 206 Require Content Range). Requirement: Check if the get response code 206 has content-type and content-range. This rule is evaluated at the JSONPath `$.paths.*.` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-body-must-be-object: title: Response Body Must Be Object reference: https://spotlight-rules.com/spec/rules/openapi/response-body-must-be-object/ description: Response bodies must be an object type. message: Response bodies must be an object type. severity: info given: $.paths[*][*].responses[*].content.application/json.schema.type then: function: pattern functionOptions: match: object tags: - format:openapi - spec:paths - spec:responses - spec:media-types - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-body-must-be-object'' (Response Body Must Be Object). Requirement: Response bodies must be an object type. To fix: Ensure the targeted value matches the regular expression `object`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[*][*].responses[*].content.application/json.schema.type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-cache-header-no-conflict: title: Response Cache Header No Conflict reference: https://spotlight-rules.com/spec/rules/openapi/response-cache-header-no-conflict/ description: 'Cache usage SHOULD be extensively detailed in the `description` property to avoid data leaks or the usage of stale data. This rule should ensure in some way that the api provider documented extensively the cache usage to avoid data leaks or usage of stale data. For now this ruleset tests: * the presence of following keywords in the `description`: `max-age`, `private`, `no-store`, `no-cache`. * that one and only one between Expires and Cache-Control is used. `Cache-Control` and `Expires` should not be used in conjuction, because `Cache-Control` overrides `Expires` when `max-age` is set. Instead if neither `Cache-Control` or `Expires` are set, clients MAY use euristic cache like described in RFC7234.' message: '{{error}}' severity: info given: $.[responses][?(@property[0] == "2" )][headers] then: - function: xor functionOptions: properties: - Expires - Cache-Control formats: - oas3 tags: - format:openapi - spec:responses - spec:headers - topic:caching - experience:reliability - experience:consistency - experience:performance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-cache-header-no-conflict'' (Response Cache Header No Conflict). Requirement: Cache usage SHOULD be extensively detailed in the `description` property to avoid data leaks or the usage of stale data. This rule should ensure in some way that the api provider documented extensively the cache usage to avoid data leaks or usage of stale data. For now this ruleset tests: * the presence of following keywords in the `description`: `max-age`, `private`, `no-store`, `no-cache`. * that one and only one between Expires and Cache-Control is used. `Cache-Control` and `Expires` should not be used in conjuction, because `Cache-Control` overrides `Expires` when `max-age` is set. Instead if neither `Cache-Control` or `Expires` are set, clients MAY use euristic cache like described in RFC7234. To fix: Include exactly one of: Expires, Cache-Control. This rule is evaluated at the JSONPath `$.[responses][?(@property[0] == "2" )][headers]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-code-must-be-valid: title: Response Code Must Be Valid reference: https://spotlight-rules.com/spec/rules/openapi/response-code-must-be-valid/ description: All APIs should return a valid http response code. message: '{{error}}' severity: info given: $..responses then: field: '@key' function: trimble-valid-http-response tags: - format:openapi - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-code-must-be-valid'' (Response Code Must Be Valid). Requirement: All APIs should return a valid http response code. This rule is evaluated at the JSONPath `$..responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-custom-header-naming-format: title: Response Custom Header Naming Format reference: https://spotlight-rules.com/spec/rules/openapi/response-custom-header-naming-format/ description: Custom headers MUST NOT be longer than 50 chars, and MUST only contain alphanumeric and dash chars, and MUST begin with Sps- not X-. message: Custom headers MUST NOT be longer than 50 chars, and MUST only contain alphanumeric and dash chars, and MUST begin with Sps- not X-. severity: info given: $.paths[*][*].responses[*].headers.*~ then: function: pattern functionOptions: match: ^(Sps-[a-zA-Z0-9-]{1,50}|Accept|Access-Control.*|Authorization|Cache-Control|Content-Disposition|Content-Language|Content-Length|Content-Type|Date|ETag|Host|If-Match|If-None-Match|Location|Origin|User-Agent)$ tags: - format:openapi - spec:paths - spec:responses - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-custom-header-naming-format'' (Response Custom Header Naming Format). Requirement: Custom headers MUST NOT be longer than 50 chars, and MUST only contain alphanumeric and dash chars, and MUST begin with Sps- not X-. To fix: Ensure the targeted value matches the regular expression `^(Sps-[a-zA-Z0-9-]{1,50}|Accept|Access-Control.*|Authorization|Cache-Control|Content-Disposition|Content-Language|Content-Length|Content-Type|Date|ETag|Host|If-Match|If-None-Match|Location|Origin|User-Agent)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[*][*].responses[*].headers.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-default-content-language-en-us: title: Response Default Content Language En Us reference: https://spotlight-rules.com/spec/rules/openapi/response-default-content-language-en-us/ description: Content-Language is optional but MUST default locale to en-US when none provided. message: Content-Language is optional but MUST default locale to en-US when none provided. severity: info given: $.paths[*][*].responses[*].headers.Content-Language.schema.default then: function: pattern functionOptions: match: en-US tags: - format:openapi - spec:paths - spec:responses - spec:headers - spec:media-types - spec:schemas - topic:content-negotiation - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-default-content-language-en-us'' (Response Default Content Language En Us). Requirement: Content-Language is optional but MUST default locale to en-US when none provided. To fix: Ensure the targeted value matches the regular expression `en-US`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[*][*].responses[*].headers.Content-Language.schema.default` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-delete-404-use-schema-ref: title: Response Delete 404 Use Schema Ref reference: https://spotlight-rules.com/spec/rules/openapi/response-delete-404-use-schema-ref/ description: DELETE 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response. message: DELETE 404 Responses MUST Use Schema Reference severity: info given: $.paths.*.delete.responses.404 then: field: $ref function: falsy tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-delete-404-use-schema-ref'' (Response Delete 404 Use Schema Ref). Requirement: DELETE 404 not found HTTP status codes have a schema references to standardize the response payload returned for the error response. To fix: Ensure `$ref` is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.*.delete.responses.404` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-delete-codes-allowed: title: Response Delete Codes Allowed reference: https://spotlight-rules.com/spec/rules/openapi/response-delete-codes-allowed/ description: DELETE operations should not return 200 or 201 status codes. message: DELETE operations should not return 200 or 201 status codes. severity: info given: $.paths[*].delete.responses then: field: '@key' function: pattern functionOptions: notMatch: ^(200|201)$ tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-delete-codes-allowed'' (Response Delete Codes Allowed). Requirement: DELETE operations should not return 200 or 201 status codes. To fix: Ensure `@key` does NOT match the regular expression `^(200|201)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].delete.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-delete-define-204: title: Response Delete Define 204 reference: https://spotlight-rules.com/spec/rules/openapi/response-delete-define-204/ description: DELETE responses should have a 204 success HTTP status codes, communicating a success created response to consumers. message: DELETE 204 Status Code severity: info given: $.paths.*.delete.responses then: field: '204' function: truthy tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:reliability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-delete-define-204'' (Response Delete Define 204). Requirement: DELETE responses should have a 204 success HTTP status codes, communicating a success created response to consumers. To fix: Ensure `204` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*.delete.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-delete-must-not-return-body: title: Response Delete Must Not Return Body reference: https://spotlight-rules.com/spec/rules/openapi/response-delete-must-not-return-body/ description: DELETE operations must not have a response body. message: DELETE operations must not have a response body. severity: info given: $.paths.*.delete.responses[202,204].content then: function: falsy tags: - format:openapi - spec:paths - spec:operations - spec:responses - spec:media-types - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-delete-must-not-return-body'' (Response Delete Must Not Return Body). Requirement: DELETE operations must not have a response body. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.*.delete.responses[202,204].content` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-delete-require-204: title: Response Delete Require 204 reference: https://spotlight-rules.com/spec/rules/openapi/response-delete-require-204/ description: All DELETE methods MUST have a 204 response. message: All DELETE methods MUST have a 204 response. severity: info given: - $.paths[*].delete.responses then: field: '204' function: truthy formats: - oas3 tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:consistency - experience:error-handling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-delete-require-204'' (Response Delete Require 204). Requirement: All DELETE methods MUST have a 204 response. To fix: Ensure `204` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths[*].delete.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-error-match-problem-schema: title: Response Error Match Problem Schema reference: https://spotlight-rules.com/spec/rules/openapi/response-error-match-problem-schema/ description: 'WARN: This rule is under implementation and just provides an hint. Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users. This rule inspects the schema returned by an error response and verifies whether it contains the main properties defined in RFC7807: `status`, `title` and `detail`. An example of a valid payload is ``` { "title": "Not Found", "status": 404, "detail": "Book does not exist; id: 123" } ``` See recommendation RAC_REST_NAME_007.' message: Your schema doesn't seem to match RFC7807. Are you sure it is ok? {{path}} severity: info given: $.paths.[*].responses[?(@property.match(/^(4|5|default)/))][[schema]] then: function: schema functionOptions: schema: type: object properties: status: type: integer title: type: string detail: type: string formats: - oas3 tags: - format:openapi - spec:paths - spec:responses - spec:schemas - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-error-match-problem-schema'' (Response Error Match Problem Schema). Requirement: WARN: This rule is under implementation and just provides an hint. Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users. This rule inspects the schema returned by an error response and verifies whether it contains the main properties defined in RFC7807: `status`, `title` and `detail`. An example of a valid payload is ``` { "title": "Not Found", "status": 404, "detail": "Book does not exist; id: 123" } ``` See recommendation RAC_REST_NAME_007. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.paths.[*].responses[?(@property.match(/^(4|5|default)/))][[schema]]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-error-schema-problem-property-names: title: Response Error Schema Problem Property Names reference: https://spotlight-rules.com/spec/rules/openapi/response-error-schema-problem-property-names/ description: 'WARN: This rule is under implementation and just provides an hint. Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users. Errors should return RFC7807 objects. Instead, this schema seems to use non standard properties such as: `message`, `msg` and `code`. An error of the following form ``` { "msg": "Book with id: 123 does not exist.", "code": 6063 } ``` can be expressed in RFC7807 with ``` { "detail": "Book with id: 123 does not exist.", "type": "https://api.example/v1/errors/6063", "status": 404, "title": "Not Found" } ``` Returning an URI in `type`, instead of an opaque `code` can help the client in better identifying the error; moreover the URI though it should not be dereferenced automatically, can return an actual resource providing guidance in addressing the issue. See recommendation RAC_REST_NAME_007.' message: Error response doesn't seem to match RFC7807. Are you sure it is ok? {{path}} severity: info given: $.[responses][?(@property.match(/^(4|5|default)/))][[schema]][properties].*~ then: field: '@key' function: pattern functionOptions: notMatch: message|code|msg formats: - oas3 tags: - format:openapi - spec:responses - spec:schemas - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-error-schema-problem-property-names'' (Response Error Schema Problem Property Names). Requirement: WARN: This rule is under implementation and just provides an hint. Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users. Errors should return RFC7807 objects. Instead, this schema seems to use non standard properties such as: `message`, `msg` and `code`. An error of the following form ``` { "msg": "Book with id: 123 does not exist.", "code": 6063 } ``` can be expressed in RFC7807 with ``` { "detail": "Book with id: 123 does not exist.", "type": "https://api.example/v1/errors/6063", "status": 404, "title": "Not Found" } ``` Returning an URI in `type`, instead of an opaque `code` can help the client in better identifying the error; moreover the URI though it should not be dereferenced automatically, can return an actual resource providing guidance in addressing the issue. See recommendation RAC_REST_NAME_007. To fix: Ensure `@key` does NOT match the regular expression `message|code|msg`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.[responses][?(@property.match(/^(4|5|default)/))][[schema]][properties].*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-error-standard-payload: title: Response Error Standard Payload reference: https://spotlight-rules.com/spec/rules/openapi/response-error-standard-payload/ description: All 4XX and 5XX response codes must follow Trimble API Standard. message: '{{error}}' severity: info given: $.paths.*.*.responses then: function: trimble-check-standard-for-error-payload tags: - format:openapi - spec:paths - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-error-standard-payload'' (Response Error Standard Payload). Requirement: All 4XX and 5XX response codes must follow Trimble API Standard. This rule is evaluated at the JSONPath `$.paths.*.*.responses.` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-error-use-problem-json: title: Response Error Use Problem JSON reference: https://spotlight-rules.com/spec/rules/openapi/response-error-use-problem-json/ description: All 4xx and 5xx error responses MUST use the `application/problem+json` media type (RFC 7807). message: 'Error response documents MUST use the application/problem+json media type: {{error}}' severity: info given: $.paths..responses[?( @property >= 400 && @property < 600)].content[*]~ then: function: enumeration functionOptions: values: - application/problem+json formats: - oas3 tags: - format:openapi - spec:paths - spec:responses - spec:media-types - experience:consistency - experience:error-handling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-error-use-problem-json'' (Response Error Use Problem JSON). Requirement: All 4xx and 5xx error responses MUST use the `application/problem+json` media type (RFC 7807). To fix: Set the targeted value to one of the allowed values: application/problem+json. This rule is evaluated at the JSONPath `$.paths..responses[?( @property >= 400 && @property < 600)].content[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-error-use-problem-type: title: Response Error Use Problem Type reference: https://spotlight-rules.com/spec/rules/openapi/response-error-use-problem-type/ description: 'Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users. Error responses should return one of the media-type defined in RFC7807: - `application/problem+json` - `application/problem+xml` An example of a valid response: ``` responses: "503": content: application/problem+json: schema: ... ```.' message: Error responses should support RFC7807 in {{path}}. severity: info given: $.paths.[*].responses[?(@property.match(/^(4|5|default)/))].content.*~ then: function: enumeration functionOptions: values: - application/problem+xml - application/problem+json formats: - oas3 tags: - format:openapi - spec:paths - spec:responses - spec:media-types - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-error-use-problem-type'' (Response Error Use Problem Type). Requirement: Error management is a key enabler of a resilient API ecosystem. Enforcing a consistent schema for errors between different APIs, enables client to properly implement an error management strategy, with positive impacts for users. Error responses should return one of the media-type defined in RFC7807: - `application/problem+json` - `application/problem+xml` An example of a valid response: ``` responses: "503": content: application/problem+json: schema: ... ```. To fix: Set the targeted value to one of the allowed values: application/problem+xml, application/problem+json. This rule is evaluated at the JSONPath `$.paths.[*].responses[?(@property.match(/^(4|5|default)/))].content.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-error-use-problem-type-2: title: Response Error Use Problem Type 2 reference: https://spotlight-rules.com/spec/rules/openapi/response-error-use-problem-type-2/ description: Every error response SHOULD support RFC 7807. message: Every error response SHOULD support RFC 7807. severity: info given: $.paths...responses[?(@property.match(/^(4|5)/))].content.*~ then: function: enumeration functionOptions: values: - application/problem+xml - application/problem+json tags: - format:openapi - spec:paths - spec:responses - spec:media-types - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-error-use-problem-type-2'' (Response Error Use Problem Type 2). Requirement: Every error response SHOULD support RFC 7807. To fix: Set the targeted value to one of the allowed values: application/problem+xml, application/problem+json. This rule is evaluated at the JSONPath `$.paths...responses[?(@property.match(/^(4|5)/))].content.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-get-codes-allowed: title: Response Get Codes Allowed reference: https://spotlight-rules.com/spec/rules/openapi/response-get-codes-allowed/ description: GET operations should not use status codes 201, 202, 204, 409, 412. message: GET operations should not use status codes 201, 202, 204, 409, 412. severity: info given: $.paths[*].get.responses then: field: '@key' function: pattern functionOptions: notMatch: ^(201|202|204|409|412)$ tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-get-codes-allowed'' (Response Get Codes Allowed). Requirement: GET operations should not use status codes 201, 202, 204, 409, 412. To fix: Ensure `@key` does NOT match the regular expression `^(201|202|204|409|412)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].get.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-get-define-200: title: Response Get Define 200 reference: https://spotlight-rules.com/spec/rules/openapi/response-get-define-200/ description: GET responses should have a 200 success HTTP status codes, communicating a successful response to consumers. message: GET Responses MUST Have 200 Status Codes severity: info given: $.paths.*.get.responses then: field: '200' function: truthy tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:reliability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-get-define-200'' (Response Get Define 200). Requirement: GET responses should have a 200 success HTTP status codes, communicating a successful response to consumers. To fix: Ensure `200` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*.get.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-get-must-return-200: title: Response Get Must Return 200 reference: https://spotlight-rules.com/spec/rules/openapi/response-get-must-return-200/ description: GET operations must always return 200 status code. message: GET operations must always return 200 status code. severity: info given: $.paths[*].get.responses then: - field: '200' function: truthy tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-get-must-return-200'' (Response Get Must Return 200). Requirement: GET operations must always return 200 status code. To fix: Ensure `200` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths[*].get.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-get-must-return-body: title: Response Get Must Return Body reference: https://spotlight-rules.com/spec/rules/openapi/response-get-must-return-body/ description: A `GET` operation must return a response body. message: A `GET` operation must return a response body. severity: info given: $.paths[*].get.responses[*] then: field: content function: truthy tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-get-must-return-body'' (Response Get Must Return Body). Requirement: A `GET` operation must return a response body. To fix: Ensure `content` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths[*].get.responses[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-head-codes-allowed: title: Response Head Codes Allowed reference: https://spotlight-rules.com/spec/rules/openapi/response-head-codes-allowed/ description: HEAD operations should not return 201, 202, 204, 409, 412 status codes. message: HEAD operations should not return 201, 202, 204, 409, 412 status codes. severity: info given: $.paths[*].head.responses then: field: '@key' function: pattern functionOptions: notMatch: ^(201|202|204|409|412)$ tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-head-codes-allowed'' (Response Head Codes Allowed). Requirement: HEAD operations should not return 201, 202, 204, 409, 412 status codes. To fix: Ensure `@key` does NOT match the regular expression `^(201|202|204|409|412)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].head.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-head-must-not-return-body: title: Response Head Must Not Return Body reference: https://spotlight-rules.com/spec/rules/openapi/response-head-must-not-return-body/ description: HEAD operations should not return a response body for success. message: HEAD operations should not return a response body for success. severity: info given: $.paths.*.head.responses[200].content then: function: falsy tags: - format:openapi - spec:paths - spec:operations - spec:responses - spec:media-types - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-head-must-not-return-body'' (Response Head Must Not Return Body). Requirement: HEAD operations should not return a response body for success. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.*.head.responses[200].content` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-header-names-pascal-case: title: Response Header Names Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/response-header-names-pascal-case/ description: Headers should be pascal-case. See Italian recommendation RAC_REST_NAME_003. message: 'Header {{error}}: {{path}}' severity: info given: - $.[responses][*].headers.*~ then: function: casing functionOptions: type: pascal separator: char: '-' tags: - format:openapi - spec:responses - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-header-names-pascal-case'' (Response Header Names Pascal Case). Requirement: Headers should be pascal-case. See Italian recommendation RAC_REST_NAME_003. To fix: Rename the targeted key or value to PascalCase (e.g. `UserName`) at each matching location, updating every reference to it. This rule is evaluated at the JSONPath `$.[responses][*].headers.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-header-no-x-prefix: title: Response Header No X Prefix reference: https://spotlight-rules.com/spec/rules/openapi/response-header-no-x-prefix/ description: '''HTTP'' headers SHOULD NOT start with ''X-'' RFC6648.' message: HTTP response header SHOULD NOT start with 'X-' in {{path}} severity: info given: - $.[responses][*].headers.*~ then: function: pattern functionOptions: match: /^([^x]|.[^-])|RateLimit-/i tags: - format:openapi - spec:responses - spec:headers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-header-no-x-prefix'' (Response Header No X Prefix). Requirement: ''HTTP'' headers SHOULD NOT start with ''X-'' RFC6648. To fix: Ensure the targeted value matches the regular expression `/^([^x]|.[^-])|RateLimit-/i`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.[responses][*].headers.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-keys-snake-case: title: Response Keys Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/response-keys-snake-case/ description: response key must be snake cased (e.g. snake_case). message: '{{error}}' severity: info given: $.components['responses'].*~ then: function: digitalocean-ensureSnakeCaseWithDigits tags: - format:openapi - spec:responses - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-keys-snake-case'' (Response Keys Snake Case). Requirement: response key must be snake cased (e.g. snake_case). This rule is evaluated at the JSONPath `$.components[''responses''].*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-location-header-only-on-201: title: Response Location Header Only On 201 reference: https://spotlight-rules.com/spec/rules/openapi/response-location-header-only-on-201/ description: Location header MUST NOT be present in non-201 responses. message: Location header MUST NOT be present in non-201 responses. severity: info given: $.paths[*][*].responses[?(@property !== '201')].headers then: field: Location function: falsy tags: - format:openapi - spec:paths - spec:responses - spec:headers - experience:consistency - experience:error-handling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-location-header-only-on-201'' (Response Location Header Only On 201). Requirement: Location header MUST NOT be present in non-201 responses. To fix: Ensure `Location` is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths[*][*].responses[?(@property !== ''201'')].headers` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-must-use-json-content-type: title: Response Must Use JSON Content Type reference: https://spotlight-rules.com/spec/rules/openapi/response-must-use-json-content-type/ description: API responses should use application/json as the primary content type. Analysis of 773 specs shows application/json is used by 92% of APIs, making it the universal standard for modern REST APIs. message: Response MUST Use application/json Content Type severity: info given: $.paths.*[get,post,put,patch,delete].responses[*].content then: field: application/json function: truthy tags: - format:openapi - spec:paths - spec:operations - spec:responses - spec:media-types - experience:consistency - experience:usability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-must-use-json-content-type'' (Response Must Use JSON Content Type). Requirement: API responses should use application/json as the primary content type. Analysis of 773 specs shows application/json is used by 92% of APIs, making it the universal standard for modern REST APIs. To fix: Ensure `application/json` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths.*[get,post,put,patch,delete].responses[*].content` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-names-pascal-case: title: Response Names Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/response-names-pascal-case/ description: Response names SHOULD be written in PascalCase. message: '{{property}} is not PascalCase: {{error}}' severity: info given: $.components.responses.*~ then: function: pattern functionOptions: match: ^[A-Z][a-zA-Z0-9]*$ tags: - format:openapi - spec:responses - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-names-pascal-case'' (Response Names Pascal Case). Requirement: Response names SHOULD be written in PascalCase. To fix: Ensure the targeted value matches the regular expression `^[A-Z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.components.responses.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-no-operational-header-in-spec: title: Response No Operational Header In Spec reference: https://spotlight-rules.com/spec/rules/openapi/response-no-operational-header-in-spec/ description: Access-Control-*, Content-Type, and Accept Headers SHOULD NOT be specified explicitly in a spec as it an operational concern. message: Access-Control-*, Content-Type, and Accept Headers SHOULD NOT be specified explicitly in a spec as it an operational concern. severity: info given: $.paths[*][*].responses[*].headers then: function: pattern functionOptions: notMatch: ^(Access-Control-.*|Content-Type|Accept)$ tags: - format:openapi - spec:paths - spec:responses - spec:headers - topic:cors - experience:consistency - experience:governance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-no-operational-header-in-spec'' (Response No Operational Header In Spec). Requirement: Access-Control-*, Content-Type, and Accept Headers SHOULD NOT be specified explicitly in a spec as it an operational concern. To fix: Ensure the targeted value does NOT match the regular expression `^(Access-Control-.*|Content-Type|Accept)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*][*].responses[*].headers` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-options-codes-allowed: title: Response Options Codes Allowed reference: https://spotlight-rules.com/spec/rules/openapi/response-options-codes-allowed/ description: OPTIONS operations should not return 201, 202, 409, 412 status codes. message: OPTIONS operations should not return 201, 202, 409, 412 status codes. severity: info given: $.paths[*].options.responses then: field: '@key' function: pattern functionOptions: notMatch: ^(201|202|409|412)$ tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-options-codes-allowed'' (Response Options Codes Allowed). Requirement: OPTIONS operations should not return 201, 202, 409, 412 status codes. To fix: Ensure `@key` does NOT match the regular expression `^(201|202|409|412)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].options.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-options-must-not-return-body: title: Response Options Must Not Return Body reference: https://spotlight-rules.com/spec/rules/openapi/response-options-must-not-return-body/ description: OPTIONS operations should not return a response body for success. message: OPTIONS operations should not return a response body for success. severity: info given: $.paths.*.options.responses[200, 204].content then: function: falsy tags: - format:openapi - spec:paths - spec:operations - spec:responses - spec:media-types - experience:consistency - experience:reliability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-options-must-not-return-body'' (Response Options Must Not Return Body). Requirement: OPTIONS operations should not return a response body for success. To fix: Ensure the targeted value is absent or empty (falsy) at each matching location. This rule is evaluated at the JSONPath `$.paths.*.options.responses[200, 204].content` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-patch-codes-allowed: title: Response Patch Codes Allowed reference: https://spotlight-rules.com/spec/rules/openapi/response-patch-codes-allowed/ description: PATCH operations should not return 201 status code. message: PATCH operations should not return 201 status code. severity: info given: $.paths[*].patch.responses then: field: '@key' function: pattern functionOptions: notMatch: ^201$ tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-patch-codes-allowed'' (Response Patch Codes Allowed). Requirement: PATCH operations should not return 201 status code. To fix: Ensure `@key` does NOT match the regular expression `^201$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].patch.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-post-codes-allowed: title: Response Post Codes Allowed reference: https://spotlight-rules.com/spec/rules/openapi/response-post-codes-allowed/ description: POST operations should not return 412 status codes. message: POST operations should not return 412 status codes. severity: info given: $.paths[*].post.responses then: field: '@key' function: pattern functionOptions: notMatch: '412' tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-post-codes-allowed'' (Response Post Codes Allowed). Requirement: POST operations should not return 412 status codes. To fix: Ensure `@key` does NOT match the regular expression `412`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].post.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-post-define-201: title: Response Post Define 201 reference: https://spotlight-rules.com/spec/rules/openapi/response-post-define-201/ description: POST responses should have a 201 success HTTP status codes, communicating a success created response to consumers. message: POST Responses MUST Have 201 Status Codes severity: info given: $.paths[*].post.responses then: field: '201' function: truthy tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:reliability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-post-define-201'' (Response Post Define 201). Requirement: POST responses should have a 201 success HTTP status codes, communicating a success created response to consumers. To fix: Ensure `201` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.paths[*].post.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-post-require-201-or-202: title: Response Post Require 201 Or 202 reference: https://spotlight-rules.com/spec/rules/openapi/response-post-require-201-or-202/ description: All POST methods MUST have a 201 or 202 response. message: All POST methods MUST have a 201 or 202 response. severity: info given: - $.paths[*].post.responses then: function: trimble-operation-post-201-202-status-code formats: - oas3 tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:consistency - experience:error-handling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-post-require-201-or-202'' (Response Post Require 201 Or 202). Requirement: All POST methods MUST have a 201 or 202 response. This rule is evaluated at the JSONPath `$.paths[*].post.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-prefer-400-over-422: title: Response Prefer 400 Over 422 reference: https://spotlight-rules.com/spec/rules/openapi/response-prefer-400-over-422/ description: MUST use standard HTTP status codes [150a]. message: Prefer 400 over 422 as response code severity: info given: $.paths.*.*.responses.422 then: field: '422' function: defined tags: - format:openapi - spec:paths - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-prefer-400-over-422'' (Response Prefer 400 Over 422). Requirement: MUST use standard HTTP status codes [150a]. To fix: Ensure `422` is defined at each matching location. This rule is evaluated at the JSONPath `$.paths.*.*.responses.422` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-put-codes-allowed: title: Response Put Codes Allowed reference: https://spotlight-rules.com/spec/rules/openapi/response-put-codes-allowed/ description: PUT operations should not return 200 or 201 status codes. message: PUT operations should not return 200 or 201 status codes. severity: info given: $.paths[*].put.responses then: field: '@key' function: pattern functionOptions: notMatch: ^(200|201)$ tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-put-codes-allowed'' (Response Put Codes Allowed). Requirement: PUT operations should not return 200 or 201 status codes. To fix: Ensure `@key` does NOT match the regular expression `^(200|201)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.paths[*].put.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-success-use-hal-json: title: Response Success Use HAL JSON reference: https://spotlight-rules.com/spec/rules/openapi/response-success-use-hal-json/ description: All 2xx success responses MUST use the `application/hal+json` media type. message: 'Success response documents MUST use the application/hal+json media type: {{error}}' severity: info given: $.paths..responses[?( @property >= 200 && @property < 300 && @property != 204)].content[*]~ then: function: enumeration functionOptions: values: - application/hal+json formats: - oas3 tags: - format:openapi - spec:paths - spec:responses - spec:media-types - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-success-use-hal-json'' (Response Success Use HAL JSON). Requirement: All 2xx success responses MUST use the `application/hal+json` media type. To fix: Set the targeted value to one of the allowed values: application/hal+json. This rule is evaluated at the JSONPath `$.paths..responses[?( @property >= 200 && @property < 300 && @property != 204)].content[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-use-json-api: title: Response Use JSON API reference: https://spotlight-rules.com/spec/rules/openapi/response-use-json-api/ description: All responses MUST use the JSON:API `application/vnd.api+json` media type. message: 'Response documents MUST use the application/vnd.api+json (JSON:API) media type: {{error}}' severity: info given: $.paths..responses[?( @property >= 200 && @property < 600 && @property != 204)].content[*]~ then: function: enumeration functionOptions: values: - application/vnd.api+json formats: - oas3 tags: - format:openapi - spec:paths - spec:responses - spec:media-types - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-use-json-api'' (Response Use JSON API). Requirement: All responses MUST use the JSON:API `application/vnd.api+json` media type. To fix: Set the targeted value to one of the allowed values: application/vnd.api+json. This rule is evaluated at the JSONPath `$.paths..responses[?( @property >= 200 && @property < 600 && @property != 204)].content[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-use-standard-mime-types: title: Response Use Standard Mime Types reference: https://spotlight-rules.com/spec/rules/openapi/response-use-standard-mime-types/ description: MIME types MUST be standard (application/json, application/problem+json, application/problem+xml) or use custom format application/vnd.*. message: MIME types MUST be standard (application/json, application/problem+json, application/problem+xml) or use custom format application/vnd.*. severity: info given: $.paths[*][*].responses[*].content.*~ then: function: pattern functionOptions: match: ^application/(json|problem\+json|problem\+xml|vnd\..*)$ tags: - format:openapi - spec:paths - spec:responses - spec:media-types - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-use-standard-mime-types'' (Response Use Standard Mime Types). Requirement: MIME types MUST be standard (application/json, application/problem+json, application/problem+xml) or use custom format application/vnd.*. To fix: Ensure the targeted value matches the regular expression `^application/(json|problem\+json|problem\+xml|vnd\..*)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.paths[*][*].responses[*].content.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-use-standard-status-codes: title: Response Use Standard Status Codes reference: https://spotlight-rules.com/spec/rules/openapi/response-use-standard-status-codes/ description: MUST use standard HTTP status codes [150a]. message: '{{property}} is not a standardized response code' severity: info given: $.paths.*.*.responses.*~ then: function: enumeration functionOptions: values: - '100' - '101' - '200' - '201' - '202' - '203' - '204' - '205' - '206' - '207' - '300' - '301' - '302' - '303' - '304' - '305' - '307' - '400' - '401' - '402' - '403' - '404' - '405' - '406' - '407' - '408' - '409' - '410' - '411' - '412' - '413' - '414' - '415' - '416' - '417' - '422' - '423' - '426' - '428' - '429' - '431' - '500' - '501' - '502' - '503' - '504' - '505' - '511' - default tags: - format:openapi - spec:paths - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-use-standard-status-codes'' (Response Use Standard Status Codes). Requirement: MUST use standard HTTP status codes [150a]. To fix: Set the targeted value to one of the allowed values: 100, 101, 200, 201, 202, 203, 204, 205, 206, 207, 300, 301, 302, 303, 304, 305, 307, 400, 401, 402, 403, 404, 405, 406, 407, 408, 409, 410, 411, 412, 413, 414, 415, 416, 417, 422, 423, 426, 428, 429, 431, 500, 501, 502, 503, 504, 505, 511, default. This rule is evaluated at the JSONPath `$.paths.*.*.responses.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-use-standard-status-codes-2: title: Response Use Standard Status Codes 2 reference: https://spotlight-rules.com/spec/rules/openapi/response-use-standard-status-codes-2/ description: An API MUST return HTTP response codes in conformance with RFC-2616 and common usage. message: An API MUST return HTTP response codes in conformance with RFC-2616 and common usage. severity: info given: $.paths...responses.*~ then: function: enumeration functionOptions: values: - '200' - '201' - '202' - '204' - '400' - '401' - '403' - '404' - '405' - '406' - '409' - '412' - '415' - '428' - '429' - '500' tags: - format:openapi - spec:paths - spec:responses - experience:error-handling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-use-standard-status-codes-2'' (Response Use Standard Status Codes 2). Requirement: An API MUST return HTTP response codes in conformance with RFC-2616 and common usage. To fix: Set the targeted value to one of the allowed values: 200, 201, 202, 204, 400, 401, 403, 404, 405, 406, 409, 412, 415, 428, 429, 500. This rule is evaluated at the JSONPath `$.paths...responses.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-response-write-require-content-type: title: Response Write Require Content Type reference: https://spotlight-rules.com/spec/rules/openapi/response-write-require-content-type/ description: All API responses MUST include the Content-Type header in all responses. message: '{{error}}' severity: info given: - $.paths[*].post.responses - $.paths[*].put.responses then: function: trimble-check-for-content-type-in-put-and-post-responses tags: - format:openapi - spec:paths - spec:operations - spec:responses - experience:consistency - experience:data-modeling prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''response-write-require-content-type'' (Response Write Require Content Type). Requirement: All API responses MUST include the Content-Type header in all responses. This rule is evaluated at the JSONPath `$.paths[*].post.responses | $.paths[*].put.responses` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-array-property-require-items: title: Schema Array Property Require Items reference: https://spotlight-rules.com/spec/rules/openapi/schema-array-property-require-items/ description: Schema properties that are of the type array must have an items property defined. message: Schema Array Properties MUST Have Items severity: info given: $.components.schemas.*.properties[?(@.type=="array")] then: field: items function: truthy tags: - format:openapi - spec:schemas - spec:components - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-array-property-require-items'' (Schema Array Property Require Items). Requirement: Schema properties that are of the type array must have an items property defined. To fix: Ensure `items` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.components.schemas.*.properties[?(@.type=="array")]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-array-property-typed-items: title: Schema Array Property Typed Items reference: https://spotlight-rules.com/spec/rules/openapi/schema-array-property-typed-items/ description: Array properties must have an items attribute with a type. message: '{{error}}' severity: info given: $..*.properties[*] then: function: digitalocean-ensureAllArraysHaveItemTypes tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-array-property-typed-items'' (Schema Array Property Typed Items). Requirement: Array properties must have an items attribute with a type. This rule is evaluated at the JSONPath `$..*.properties[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-boolean-no-prefix: title: Schema Boolean No Prefix reference: https://spotlight-rules.com/spec/rules/openapi/schema-boolean-no-prefix/ description: Boolean properties SHOULD NOT use is, has, or another prefix. message: Boolean properties SHOULD NOT use is, has, or another prefix. severity: info given: $..properties[?(@ && @.type == 'boolean')]~ then: function: pattern functionOptions: notMatch: ^(is|has|was|will|needs|uses|should|can)([A-Z]|$).* formats: - oas3 tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-boolean-no-prefix'' (Schema Boolean No Prefix). Requirement: Boolean properties SHOULD NOT use is, has, or another prefix. To fix: Ensure the targeted value does NOT match the regular expression `^(is|has|was|will|needs|uses|should|can)([A-Z]|$).*`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..properties[?(@ && @.type == ''boolean'')]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-created-datetime-must-be-date-time: title: Schema Created Datetime Must Be Date Time reference: https://spotlight-rules.com/spec/rules/openapi/schema-created-datetime-must-be-date-time/ description: createdDateTime MUST use a data type of 'string' with the format 'date-time'. message: createdDateTime MUST use a data type of 'string' with the format 'date-time'. severity: info given: $..properties.createdDateTime then: - field: type function: pattern functionOptions: match: ^string$ - field: format function: truthy - field: format function: pattern functionOptions: match: ^date-time$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-created-datetime-must-be-date-time'' (Schema Created Datetime Must Be Date Time). Requirement: createdDateTime MUST use a data type of ''string'' with the format ''date-time''. To fix: Ensure `type` matches the regular expression `^string$`; rewrite any value that does not. Also: Ensure `format` is present and non-empty at each matching location. Also: Ensure `format` matches the regular expression `^date-time$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..properties.createdDateTime` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-createdby-property-must-be-string: title: Schema Createdby Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-createdby-property-must-be-string/ description: createdBy MUST use a data type of 'string'. message: createdBy MUST use a data type of 'string'. severity: info given: $..[?(@property === "createdBy")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-createdby-property-must-be-string'' (Schema Createdby Property Must Be String). Requirement: createdBy MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "createdBy")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-date-time-property-require-format: title: Schema Date Time Property Require Format reference: https://spotlight-rules.com/spec/rules/openapi/schema-date-time-property-require-format/ description: Date/time string properties (createdAt, updated_at, *_date, timestamp, …) should declare a format such as date-time (RFC 3339) so the value is unambiguous and machine-validatable. message: Date/time string property should declare a format (e.g. date-time). given: $..properties[?( @property.match(/(_at$|_date$|_time$|At$|Date$|Time$|timestamp)/i) && @.type == 'string' )] severity: info then: field: format function: truthy tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-date-time-property-require-format'' (Schema Date Time Property Require Format). Requirement: Date/time string properties (createdAt, updated_at, *_date, timestamp, …) should declare a format such as date-time (RFC 3339) so the value is unambiguous and machine-validatable. To fix: Ensure `format` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$..properties[?( @property.match(/(_at$|_date$|_time$|At$|Date$|Time$|timestamp)/i) && @.type == ''string'' )]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-definition-camel-case: title: Schema Definition Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-definition-camel-case/ description: Schema definitions MUST follow camelCase. message: '{{property}} schema definition is not camelCase: {{error}}' severity: info given: $.definitions[*]~ then: function: pattern functionOptions: match: ^[a-z][a-zA-Z0-9]*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-definition-camel-case'' (Schema Definition Camel Case). Requirement: Schema definitions MUST follow camelCase. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-definition-constant-case: title: Schema Definition Constant Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-definition-constant-case/ description: Schema definitions MUST follow CONSTANT_CASE (screaming snake_case). message: '{{property}} schema definition is not CONSTANT_CASE: {{error}}' severity: info given: $.definitions[*]~ then: function: pattern functionOptions: match: ^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-definition-constant-case'' (Schema Definition Constant Case). Requirement: Schema definitions MUST follow CONSTANT_CASE (screaming snake_case). To fix: Ensure the targeted value matches the regular expression `^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-definition-kebab-case: title: Schema Definition Kebab Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-definition-kebab-case/ description: Schema definitions MUST follow kebab-case. message: '{{property}} schema definition is not kebab-case: {{error}}' severity: info given: $.definitions[*]~ then: function: pattern functionOptions: match: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-definition-kebab-case'' (Schema Definition Kebab Case). Requirement: Schema definitions MUST follow kebab-case. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-definition-pascal-case: title: Schema Definition Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-definition-pascal-case/ description: Schema definitions MUST follow PascalCase. message: '{{property}} schema definition is not PascalCase: {{error}}' severity: info given: $.definitions[*]~ then: function: pattern functionOptions: match: ^[A-Z][a-zA-Z0-9]*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-definition-pascal-case'' (Schema Definition Pascal Case). Requirement: Schema definitions MUST follow PascalCase. To fix: Ensure the targeted value matches the regular expression `^[A-Z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-definition-snake-case: title: Schema Definition Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-definition-snake-case/ description: Schema definitions MUST follow snake_case. message: '{{property}} schema definition is not snake_case: {{error}}' severity: info given: $.definitions[*]~ then: function: pattern functionOptions: match: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-definition-snake-case'' (Schema Definition Snake Case). Requirement: Schema definitions MUST follow snake_case. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-z0-9]*(_[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-deletedby-property-must-be-string: title: Schema Deletedby Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-deletedby-property-must-be-string/ description: deletedBy MUST use a data type of 'string'. message: deletedBy MUST use a data type of 'string'. severity: info given: $..[?(@property === "deletedBy")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-deletedby-property-must-be-string'' (Schema Deletedby Property Must Be String). Requirement: deletedBy MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "deletedBy")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-description-max-length: title: Schema Description Max Length reference: https://spotlight-rules.com/spec/rules/openapi/schema-description-max-length/ description: Schema should have a length limit applied, restricting how long schema descriptions can be, helping keep them concise and consistent. message: Schema Description MUST be Less Than 250 Characters severity: info given: $.components.schemas.* then: field: description function: length functionOptions: max: 250 tags: - format:openapi - spec:schemas - spec:components - experience:documentation - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-description-max-length'' (Schema Description Max Length). Requirement: Schema should have a length limit applied, restricting how long schema descriptions can be, helping keep them concise and consistent. To fix: Ensure the length of `description` is at most 250. This rule is evaluated at the JSONPath `$.components.schemas.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-description-property-must-be-string: title: Schema Description Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-description-property-must-be-string/ description: description MUST use a data type of 'string'. message: description MUST use a data type of 'string'. severity: info given: $..[?(@property === "description")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-description-property-must-be-string'' (Schema Description Property Must Be String). Requirement: description MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "description")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-enum-not-empty: title: Schema Enum Not Empty reference: https://spotlight-rules.com/spec/rules/openapi/schema-enum-not-empty/ description: An enum should declare at least one value — an empty enum permits nothing and is almost always a mistake. message: enum should not be empty. given: $..enum severity: info then: function: schema functionOptions: schema: type: array minItems: 1 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-enum-not-empty'' (Schema Enum Not Empty). Requirement: An enum should declare at least one value — an empty enum permits nothing and is almost always a mistake. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$..enum` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-fingerprint-property-must-be-string: title: Schema Fingerprint Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-fingerprint-property-must-be-string/ description: Fingerprint values MUST use a data type of `string`. message: Fingerprint values MUST use a data type of `string`. severity: info given: $..[?(@property === "fingerprint")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-fingerprint-property-must-be-string'' (Schema Fingerprint Property Must Be String). Requirement: Fingerprint values MUST use a data type of `string`. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "fingerprint")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-id-property-must-be-string: title: Schema ID Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-id-property-must-be-string/ description: id SHOULD use a data type of 'string'. message: id SHOULD use a data type of 'string'. severity: info given: $..[?(@property === "id")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-id-property-must-be-string'' (Schema ID Property Must Be String). Requirement: id SHOULD use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "id")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-integer-format-allowed-values: title: Schema Integer Format Allowed Values reference: https://spotlight-rules.com/spec/rules/openapi/schema-integer-format-allowed-values/ description: To improve interoperability, integer and number formats are constrained to a shared subset. See recommendation RAC_REST_FORMAT_004. message: Type format is "{{value}}", expected one of [int32, int64]. {{path}} severity: info given: '$.[?(@.type=="integer")] ' then: field: format function: enumeration functionOptions: values: - int32 - int64 formats: - oas3 tags: - format:openapi - spec:document - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-integer-format-allowed-values'' (Schema Integer Format Allowed Values). Requirement: To improve interoperability, integer and number formats are constrained to a shared subset. See recommendation RAC_REST_FORMAT_004. To fix: Set `format` to one of the allowed values: int32, int64. This rule is evaluated at the JSONPath `$.[?(@.type=="integer")] ` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-integer-require-format: title: Schema Integer Require Format reference: https://spotlight-rules.com/spec/rules/openapi/schema-integer-require-format/ description: Schema of type number or integer must specify a format to express the associated datatype, eg. `int32`, `int64`, ... You can express similar requirements using the `minimum` and `maximum` properties. See recommendation RAC_REST_FORMAT_004. message: Schema of type number or integer must specify a format. {{path}} severity: info given: '$.[?(@.type=="integer")] ' then: field: format function: truthy formats: - oas3 tags: - format:openapi - spec:document - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-integer-require-format'' (Schema Integer Require Format). Requirement: Schema of type number or integer must specify a format to express the associated datatype, eg. `int32`, `int64`, ... You can express similar requirements using the `minimum` and `maximum` properties. See recommendation RAC_REST_FORMAT_004. To fix: Ensure `format` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.[?(@.type=="integer")] ` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-keys-snake-case: title: Schema Keys Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-keys-snake-case/ description: schema key must be snake cased (e.g. snake_case). message: '{{error}}' severity: info given: $.components['schemas'].*~ then: function: digitalocean-ensureSnakeCaseWithDigits tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-keys-snake-case'' (Schema Keys Snake Case). Requirement: schema key must be snake cased (e.g. snake_case). This rule is evaluated at the JSONPath `$.components[''schemas''].*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-modified-datetime-must-be-date-time: title: Schema Modified Datetime Must Be Date Time reference: https://spotlight-rules.com/spec/rules/openapi/schema-modified-datetime-must-be-date-time/ description: modifiedDateTime MUST use a data type of 'string' with the format 'date-time'. message: modifiedDateTime MUST use a data type of 'string' with the format 'date-time'. severity: info given: $..properties.modifiedDateTime then: - field: type function: pattern functionOptions: match: ^string$ - field: format function: truthy - field: format function: pattern functionOptions: match: ^date-time$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-modified-datetime-must-be-date-time'' (Schema Modified Datetime Must Be Date Time). Requirement: modifiedDateTime MUST use a data type of ''string'' with the format ''date-time''. To fix: Ensure `type` matches the regular expression `^string$`; rewrite any value that does not. Also: Ensure `format` is present and non-empty at each matching location. Also: Ensure `format` matches the regular expression `^date-time$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..properties.modifiedDateTime` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-modifiedby-property-must-be-string: title: Schema Modifiedby Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-modifiedby-property-must-be-string/ description: modifiedBy MUST use a data type of 'string'. message: modifiedBy MUST use a data type of 'string'. severity: info given: $..[?(@property === "modifiedBy")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-modifiedby-property-must-be-string'' (Schema Modifiedby Property Must Be String). Requirement: modifiedBy MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "modifiedBy")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-name-max-length: title: Schema Name Max Length reference: https://spotlight-rules.com/spec/rules/openapi/schema-name-max-length/ description: Schema should have a length limit applied keeping the names of schema consistent across APIs. message: Schema Names MUST Be Less Than 25 Characters severity: info given: $.components.schemas then: field: '@key' function: length functionOptions: max: 25 tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-name-max-length'' (Schema Name Max Length). Requirement: Schema should have a length limit applied keeping the names of schema consistent across APIs. To fix: Ensure the length of `@key` is at most 25. This rule is evaluated at the JSONPath `$.components.schemas` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-name-property-must-be-string: title: Schema Name Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-name-property-must-be-string/ description: name MUST use a data type of 'string'. message: name MUST use a data type of 'string'. severity: info given: $..[?(@property === "name")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-name-property-must-be-string'' (Schema Name Property Must Be String). Requirement: name MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "name")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-names-pascal-case: title: Schema Names Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-names-pascal-case/ description: Schema names SHOULD be written in PascalCase. message: '{{property}} is not PascalCase: {{error}}' severity: info given: $.components.schemas.*~ then: function: pattern functionOptions: match: ^[A-Z][a-zA-Z0-9]*$ tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-names-pascal-case'' (Schema Names Pascal Case). Requirement: Schema names SHOULD be written in PascalCase. To fix: Ensure the targeted value matches the regular expression `^[A-Z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.components.schemas.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-number-format-allowed-values: title: Schema Number Format Allowed Values reference: https://spotlight-rules.com/spec/rules/openapi/schema-number-format-allowed-values/ description: To improve interoperability, integer and number formats are constrained to a shared subset. See recommendation RAC_REST_FORMAT_004. message: Type format is "{{value}}", expected one of [decimal32, decimal64, decimal128, float, double]. {{path}} severity: info given: '$.[?(@.type=="number")] ' then: field: format function: enumeration functionOptions: values: - decimal32 - decimal64 - float - double - decimal128 formats: - oas3 tags: - format:openapi - spec:document - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-number-format-allowed-values'' (Schema Number Format Allowed Values). Requirement: To improve interoperability, integer and number formats are constrained to a shared subset. See recommendation RAC_REST_FORMAT_004. To fix: Set `format` to one of the allowed values: decimal32, decimal64, float, double, decimal128. This rule is evaluated at the JSONPath `$.[?(@.type=="number")] ` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-number-require-format: title: Schema Number Require Format reference: https://spotlight-rules.com/spec/rules/openapi/schema-number-require-format/ description: Schema of type number or integer must specify a format to express the associated datatype, eg. `int32`, `int64`, ... You can express similar requirements using the `minimum` and `maximum` properties. See recommendation RAC_REST_FORMAT_004. message: Schema of type number or integer must specify a format. {{path}} severity: info given: $.[?(@.type=="number")] then: field: format function: truthy formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-number-require-format'' (Schema Number Require Format). Requirement: Schema of type number or integer must specify a format to express the associated datatype, eg. `int32`, `int64`, ... You can express similar requirements using the `minimum` and `maximum` properties. See recommendation RAC_REST_FORMAT_004. To fix: Ensure `format` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.[?(@.type=="number")]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-orgid-property-must-be-string: title: Schema Orgid Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-orgid-property-must-be-string/ description: orgId MUST use a data type of 'string'. message: orgId MUST use a data type of 'string'. severity: info given: $..[?(@property === "orgId")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-orgid-property-must-be-string'' (Schema Orgid Property Must Be String). Requirement: orgId MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "orgId")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-camel-case: title: Schema Property Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-camel-case/ description: Schema properties MUST follow camelCase. message: '{{property}} schema property is not camelCase: {{error}}' severity: info given: $.definitions..properties[*]~ then: function: pattern functionOptions: match: ^[a-z][a-zA-Z0-9]*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-camel-case'' (Schema Property Camel Case). Requirement: Schema properties MUST follow camelCase. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions..properties[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-camel-case-3: title: Schema Property Camel Case 3 reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-camel-case-3/ description: Schema property names should use camelCase. Analysis of 773 specs shows camelCase is the dominant convention at 65% (12958 properties), followed by snake_case at 33% (6661 properties). message: Schema Properties MUST Use camelCase severity: info given: $.components.schemas[*].properties then: function: pattern functionOptions: match: ^[a-z][a-zA-Z0-9]*$ tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-camel-case-3'' (Schema Property Camel Case 3). Requirement: Schema property names should use camelCase. Analysis of 773 specs shows camelCase is the dominant convention at 65% (12958 properties), followed by snake_case at 33% (6661 properties). To fix: Ensure the targeted value matches the regular expression `^[a-z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.components.schemas[*].properties` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-constant-case: title: Schema Property Constant Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-constant-case/ description: Schema properties MUST follow CONSTANT_CASE (screaming snake_case). message: '{{property}} schema property is not CONSTANT_CASE: {{error}}' severity: info given: $.definitions..properties[*]~ then: function: pattern functionOptions: match: ^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-constant-case'' (Schema Property Constant Case). Requirement: Schema properties MUST follow CONSTANT_CASE (screaming snake_case). To fix: Ensure the targeted value matches the regular expression `^[A-Z][A-Z0-9]*(_[A-Z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions..properties[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-description-max-length: title: Schema Property Description Max Length reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-description-max-length/ description: Schema property descriptions should have a length limit applied, applying constraints to writing descriptions, and keeping consistent across APIs. message: Schema Properties Description MUST Have 250 Characters severity: info given: $.components.schemas.*.properties[?(@.type == 'string')] then: field: description function: length functionOptions: max: 250 tags: - format:openapi - spec:schemas - spec:components - experience:documentation - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-description-max-length'' (Schema Property Description Max Length). Requirement: Schema property descriptions should have a length limit applied, applying constraints to writing descriptions, and keeping consistent across APIs. To fix: Ensure the length of `description` is at most 250. This rule is evaluated at the JSONPath `$.components.schemas.*.properties[?(@.type == ''string'')]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-enum-upper-snake-case: title: Schema Property Enum Upper Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-enum-upper-snake-case/ description: Schema property enumerators are consistent casing, keeping all entries upper snake case, and consistent across all APIs. message: Schema Property Enum MUST Be Upper Snake Case severity: info given: $.components.schemas.*.properties.*.enum.* then: function: pattern functionOptions: match: ^[A-Z]+(?:_[A-Z]+)*$ tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-enum-upper-snake-case'' (Schema Property Enum Upper Snake Case). Requirement: Schema property enumerators are consistent casing, keeping all entries upper snake case, and consistent across all APIs. To fix: Ensure the targeted value matches the regular expression `^[A-Z]+(?:_[A-Z]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.components.schemas.*.properties.*.enum.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-kebab-case: title: Schema Property Kebab Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-kebab-case/ description: Schema properties MUST follow kebab-case. message: '{{property}} schema property is not kebab-case: {{error}}' severity: info given: $.definitions..properties[*]~ then: function: pattern functionOptions: match: ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-kebab-case'' (Schema Property Kebab Case). Requirement: Schema properties MUST follow kebab-case. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-z0-9]*(-[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions..properties[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-names-camel-case: title: Schema Property Names Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-names-camel-case/ description: Schema property names are camel case, providing consistent casing across all the schema properties used by APIs. message: Schema Property Names MUST Be camelCase. severity: info given: $.components.schemas.*.properties then: - field: '@key' function: pattern functionOptions: notMatch: ^[A-Z][a-z0-9]*[A-Z0-9][a-z0-9]+[A-Za-z0-9]*$ tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-names-camel-case'' (Schema Property Names Camel Case). Requirement: Schema property names are camel case, providing consistent casing across all the schema properties used by APIs. To fix: Ensure `@key` does NOT match the regular expression `^[A-Z][a-z0-9]*[A-Z0-9][a-z0-9]+[A-Za-z0-9]*$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.components.schemas.*.properties` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-names-camel-case-2: title: Schema Property Names Camel Case 2 reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-names-camel-case-2/ description: Property names and acronyms MUST be in camelCase. message: Property names and acronyms MUST be in camelCase. severity: info given: $..properties.*~ then: function: pattern functionOptions: match: ^[a-z][a-z0-9]*(([A-Z]{2}|[A-Z])[a-z0-9]+)*$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-names-camel-case-2'' (Schema Property Names Camel Case 2). Requirement: Property names and acronyms MUST be in camelCase. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-z0-9]*(([A-Z]{2}|[A-Z])[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..properties.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-names-length-limit: title: Schema Property Names Length Limit reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-names-length-limit/ description: Schema property names have a length restriction applied, keeping names consistent, and avoiding being too long. message: Schema Properties Name Length severity: info given: $.components.schemas.*.properties then: field: '@key' function: length functionOptions: max: 25 tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-names-length-limit'' (Schema Property Names Length Limit). Requirement: Schema property names have a length restriction applied, keeping names consistent, and avoiding being too long. To fix: Ensure the length of `@key` is at most 25. This rule is evaluated at the JSONPath `$.components.schemas.*.properties` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-no-language-keywords: title: Schema Property No Language Keywords reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-no-language-keywords/ description: Names that may conflict with keywords in common programming languages SHOULD NOT be used. message: Names that may conflict with keywords in common programming languages SHOULD NOT be used. severity: info given: $..properties.*~ then: function: pattern functionOptions: notMatch: ^(abstract|for|new|switch|assert|default|goto|package|synchronized|boolean|do|if|private|this|break|double|implements|throw|byte|else|import|public|throws|case|enum|instanceof|return|transient|catch|extends|int|short|try|char|final|interface|static|void|class|finally|long|volatile|const|float|native|super|while)$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-no-language-keywords'' (Schema Property No Language Keywords). Requirement: Names that may conflict with keywords in common programming languages SHOULD NOT be used. To fix: Ensure the targeted value does NOT match the regular expression `^(abstract|for|new|switch|assert|default|goto|package|synchronized|boolean|do|if|private|this|break|double|implements|throw|byte|else|import|public|throws|case|enum|instanceof|return|transient|catch|extends|int|short|try|char|final|interface|static|void|class|finally|long|volatile|const|float|native|super|while)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..properties.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-no-prepositions: title: Schema Property No Prepositions reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-no-prepositions/ description: Property names SHOULD NOT include prepositions (e.g. "for", "during", "at", etc.). message: Property names SHOULD NOT include prepositions (e.g. severity: info given: $..properties.*~ then: function: pattern functionOptions: notMatch: (^(about|above|across|after|against|among|around|at|before|behind|below|beside|between|down|during|for|from|in|inside|into|near|of|off|on|out|over|through|to|toward|under|up|with|as|but|like|since|than|till|unlike|until|upon|within|without)([A-Z]|$)|.*(About|Above|Across|After|Against|Among|Around|At|Before|Behind|Below|Beside|Between|Down|During|For|From|In|Inside|Into|Near|Of|Off|On|Out|Over|Through|To|Toward|Under|Up|With|As|But|Like|Since|Than|Till|Unlike|Until|Upon|Within|Without)([A-Z]|$)).* formats: - oas3 tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-no-prepositions'' (Schema Property No Prepositions). Requirement: Property names SHOULD NOT include prepositions (e.g. "for", "during", "at", etc.). To fix: Ensure the targeted value does NOT match the regular expression `(^(about|above|across|after|against|among|around|at|before|behind|below|beside|between|down|during|for|from|in|inside|into|near|of|off|on|out|over|through|to|toward|under|up|with|as|but|like|since|than|till|unlike|until|upon|within|without)([A-Z]|$)|.*(About|Above|Across|After|Against|Among|Around|At|Before|Behind|Below|Beside|Between|Down|During|For|From|In|Inside|Into|Near|Of|Off|On|Out|Over|Through|To|Toward|Under|Up|With|As|But|Like|Since|Than|Till|Unlike|Until|Upon|Within|Without)([A-Z]|$)).*`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..properties.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-pascal-case: title: Schema Property Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-pascal-case/ description: Schema properties MUST follow PascalCase. message: '{{property}} schema property is not PascalCase: {{error}}' severity: info given: $.definitions..properties[*]~ then: function: pattern functionOptions: match: ^[A-Z][a-zA-Z0-9]*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-pascal-case'' (Schema Property Pascal Case). Requirement: Schema properties MUST follow PascalCase. To fix: Ensure the targeted value matches the regular expression `^[A-Z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions..properties[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-require-type: title: Schema Property Require Type reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-require-type/ description: Schema properties must have a type defined. message: '{{error}}' severity: info given: $..properties.* then: function: digitalocean-ensureSchemaHasType tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-require-type'' (Schema Property Require Type). Requirement: Schema properties must have a type defined. This rule is evaluated at the JSONPath `$..properties.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-property-snake-case: title: Schema Property Snake Case reference: https://spotlight-rules.com/spec/rules/openapi/schema-property-snake-case/ description: Schema properties MUST follow snake_case. message: '{{property}} schema property is not snake_case: {{error}}' severity: info given: $.definitions..properties[*]~ then: function: pattern functionOptions: match: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$ tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-property-snake-case'' (Schema Property Snake Case). Requirement: Schema properties MUST follow snake_case. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-z0-9]*(_[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.definitions..properties[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-ref-property-must-be-string: title: Schema Ref Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-ref-property-must-be-string/ description: ref MUST use a data type of 'string'. message: ref MUST use a data type of 'string'. severity: info given: $..[?(@property === "ref")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-ref-property-must-be-string'' (Schema Ref Property Must Be String). Requirement: ref MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "ref")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-ref-property-require-format: title: Schema Ref Property Require Format reference: https://spotlight-rules.com/spec/rules/openapi/schema-ref-property-require-format/ description: Property with the name 'ref' MUST use a format 'sps-ref'. message: Property with the name 'ref' MUST use a format 'sps-ref'. severity: info given: $..properties..[?((@property=== "ref" || @property === "Ref") && @.$ref == null && @.allOf == null && @.oneOf == null && @.type != null)] then: - field: format function: truthy - field: format function: pattern functionOptions: match: ^sps-ref$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-ref-property-require-format'' (Schema Ref Property Require Format). Requirement: Property with the name ''ref'' MUST use a format ''sps-ref''. To fix: Ensure `format` is present and non-empty at each matching location. Also: Ensure `format` matches the regular expression `^sps-ref$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..properties..[?((@property=== "ref" || @property === "Ref") && @.$ref == null && @.allOf == null && @.oneOf == null && @.type != null)]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-ref-property-standard: title: Schema Ref Property Standard reference: https://spotlight-rules.com/spec/rules/openapi/schema-ref-property-standard/ description: Properties following 'sps-ref' format MUST use the standardized schema - maxLength (255), minLength(7), pattern (includes 'sps'), type (string). message: '{{property}} is not provided or not following required schema values.' severity: info given: $..[?(@property=== "format" && @ == "sps-ref")]^ then: - function: schema functionOptions: schema: type: object required: - maxLength - minLength - type - pattern properties: maxLength: type: integer minimum: 255 maximum: 255 minLength: type: integer minimum: 7 maximum: 7 type: type: string pattern: type: string - field: pattern function: pattern functionOptions: match: sps - field: type function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-ref-property-standard'' (Schema Ref Property Standard). Requirement: Properties following ''sps-ref'' format MUST use the standardized schema - maxLength (255), minLength(7), pattern (includes ''sps''), type (string). To fix: Adjust the targeted value so it conforms to the schema this rule requires. Also: Ensure `pattern` matches the regular expression `sps`; rewrite any value that does not. Also: Ensure `type` matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property=== "format" && @ == "sps-ref")]^` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-requestid-property-must-be-string: title: Schema Requestid Property Must Be String reference: https://spotlight-rules.com/spec/rules/openapi/schema-requestid-property-must-be-string/ description: requestId MUST use a data type of 'string'. message: requestId MUST use a data type of 'string'. severity: info given: $..[?(@property === "requestId")].type then: function: pattern functionOptions: match: ^string$ formats: - oas3 tags: - format:openapi - spec:schemas - topic:tracing - experience:data-modeling - experience:consistency - experience:observability prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-requestid-property-must-be-string'' (Schema Requestid Property Must Be String). Requirement: requestId MUST use a data type of ''string''. To fix: Ensure the targeted value matches the regular expression `^string$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$..[?(@property === "requestId")].type` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-require-tag-object: title: Schema Require Tag Object reference: https://spotlight-rules.com/spec/rules/openapi/schema-require-tag-object/ description: There needs to be a central tags object applied to the OpenAPI, providing central tags that can be applied across all operations within an OpenAPI. message: OpenAPIs MUST Have a Tag Object severity: info given: $ then: field: tags function: truthy tags: - format:openapi - spec:document - experience:discoverability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-require-tag-object'' (Schema Require Tag Object). Requirement: There needs to be a central tags object applied to the OpenAPI, providing central tags that can be applied across all operations within an OpenAPI. To fix: Ensure `tags` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-require-type: title: Schema Require Type reference: https://spotlight-rules.com/spec/rules/openapi/schema-require-type/ description: Schema should have a type defined, being explicit about type of data a schema describes and can be used to validate, helping standardize the type of data being made available. message: Schema MUST Have Type Property severity: info given: $.components.schemas.* then: field: type function: truthy tags: - format:openapi - spec:schemas - spec:components - experience:data-modeling - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-require-type'' (Schema Require Type). Requirement: Schema should have a type defined, being explicit about type of data a schema describes and can be used to validate, helping standardize the type of data being made available. To fix: Ensure `type` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.components.schemas.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-use-fingerprint-not-hash: title: Schema Use Fingerprint Not Hash reference: https://spotlight-rules.com/spec/rules/openapi/schema-use-fingerprint-not-hash/ description: Rather than property names refering to the implementation for 'hash' or 'hashkey', you MUST use the property name 'fingerprint'. message: '{{property}} is not using property name fingerprint.' severity: info given: $.components.schemas..properties.*~ then: function: pattern functionOptions: notMatch: ^hashkey|hashKey|hash$ formats: - oas3 tags: - format:openapi - spec:schemas - spec:components - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-use-fingerprint-not-hash'' (Schema Use Fingerprint Not Hash). Requirement: Rather than property names refering to the implementation for ''hash'' or ''hashkey'', you MUST use the property name ''fingerprint''. To fix: Ensure the targeted value does NOT match the regular expression `^hashkey|hashKey|hash$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.components.schemas..properties.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-use-id-not-identifier: title: Schema Use ID Not Identifier reference: https://spotlight-rules.com/spec/rules/openapi/schema-use-id-not-identifier/ description: Use abbreviations instead of long form names, i.e. identifier SHOULD BE id. message: Use abbreviations instead of long form names, i.e. severity: info given: $..properties.*~ then: function: pattern functionOptions: notMatch: ^identifier$ formats: - oas3 tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-use-id-not-identifier'' (Schema Use ID Not Identifier). Requirement: Use abbreviations instead of long form names, i.e. identifier SHOULD BE id. To fix: Ensure the targeted value does NOT match the regular expression `^identifier$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..properties.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-schema-use-org-not-organization: title: Schema Use Org Not Organization reference: https://spotlight-rules.com/spec/rules/openapi/schema-use-org-not-organization/ description: Use abbreviations instead of long form names, i.e. organization SHOULD BE org. message: Use abbreviations instead of long form names, i.e. severity: info given: $..properties.*~ then: function: pattern functionOptions: notMatch: (^organization([A-Z]|$)|Organization([A-Z]|$)) formats: - oas3 tags: - format:openapi - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''schema-use-org-not-organization'' (Schema Use Org Not Organization). Requirement: Use abbreviations instead of long form names, i.e. organization SHOULD BE org. To fix: Ensure the targeted value does NOT match the regular expression `(^organization([A-Z]|$)|Organization([A-Z]|$))`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$..properties.*~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-server-must-not-specify-port: title: Server Must Not Specify Port reference: https://spotlight-rules.com/spec/rules/openapi/server-must-not-specify-port/ description: Port MUST NOT be specified or required to use the API, except for 'localhost' testing in a spec. message: Port MUST NOT be specified or required to use the API, except for 'localhost' testing in a spec. severity: info given: $.servers..url then: function: pattern functionOptions: notMatch: (?!https?://localhost)(https?://.*):(\d*)\/?(.*) formats: - oas3 tags: - format:openapi - spec:servers - experience:usability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''server-must-not-specify-port'' (Server Must Not Specify Port). Requirement: Port MUST NOT be specified or required to use the API, except for ''localhost'' testing in a spec. To fix: Ensure the targeted value does NOT match the regular expression `(?!https?://localhost)(https?://.*):(\d*)\/?(.*)`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.servers..url` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-server-on-approved-domain: title: Server On Approved Domain reference: https://spotlight-rules.com/spec/rules/openapi/server-on-approved-domain/ description: APIs SHOULD be accessible under api.spscommerce.com. message: APIs SHOULD be accessible under api.spscommerce.com. severity: info given: $.servers..url then: function: pattern functionOptions: match: api.spscommerce.com|api.sps-internal.com|localhost formats: - oas3 tags: - format:openapi - spec:servers - experience:governance - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''server-on-approved-domain'' (Server On Approved Domain). Requirement: APIs SHOULD be accessible under api.spscommerce.com. To fix: Ensure the targeted value matches the regular expression `api.spscommerce.com|api.sps-internal.com|localhost`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.servers..url` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-server-url-include-version: title: Server URL Include Version reference: https://spotlight-rules.com/spec/rules/openapi/server-url-include-version/ description: API URLs versions should meet the Trimble API Standards. message: '{{error}}' severity: info given: $.servers then: function: trimble-valid-version-checker tags: - format:openapi - spec:servers - experience:versioning - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''server-url-include-version'' (Server URL Include Version). Requirement: API URLs versions should meet the Trimble API Standards. This rule is evaluated at the JSONPath `$.servers` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-server-url-meet-standards: title: Server URL Meet Standards reference: https://spotlight-rules.com/spec/rules/openapi/server-url-meet-standards/ description: API URLs should meet the Trimble API Standards. message: '{{error}}' severity: info given: $.servers then: function: trimble-valid-url-checker tags: - format:openapi - spec:servers - experience:consistency - experience:governance prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''server-url-meet-standards'' (Server URL Meet Standards). Requirement: API URLs should meet the Trimble API Standards. This rule is evaluated at the JSONPath `$.servers` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-server-url-must-be-lowercase: title: Server URL Must Be Lowercase reference: https://spotlight-rules.com/spec/rules/openapi/server-url-must-be-lowercase/ description: Server URL SHOULD BE lowercase. message: Server URL SHOULD BE lowercase. severity: info given: $.servers..url then: function: pattern functionOptions: match: ^[^A-Z]*$ formats: - oas3 tags: - format:openapi - spec:servers - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''server-url-must-be-lowercase'' (Server URL Must Be Lowercase). Requirement: Server URL SHOULD BE lowercase. To fix: Ensure the targeted value matches the regular expression `^[^A-Z]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.servers..url` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-tag-names-title-case: title: Tag Names Title Case reference: https://spotlight-rules.com/spec/rules/openapi/tag-names-title-case/ description: The first letter of each word in a tag being applied to APIs needs to be capitalized, keeping the tags being applied across APIs the same look and feel for organizing and publishing to documentation. message: Tag Names MUST Have First Letter in Each Word Capitalized severity: info given: $.tags.*.name then: function: pattern functionOptions: match: '[A-Z]\w*' tags: - format:openapi - spec:tags - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''tag-names-title-case'' (Tag Names Title Case). Requirement: The first letter of each word in a tag being applied to APIs needs to be capitalized, keeping the tags being applied across APIs the same look and feel for organizing and publishing to documentation. To fix: Ensure the targeted value matches the regular expression `[A-Z]\w*`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.tags.*.name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-tag-no-camel-case: title: Tag No Camel Case reference: https://spotlight-rules.com/spec/rules/openapi/tag-no-camel-case/ description: Detects a tag with camelCase (personalItem) text within it. message: Tag names cannot use Camel Case. Please rename {{value}}. severity: info given: - $.tags[*].name - $.paths[*][*].tags[*] then: function: pattern functionOptions: notMatch: /^[a-z]+[A-Z][a-z]+$/g tags: - format:openapi - spec:paths - spec:tags - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''tag-no-camel-case'' (Tag No Camel Case). Requirement: Detects a tag with camelCase (personalItem) text within it. To fix: Ensure the targeted value does NOT match the regular expression `/^[a-z]+[A-Z][a-z]+$/g`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.tags[*].name | $.paths[*][*].tags[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-tag-no-pascal-case: title: Tag No Pascal Case reference: https://spotlight-rules.com/spec/rules/openapi/tag-no-pascal-case/ description: Tag names cannot use Pascal Case. Please rename {{value}}. message: Tag names cannot use Pascal Case. Please rename {{value}}. severity: info given: - $.tags[*].name - $.paths[*][*].tags[*] then: function: pattern functionOptions: notMatch: /[A-Z][a-z]+[A-Z][a-z]+$/g tags: - format:openapi - spec:paths - spec:tags - experience:naming - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''tag-no-pascal-case'' (Tag No Pascal Case). Requirement: Tag names cannot use Pascal Case. Please rename {{value}}. To fix: Ensure the targeted value does NOT match the regular expression `/[A-Z][a-z]+[A-Z][a-z]+$/g`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.tags[*].name | $.paths[*][*].tags[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' openapi-tag-require-at-least-one: title: Tag Require At Least One reference: https://spotlight-rules.com/spec/rules/openapi/tag-require-at-least-one/ description: There needs to be at least one tag applied to an OpenAPI, providing a key word or phrase that can be applied to API operations. message: MUST Be At Least One Tag severity: info given: $ then: field: tags function: length functionOptions: min: 1 tags: - format:openapi - spec:document - experience:discoverability - experience:consistency prompt: 'You are editing an OpenAPI document to satisfy the Spotlight API governance rule ''tag-require-at-least-one'' (Tag Require At Least One). Requirement: There needs to be at least one tag applied to an OpenAPI, providing a key word or phrase that can be applied to API operations. To fix: Ensure the length of `tags` is at least 1. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid OpenAPI. Return only the complete corrected document, with no commentary.' apis-json-api-property-require-linting-rules: title: API Property Require Linting Rules reference: https://spotlight-rules.com/spec/rules/apis-json/api-property-require-linting-rules/ description: This property ensures that an API has governance rules applied, usually as part of a central set of governance rules, defined by policy, or stages of the API lifecycle. message: Has Linting Rules severity: info given: - $.apis.*.properties.* - $.common.* then: - field: type function: pattern functionOptions: notMatch: \b(api-rules|OpenApiRules)\b tags: - format:apis-json - spec:apis - spec:properties - experience:governance - experience:consistency prompt: 'You are editing an APIs.json document to satisfy the Spotlight API governance rule ''api-property-require-linting-rules'' (API Property Require Linting Rules). Requirement: This property ensures that an API has governance rules applied, usually as part of a central set of governance rules, defined by policy, or stages of the API lifecycle. To fix: Ensure `type` does NOT match the regular expression `\b(api-rules|OpenApiRules)\b`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.apis.*.properties.* | $.common.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid APIs.json. Return only the complete corrected document, with no commentary.' apis-json-api-property-require-valid-url: title: API Property Require Valid URL reference: https://spotlight-rules.com/spec/rules/apis-json/api-property-require-valid-url/ description: This property ensures that properties of an API or API contract all have valid URLs, checking if any of the URLs are not properly formed, or could be other formats. message: Property URLs Are Valid severity: info given: - $.apis.*.properties.* - $.common.* then: - field: url function: pattern functionOptions: notMatch: ^((http|https)://)[-a-zA-Z0-9@:%._\+~#?&//=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%._\+~#?&//=]*)$ tags: - format:apis-json - spec:apis - spec:properties - experience:consistency - experience:discoverability prompt: 'You are editing an APIs.json document to satisfy the Spotlight API governance rule ''api-property-require-valid-url'' (API Property Require Valid URL). Requirement: This property ensures that properties of an API or API contract all have valid URLs, checking if any of the URLs are not properly formed, or could be other formats. To fix: Ensure `url` does NOT match the regular expression `^((http|https)://)[-a-zA-Z0-9@:%._\+~#?&//=]{2,256}\.[a-z]{2,6}\b([-a-zA-Z0-9@:%._\+~#?&//=]*)$`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.apis.*.properties.* | $.common.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid APIs.json. Return only the complete corrected document, with no commentary.' apis-json-api-property-require-vocabulary: title: API Property Require Vocabulary reference: https://spotlight-rules.com/spec/rules/apis-json/api-property-require-vocabulary/ description: This property ensures that there is a centralized vocabulary in use for guiding the creation and usage of tags, path segments, and other metadata associated with an APIs. message: Has Vocabulary severity: info given: - $.apis.*.properties.* - $.common.* then: - field: type function: pattern functionOptions: notMatch: \b(vocabulary|vocabularies|Vocabulary|Vocabularies)\b tags: - format:apis-json - spec:apis - spec:properties - experience:consistency - experience:naming - experience:governance prompt: 'You are editing an APIs.json document to satisfy the Spotlight API governance rule ''api-property-require-vocabulary'' (API Property Require Vocabulary). Requirement: This property ensures that there is a centralized vocabulary in use for guiding the creation and usage of tags, path segments, and other metadata associated with an APIs. To fix: Ensure `type` does NOT match the regular expression `\b(vocabulary|vocabularies|Vocabulary|Vocabularies)\b`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.apis.*.properties.* | $.common.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid APIs.json. Return only the complete corrected document, with no commentary.' apis-json-api-tag-require-upper-case: title: API Tag Require Upper Case reference: https://spotlight-rules.com/spec/rules/apis-json/api-tag-require-upper-case/ description: Maintaining consistent casing for tags applied to individual APIs ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of every word in a phrase treated the same way. message: API Tags MUST Be Upper Case severity: info given: $.apis.*.tags.* then: function: pattern functionOptions: match: '[A-Z]\w*' tags: - format:apis-json - spec:apis - spec:tags - experience:naming - experience:consistency - experience:discoverability prompt: 'You are editing an APIs.json document to satisfy the Spotlight API governance rule ''api-tag-require-upper-case'' (API Tag Require Upper Case). Requirement: Maintaining consistent casing for tags applied to individual APIs ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of every word in a phrase treated the same way. To fix: Ensure the targeted value matches the regular expression `[A-Z]\w*`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.apis.*.tags.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid APIs.json. Return only the complete corrected document, with no commentary.' apis-json-info-apis-json-specification-version-format: title: Info APIs JSON Specification Version Format reference: https://spotlight-rules.com/spec/rules/apis-json/info-apis-json-specification-version-format/ description: specificationVersion should be a major.minor version (e.g. 0.21). message: specificationVersion should be major.minor. given: $.specificationVersion severity: info then: function: pattern functionOptions: match: ^\d+\.\d+$ tags: - format:apis-json - spec:document - experience:versioning - experience:consistency prompt: 'You are editing an APIs.json document to satisfy the Spotlight API governance rule ''info-apis-json-specification-version-format'' (Info APIs JSON Specification Version Format). Requirement: specificationVersion should be a major.minor version (e.g. 0.21). To fix: Ensure the targeted value matches the regular expression `^\d+\.\d+$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.specificationVersion` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid APIs.json. Return only the complete corrected document, with no commentary.' apis-json-maintainer-email-format: title: Maintainer Email Format reference: https://spotlight-rules.com/spec/rules/apis-json/maintainer-email-format/ description: A maintainer email should be a valid email address. message: Maintainer email should be a valid email. given: $.maintainers[*].email severity: info then: function: pattern functionOptions: match: ^[^@\s]+@[^@\s]+\.[^@\s]+$ tags: - format:apis-json - spec:maintainers - experience:consistency prompt: 'You are editing an APIs.json document to satisfy the Spotlight API governance rule ''maintainer-email-format'' (Maintainer Email Format). Requirement: A maintainer email should be a valid email address. To fix: Ensure the targeted value matches the regular expression `^[^@\s]+@[^@\s]+\.[^@\s]+$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.maintainers[*].email` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid APIs.json. Return only the complete corrected document, with no commentary.' apis-json-tag-require-upper-case: title: Tag Require Upper Case reference: https://spotlight-rules.com/spec/rules/apis-json/tag-require-upper-case/ description: Maintaining consistent casing for tags applied to APIs.json contracts ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of every word in a phrase treated the same way. message: Tags Upper Case severity: info given: $.tags.* then: function: pattern functionOptions: match: '[A-Z]\w*' tags: - format:apis-json - spec:tags - experience:naming - experience:consistency - experience:discoverability prompt: 'You are editing an APIs.json document to satisfy the Spotlight API governance rule ''tag-require-upper-case'' (Tag Require Upper Case). Requirement: Maintaining consistent casing for tags applied to APIs.json contracts ensures a uniform appearance and enhances search and discovery. Each word in a tag should be capitalized, with the first letter of every word in a phrase treated the same way. To fix: Ensure the targeted value matches the regular expression `[A-Z]\w*`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.tags.*` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid APIs.json. Return only the complete corrected document, with no commentary.' asyncapi-component-asyncapi-message-require-contenttype: title: Component Asyncapi Message Require Contenttype reference: https://spotlight-rules.com/spec/rules/asyncapi/component-asyncapi-message-require-contenttype/ description: Messages should declare a contentType (e.g. application/json). message: Message should declare a contentType. given: $.components.messages[*] severity: info then: field: contentType function: truthy tags: - format:asyncapi - spec:components - experience:consistency - experience:data-modeling prompt: 'You are editing an AsyncAPI document to satisfy the Spotlight API governance rule ''component-asyncapi-message-require-contenttype'' (Component Asyncapi Message Require Contenttype). Requirement: Messages should declare a contentType (e.g. application/json). To fix: Ensure `contentType` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.components.messages[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid AsyncAPI. Return only the complete corrected document, with no commentary.' asyncapi-component-asyncapi-message-require-name: title: Component Asyncapi Message Require Name reference: https://spotlight-rules.com/spec/rules/asyncapi/component-asyncapi-message-require-name/ description: Messages should declare a name. message: Message should declare a name. given: $.components.messages[*] severity: info then: field: name function: truthy tags: - format:asyncapi - spec:components - experience:documentation - experience:consistency prompt: 'You are editing an AsyncAPI document to satisfy the Spotlight API governance rule ''component-asyncapi-message-require-name'' (Component Asyncapi Message Require Name). Requirement: Messages should declare a name. To fix: Ensure `name` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.components.messages[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid AsyncAPI. Return only the complete corrected document, with no commentary.' asyncapi-schema-asyncapi-property-camel-case: title: Schema Asyncapi Property Camel Case reference: https://spotlight-rules.com/spec/rules/asyncapi/schema-asyncapi-property-camel-case/ description: Schema property names should be camelCase. message: Schema property is not camelCase. given: $.components.schemas[*].properties[*]~ severity: info then: function: pattern functionOptions: match: ^[a-z][a-zA-Z0-9]*$ tags: - format:asyncapi - spec:components - experience:naming - experience:consistency prompt: 'You are editing an AsyncAPI document to satisfy the Spotlight API governance rule ''schema-asyncapi-property-camel-case'' (Schema Asyncapi Property Camel Case). Requirement: Schema property names should be camelCase. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.components.schemas[*].properties[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid AsyncAPI. Return only the complete corrected document, with no commentary.' arazzo-source-arazzo-description-require-name: title: Source Arazzo Description Require Name reference: https://spotlight-rules.com/spec/rules/arazzo/source-arazzo-description-require-name/ description: Each source description should declare a name used to reference it from steps. message: Source description should have a name. given: $.sourceDescriptions[*] severity: info then: field: name function: truthy tags: - format:arazzo - spec:source-descriptions - experience:consistency - experience:documentation prompt: 'You are editing an Arazzo document to satisfy the Spotlight API governance rule ''source-arazzo-description-require-name'' (Source Arazzo Description Require Name). Requirement: Each source description should declare a name used to reference it from steps. To fix: Ensure `name` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.sourceDescriptions[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Arazzo. Return only the complete corrected document, with no commentary.' arazzo-workflow-arazzo-step-require-operation: title: Workflow Arazzo Step Require Operation reference: https://spotlight-rules.com/spec/rules/arazzo/workflow-arazzo-step-require-operation/ description: Each step should reference an operation via operationId, operationPath, or a nested workflowId. message: Step should reference an operationId, operationPath, or workflowId. given: $.workflows[*].steps[*] severity: info then: function: schema functionOptions: schema: type: object anyOf: - required: - operationId - required: - operationPath - required: - workflowId tags: - format:arazzo - spec:workflows - experience:reliability - experience:consistency prompt: 'You are editing an Arazzo document to satisfy the Spotlight API governance rule ''workflow-arazzo-step-require-operation'' (Workflow Arazzo Step Require Operation). Requirement: Each step should reference an operation via operationId, operationPath, or a nested workflowId. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.workflows[*].steps[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Arazzo. Return only the complete corrected document, with no commentary.' json-schema-document-require-id: title: Document Require ID reference: https://spotlight-rules.com/spec/rules/json-schema/document-require-id/ description: The `$id` property should be present. message: $id should be present severity: info given: $ then: field: $id function: truthy tags: - format:jsonschema - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Schema document to satisfy the Spotlight API governance rule ''document-require-id'' (Document Require ID). Requirement: The `$id` property should be present. To fix: Ensure `$id` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Schema. Return only the complete corrected document, with no commentary.' json-schema-document-require-property: title: Document Require Property reference: https://spotlight-rules.com/spec/rules/json-schema/document-require-property/ description: The `properties` property should be present. message: properties should be present severity: info given: $ then: field: properties function: truthy tags: - format:jsonschema - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Schema document to satisfy the Spotlight API governance rule ''document-require-property'' (Document Require Property). Requirement: The `properties` property should be present. To fix: Ensure `properties` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Schema. Return only the complete corrected document, with no commentary.' json-schema-document-require-required-list: title: Document Require Required List reference: https://spotlight-rules.com/spec/rules/json-schema/document-require-required-list/ description: The `required` property should be present. message: required should be present severity: info given: $ then: field: required function: truthy tags: - format:jsonschema - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Schema document to satisfy the Spotlight API governance rule ''document-require-required-list'' (Document Require Required List). Requirement: The `required` property should be present. To fix: Ensure `required` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Schema. Return only the complete corrected document, with no commentary.' json-schema-document-require-type: title: Document Require Type reference: https://spotlight-rules.com/spec/rules/json-schema/document-require-type/ description: The `type` property should be present. message: type should be present severity: info given: $ then: field: type function: truthy tags: - format:jsonschema - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Schema document to satisfy the Spotlight API governance rule ''document-require-type'' (Document Require Type). Requirement: The `type` property should be present. To fix: Ensure `type` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Schema. Return only the complete corrected document, with no commentary.' json-schema-schema-property-require-type: title: Schema Property Require Type reference: https://spotlight-rules.com/spec/rules/json-schema/schema-property-require-type/ description: The `type` property of each property should be present. message: type should be present severity: info given: $.properties[*] then: field: type function: truthy tags: - format:jsonschema - spec:properties - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Schema document to satisfy the Spotlight API governance rule ''schema-property-require-type'' (Schema Property Require Type). Requirement: The `type` property of each property should be present. To fix: Ensure `type` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.properties[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Schema. Return only the complete corrected document, with no commentary.' json-schema-schema-require: title: Schema Require reference: https://spotlight-rules.com/spec/rules/json-schema/schema-require/ description: The `$schema` property should be present. message: $schema should be present severity: info given: $ then: field: $schema function: truthy tags: - format:jsonschema - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Schema document to satisfy the Spotlight API governance rule ''schema-require'' (Schema Require). Requirement: The `$schema` property should be present. To fix: Ensure `$schema` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Schema. Return only the complete corrected document, with no commentary.' json-structure-document-json-structure-id-uri: title: Document JSON Structure ID URI reference: https://spotlight-rules.com/spec/rules/json-structure/document-json-structure-id-uri/ description: $id should be a stable absolute URI (https:// or urn:) identifying the schema. message: $id should be an absolute URI. given: $.$id severity: info then: function: pattern functionOptions: match: '^https?://|^urn:' tags: - format:json-structure - spec:document - experience:consistency - experience:discoverability prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''document-json-structure-id-uri'' (Document JSON Structure ID URI). Requirement: $id should be a stable absolute URI (https:// or urn:) identifying the schema. To fix: Ensure the targeted value matches the regular expression `^https?://|^urn:`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.$id` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-document-require-id: title: Document Require ID reference: https://spotlight-rules.com/spec/rules/json-structure/document-require-id/ description: The `$id` property should be present. message: $id should be present severity: info given: $ then: field: $id function: truthy tags: - format:json-structure - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''document-require-id'' (Document Require ID). Requirement: The `$id` property should be present. To fix: Ensure `$id` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-document-require-name: title: Document Require Name reference: https://spotlight-rules.com/spec/rules/json-structure/document-require-name/ description: The `name` property should be present. message: name should be present severity: info given: $ then: field: name function: truthy tags: - format:json-structure - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''document-require-name'' (Document Require Name). Requirement: The `name` property should be present. To fix: Ensure `name` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-document-require-property: title: Document Require Property reference: https://spotlight-rules.com/spec/rules/json-structure/document-require-property/ description: The `properties` property should be present. message: properties should be present severity: info given: $ then: field: properties function: truthy tags: - format:json-structure - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''document-require-property'' (Document Require Property). Requirement: The `properties` property should be present. To fix: Ensure `properties` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-document-require-type: title: Document Require Type reference: https://spotlight-rules.com/spec/rules/json-structure/document-require-type/ description: The `type` property should be present. message: type should be present severity: info given: $ then: field: type function: truthy tags: - format:json-structure - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''document-require-type'' (Document Require Type). Requirement: The `type` property should be present. To fix: Ensure `type` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-schema-json-structure-property-camel-case: title: Schema JSON Structure Property Camel Case reference: https://spotlight-rules.com/spec/rules/json-structure/schema-json-structure-property-camel-case/ description: Property names should be camelCase. message: Property is not camelCase. given: $.properties[*]~ severity: info then: function: pattern functionOptions: match: ^[a-z][a-zA-Z0-9]*$ tags: - format:json-structure - spec:schemas - experience:naming - experience:consistency prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''schema-json-structure-property-camel-case'' (Schema JSON Structure Property Camel Case). Requirement: Property names should be camelCase. To fix: Ensure the targeted value matches the regular expression `^[a-z][a-zA-Z0-9]*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.properties[*]~` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-schema-json-structure-uri: title: Schema JSON Structure URI reference: https://spotlight-rules.com/spec/rules/json-structure/schema-json-structure-uri/ description: $schema should be the URI of the JSON Structure meta-schema. message: $schema should be a URI. given: $.$schema severity: info then: function: pattern functionOptions: match: ^https?:// tags: - format:json-structure - spec:schemas - experience:consistency - experience:discoverability prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''schema-json-structure-uri'' (Schema JSON Structure URI). Requirement: $schema should be the URI of the JSON Structure meta-schema. To fix: Ensure the targeted value matches the regular expression `^https?://`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.$schema` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-schema-property-require-type: title: Schema Property Require Type reference: https://spotlight-rules.com/spec/rules/json-structure/schema-property-require-type/ description: The `type` property of each property should be present. message: type should be present severity: info given: $.properties[*] then: field: type function: truthy tags: - format:json-structure - spec:properties - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''schema-property-require-type'' (Schema Property Require Type). Requirement: The `type` property of each property should be present. To fix: Ensure `type` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.properties[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-structure-schema-require: title: Schema Require reference: https://spotlight-rules.com/spec/rules/json-structure/schema-require/ description: The `$schema` property should be present. message: $schema should be present severity: info given: $ then: field: $schema function: truthy tags: - format:json-structure - spec:schemas - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON Structure document to satisfy the Spotlight API governance rule ''schema-require'' (Schema Require). Requirement: The `$schema` property should be present. To fix: Ensure `$schema` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON Structure. Return only the complete corrected document, with no commentary.' json-ld-document-json-ld-id-iri: title: Document JSON LD ID IRI reference: https://spotlight-rules.com/spec/rules/json-ld/document-json-ld-id-iri/ description: '@id should be an IRI (https://, urn:, did:) or a blank-node identifier.' message: '@id should be an IRI.' given: $['@id'] severity: info then: function: pattern functionOptions: match: '^https?://|^urn:|^did:|^_:' tags: - format:json-ld - spec:document - experience:consistency - experience:discoverability prompt: 'You are editing a JSON-LD document to satisfy the Spotlight API governance rule ''document-json-ld-id-iri'' (Document JSON LD ID IRI). Requirement: @id should be an IRI (https://, urn:, did:) or a blank-node identifier. To fix: Ensure the targeted value matches the regular expression `^https?://|^urn:|^did:|^_:`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.@id` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON-LD. Return only the complete corrected document, with no commentary.' json-ld-schema-json-ld-context-uri-or-object: title: Schema JSON LD Context URI Or Object reference: https://spotlight-rules.com/spec/rules/json-ld/schema-json-ld-context-uri-or-object/ description: '@context should be a URI string, an inline object, or an array of those.' message: '@context should be a URI, object, or array.' given: $['@context'] severity: info then: function: schema functionOptions: schema: type: - string - object - array tags: - format:json-ld - spec:document - experience:data-modeling - experience:consistency prompt: 'You are editing a JSON-LD document to satisfy the Spotlight API governance rule ''schema-json-ld-context-uri-or-object'' (Schema JSON LD Context URI Or Object). Requirement: @context should be a URI string, an inline object, or an array of those. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.@context` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid JSON-LD. Return only the complete corrected document, with no commentary.' mcp-document-mcp-name-kebab-case: title: Document MCP Name Kebab Case reference: https://spotlight-rules.com/spec/rules/mcp/document-mcp-name-kebab-case/ description: MCP server name should be lower kebab-case. message: MCP server name should be kebab-case. given: $.name severity: info then: function: pattern functionOptions: match: ^[a-z0-9]+(?:-[a-z0-9]+)*$ tags: - format:mcp - spec:document - experience:naming - experience:consistency prompt: 'You are editing a MCP document to satisfy the Spotlight API governance rule ''document-mcp-name-kebab-case'' (Document MCP Name Kebab Case). Requirement: MCP server name should be lower kebab-case. To fix: Ensure the targeted value matches the regular expression `^[a-z0-9]+(?:-[a-z0-9]+)*$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.name` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid MCP. Return only the complete corrected document, with no commentary.' mcp-info-mcp-protocol-version-dated: title: Info MCP Protocol Version Dated reference: https://spotlight-rules.com/spec/rules/mcp/info-mcp-protocol-version-dated/ description: protocolVersion should be a dated MCP revision (YYYY-MM-DD). message: protocolVersion should be a dated revision (YYYY-MM-DD). given: $.protocolVersion severity: info then: function: pattern functionOptions: match: ^\d{4}-\d{2}-\d{2}$ tags: - format:mcp - spec:document - experience:versioning - experience:consistency prompt: 'You are editing a MCP document to satisfy the Spotlight API governance rule ''info-mcp-protocol-version-dated'' (Info MCP Protocol Version Dated). Requirement: protocolVersion should be a dated MCP revision (YYYY-MM-DD). To fix: Ensure the targeted value matches the regular expression `^\d{4}-\d{2}-\d{2}$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.protocolVersion` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid MCP. Return only the complete corrected document, with no commentary.' mcp-info-require-protocol-version: title: Info Require Protocol Version reference: https://spotlight-rules.com/spec/rules/mcp/info-require-protocol-version/ description: The `protocolVersion` property should be present. message: protocolVersion should be present severity: info given: $ then: field: protocolVersion function: truthy tags: - format:mcp - spec:servers - experience:versioning - experience:consistency prompt: 'You are editing a MCP document to satisfy the Spotlight API governance rule ''info-require-protocol-version'' (Info Require Protocol Version). Requirement: The `protocolVersion` property should be present. To fix: Ensure `protocolVersion` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid MCP. Return only the complete corrected document, with no commentary.' plans-plan-currency-iso4217: title: Plan Currency Iso4217 reference: https://spotlight-rules.com/spec/rules/plans/plan-currency-iso4217/ description: currency should be a 3-letter ISO 4217 code (e.g. USD). message: currency should be an ISO 4217 code. given: $.currency severity: info then: function: pattern functionOptions: match: ^[A-Z]{3}$ tags: - format:plans - spec:document - experience:consistency - experience:data-modeling prompt: 'You are editing a Plans document to satisfy the Spotlight API governance rule ''plan-currency-iso4217'' (Plan Currency Iso4217). Requirement: currency should be a 3-letter ISO 4217 code (e.g. USD). To fix: Ensure the targeted value matches the regular expression `^[A-Z]{3}$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.currency` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Plans. Return only the complete corrected document, with no commentary.' plans-plan-require-interval: title: Plan Require Interval reference: https://spotlight-rules.com/spec/rules/plans/plan-require-interval/ description: Each plan should declare a billing interval (e.g. month, year). message: Plan should declare a billing interval. given: $.plans[*] severity: info then: field: interval function: truthy tags: - format:plans - spec:plans - experience:consistency - experience:usability prompt: 'You are editing a Plans document to satisfy the Spotlight API governance rule ''plan-require-interval'' (Plan Require Interval). Requirement: Each plan should declare a billing interval (e.g. month, year). To fix: Ensure `interval` is present and non-empty at each matching location. This rule is evaluated at the JSONPath `$.plans[*]` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Plans. Return only the complete corrected document, with no commentary.' rate-limits-limit-scope-known: title: Limit Scope Known reference: https://spotlight-rules.com/spec/rules/rate-limits/limit-scope-known/ description: A limit scope should be one of ip, user, api-key, client, or global. message: Limit scope should be a known value. given: $.limits[*].scope severity: info then: function: schema functionOptions: schema: type: string enum: - ip - user - api-key - client - global tags: - format:rate-limits - spec:limits - experience:consistency prompt: 'You are editing a Rate Limits document to satisfy the Spotlight API governance rule ''limit-scope-known'' (Limit Scope Known). Requirement: A limit scope should be one of ip, user, api-key, client, or global. To fix: Adjust the targeted value so it conforms to the schema this rule requires. This rule is evaluated at the JSONPath `$.limits[*].scope` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Rate Limits. Return only the complete corrected document, with no commentary.' rate-limits-limit-window-format: title: Limit Window Format reference: https://spotlight-rules.com/spec/rules/rate-limits/limit-window-format/ description: A limit window should be a duration like 60s, 1m, 1h, or 1d. message: Limit window should be a duration (e.g. 60s, 1h). given: $.limits[*].window severity: info then: function: pattern functionOptions: match: ^\d+(ms|s|m|h|d)$ tags: - format:rate-limits - spec:limits - experience:consistency - experience:reliability prompt: 'You are editing a Rate Limits document to satisfy the Spotlight API governance rule ''limit-window-format'' (Limit Window Format). Requirement: A limit window should be a duration like 60s, 1m, 1h, or 1d. To fix: Ensure the targeted value matches the regular expression `^\d+(ms|s|m|h|d)$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.limits[*].window` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Rate Limits. Return only the complete corrected document, with no commentary.' finops-document-finops-currency-iso4217: title: Document FinOps Currency Iso4217 reference: https://spotlight-rules.com/spec/rules/finops/document-finops-currency-iso4217/ description: currency should be a 3-letter ISO 4217 code (e.g. USD). message: currency should be an ISO 4217 code. given: $.currency severity: info then: function: pattern functionOptions: match: ^[A-Z]{3}$ tags: - format:finops - spec:document - experience:consistency - experience:data-modeling prompt: 'You are editing a FinOps document to satisfy the Spotlight API governance rule ''document-finops-currency-iso4217'' (Document FinOps Currency Iso4217). Requirement: currency should be a 3-letter ISO 4217 code (e.g. USD). To fix: Ensure the targeted value matches the regular expression `^[A-Z]{3}$`; rewrite any value that does not. This rule is evaluated at the JSONPath `$.currency` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid FinOps. Return only the complete corrected document, with no commentary.' finops-document-finops-require-period: title: Document FinOps Require Period reference: https://spotlight-rules.com/spec/rules/finops/document-finops-require-period/ description: A FinOps artifact should declare a period (e.g. monthly, annual) for the budget and costs. message: FinOps should declare a period. given: $ severity: info then: field: period function: truthy tags: - format:finops - spec:document - experience:consistency - experience:governance prompt: 'You are editing a FinOps document to satisfy the Spotlight API governance rule ''document-finops-require-period'' (Document FinOps Require Period). Requirement: A FinOps artifact should declare a period (e.g. monthly, annual) for the budget and costs. To fix: Ensure `period` is present and non-empty at each matching location. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid FinOps. Return only the complete corrected document, with no commentary.' agent-skill-skill-description-single-line: title: Skill Description Single Line reference: https://spotlight-rules.com/spec/rules/agent-skill/skill-description-single-line/ description: A skill description should be a single line (no embedded line breaks) so it renders cleanly in pickers. message: Skill description should be a single line. given: $.frontmatter.description severity: info then: function: pattern functionOptions: notMatch: \n tags: - format:agent-skill - spec:frontmatter - experience:consistency - experience:usability prompt: 'You are editing an Agent Skill document to satisfy the Spotlight API governance rule ''skill-description-single-line'' (Skill Description Single Line). Requirement: A skill description should be a single line (no embedded line breaks) so it renders cleanly in pickers. To fix: Ensure the targeted value does NOT match the regular expression `\n`; rename or rewrite any value that does. This rule is evaluated at the JSONPath `$.frontmatter.description` — inspect every location it matches and correct only what violates the rule. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Agent Skill. Return only the complete corrected document, with no commentary.' agent-skill-skill-single-title: title: Skill Single Title reference: https://spotlight-rules.com/spec/rules/agent-skill/skill-single-title/ description: A skill body should have at most one level-1 heading — the frontmatter name is the title, and sections should use level-2 headings. message: Skill body should have at most one level-1 heading. severity: info given: $ then: function: headingCount functionOptions: depth: 1 max: 1 tags: - format:agent-skill - spec:body - experience:consistency prompt: 'You are editing an Agent Skill document to satisfy the Spotlight API governance rule ''skill-single-title'' (Skill Single Title). Requirement: A skill body should have at most one level-1 heading — the frontmatter name is the title, and sections should use level-2 headings. Make the smallest change that satisfies the rule, leave all unrelated content, key order, comments, and formatting unchanged, and keep the document valid Agent Skill. Return only the complete corrected document, with no commentary.'