From 11a1288d8d2464701b281b4aeb9c9f31d0e2dc45 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 15:54:37 +0100 Subject: [PATCH 01/13] CLOUDP-306579: Repeated Fields --- openapi/.raw/.ipaspectral.yaml | 36 ++++ .../ipa/__tests__/IPA124ArrayMaxItems.test.js | 177 ++++++++++++++++++ tools/spectral/ipa/ipa-spectral.yaml | 2 + tools/spectral/ipa/rulesets/IPA-124.yaml | 25 +++ tools/spectral/ipa/rulesets/README.md | 18 ++ .../rulesets/functions/IPA124ArrayMaxItems.js | 54 ++++++ 6 files changed, 312 insertions(+) create mode 100644 openapi/.raw/.ipaspectral.yaml create mode 100644 tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js create mode 100644 tools/spectral/ipa/rulesets/IPA-124.yaml create mode 100644 tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js diff --git a/openapi/.raw/.ipaspectral.yaml b/openapi/.raw/.ipaspectral.yaml new file mode 100644 index 0000000000..cd73e22598 --- /dev/null +++ b/openapi/.raw/.ipaspectral.yaml @@ -0,0 +1,36 @@ +# https://meta.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions +extends: + - https://raw.githubusercontent.com/mongodb/openapi/a3dd7046e8dccd24bb0eb9ccc9ad8c3e39f47685/tools/spectral/ipa/ipa-spectral.yaml + +overrides: + - files: + - '**#/components/schemas/DataLakeDatabaseDataSourceSettings' # external field, to be covered by CLOUDP-293178 + - '**#/components/schemas/DataLakeAtlasStoreReadPreference' # external field, to be covered by CLOUDP-293178 + rules: + xgen-IPA-123-enum-values-must-be-upper-snake-case: 'off' + - files: + - '**#/components/schemas/DataLakeAtlasStoreInstance' # external field, to be covered by CLOUDP-293178 + rules: + xgen-IPA-112-avoid-project-field-names: 'off' + - files: + - '**#/components/schemas/ClusterProviderSettings/properties/providerName' # dynamic field which can't be documented + - '**#/components/schemas/DataLakeStoreSettings/properties/provider' # external field, to be covered by CLOUDP-293178 + rules: + xgen-IPA-117-description: 'off' + - files: + - '**#/components/schemas/DataLakeAzureBlobStore' # external field, to be covered by CLOUDP-293178 + - '**#/components/schemas/AdvancedClusterDescription/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 + - '**#/components/schemas/AtlasTenantClusterUpgradeRequest20240805/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 + - '**#/components/schemas/ClusterDescription20240805/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 + - '**#/components/schemas/LegacyAtlasCluster/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 + - '**#/components/schemas/LegacyAtlasTenantClusterUpgradeRequest/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 + - '**#/components/schemas/AdvancedAutoScalingSettings/properties/diskGB' # unable to document exceptions, to be covered by CLOUDP-308286 + - '**#/components/schemas/UserSecurity/properties/customerX509' # unable to document exceptions, to be covered by CLOUDP-308286 + rules: + xgen-IPA-112-field-names-are-camel-case: 'off' + - files: + - '**#/components/schemas/DataLakeS3StoreSettings/allOf/1/properties/additionalStorageClasses' # unable to document exceptions, to be covered by CLOUDP-293178 + - '**#/components/schemas/DataLakeDatabaseDataSourceSettings/properties/databaseRegex' # unable to document exceptions, to be covered by CLOUDP-293178 + - '**#/components/schemas/DataLakeDatabaseDataSourceSettings/properties/collectionRegex' # unable to document exceptions, to be covered by CLOUDP-293178 + rules: + xgen-IPA-117-description-should-not-use-inline-links: 'off' \ No newline at end of file diff --git a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js new file mode 100644 index 0000000000..7fea514f81 --- /dev/null +++ b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js @@ -0,0 +1,177 @@ +import testRule from './__helpers__/testRule.js'; +import { DiagnosticSeverity } from '@stoplight/types'; + +testRule('xgen-IPA-124-array-max-items', [ + { + name: 'valid array with maxItems set to 100', + document: { + components: { + schemas: { + ValidSchema: { + type: 'object', + properties: { + items: { + type: 'array', + maxItems: 100, + items: { + type: 'string' + } + } + } + } + } + } + }, + errors: [] + }, + { + name: 'invalid array missing maxItems', + document: { + components: { + schemas: { + InvalidSchema: { + type: 'object', + properties: { + items: { + type: 'array', + items: { + type: 'string' + } + } + } + } + } + } + }, + errors: [ + { + code: 'xgen-IPA-124-array-max-items', + message: 'Array must have maxItems property defined.', + path: ['components', 'schemas', 'InvalidSchema', 'properties', 'items'], + severity: DiagnosticSeverity.Warning + } + ] + }, + { + name: 'invalid array with incorrect maxItems value', + document: { + components: { + schemas: { + InvalidSchema: { + type: 'object', + properties: { + items: { + type: 'array', + maxItems: 50, + items: { + type: 'string' + } + } + } + } + } + } + }, + errors: [ + { + code: 'xgen-IPA-124-array-max-items', + message: 'Array maxItems must be set to 100, found: 50.', + path: ['components', 'schemas', 'InvalidSchema', 'properties', 'items'], + severity: DiagnosticSeverity.Warning + } + ] + }, + { + name: 'array with exception should be skipped', + document: { + components: { + schemas: { + ExceptionSchema: { + type: 'object', + properties: { + items: { + type: 'array', + items: { + type: 'string' + }, + 'x-xgen-IPA-exception': { + 'xgen-IPA-124-array-max-items': 'Reason' + } + } + } + } + } + } + }, + errors: [] + }, + { + name: 'nested arrays should all be checked', + document: { + components: { + schemas: { + NestedArrays: { + type: 'object', + properties: { + outerArray: { + type: 'array', + maxItems: 100, + items: { + type: 'array', + maxItems: 50, + items: { + type: 'string' + } + } + } + } + } + } + } + }, + errors: [ + { + code: 'xgen-IPA-124-array-max-items', + message: 'Array maxItems must be set to 100, found: 50.', + path: ['components', 'schemas', 'NestedArrays', 'properties', 'outerArray', 'items'], + severity: DiagnosticSeverity.Warning + } + ] + }, + { + name: 'arrays in request/response bodies should be checked', + document: { + paths: { + '/api/resources': { + post: { + requestBody: { + content: { + 'application/json': { + schema: { + type: 'object', + properties: { + items: { + type: 'array', + items: { + type: 'string' + } + } + } + } + } + } + } + } + } + } + }, + errors: [ + { + code: 'xgen-IPA-124-array-max-items', + message: 'Array must have maxItems property defined.', + path: ['paths', '/api/resources', 'post', 'requestBody', 'content', 'application/json', 'schema', 'properties', 'items'], + severity: DiagnosticSeverity.Warning + } + ] + } +]); diff --git a/tools/spectral/ipa/ipa-spectral.yaml b/tools/spectral/ipa/ipa-spectral.yaml index 50fa4ea782..0bce3fd930 100644 --- a/tools/spectral/ipa/ipa-spectral.yaml +++ b/tools/spectral/ipa/ipa-spectral.yaml @@ -16,6 +16,7 @@ extends: - ./rulesets/IPA-119.yaml - ./rulesets/IPA-121.yaml - ./rulesets/IPA-123.yaml + - ./rulesets/IPA-124.yaml - ./rulesets/IPA-125.yaml overrides: @@ -56,3 +57,4 @@ overrides: - '**#/paths/~1rest~1unauth~1version' # external reference, to be covered by CLOUDP-309694 rules: xgen-IPA-114-error-responses-refer-to-api-error: 'off' + diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml new file mode 100644 index 0000000000..5548259850 --- /dev/null +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -0,0 +1,25 @@ +# IPA-124: Repeated Fields +# http://go/ipa/124 + +functions: + - IPA124ArrayMaxItems + +rules: + xgen-IPA-124-array-max-items: + description: | + Array fields must have a maxItems property defined with a value of 100. + + ##### Implementation details + Rule checks for the following conditions: + + - All schema objects with type 'array' must have a maxItems property + - The maxItems value must be set to 100 + - Schema objects with `x-xgen-IPA-exception` for this rule are excluded from validation + message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-124-array-max-items' + severity: warn + resolved: false + given: $..[?(@.type=="array")] + then: + function: IPA124ArrayMaxItems + functionOptions: + maxItems: 100 \ No newline at end of file diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index e828145239..ae108da320 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -844,6 +844,24 @@ Rule checks for the following conditions: +### IPA-124 + +Rules are based on [http://go/ipa/IPA-124](http://go/ipa/IPA-124). + +#### xgen-IPA-124-array-max-items + + ![warn](https://img.shields.io/badge/warning-yellow) +Array fields must have a maxItems property defined with a value of 100. + +##### Implementation details +Rule checks for the following conditions: + + - All schema objects with type 'array' must have a maxItems property + - The maxItems value must be set to 100 + - Schema objects with `x-xgen-IPA-exception` for this rule are excluded from validation + + + ### IPA-125 Rules are based on [http://go/ipa/IPA-125](http://go/ipa/IPA-125). diff --git a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js new file mode 100644 index 0000000000..32a86c6c9c --- /dev/null +++ b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js @@ -0,0 +1,54 @@ +import { + collectAdoption, + collectAndReturnViolation, + collectException, + handleInternalError, +} from './utils/collectionUtils.js'; +import { hasException } from './utils/exceptions.js'; + +const RULE_NAME = 'xgen-IPA-124-array-max-items'; + +/** + * Checks if array fields have maxItems defined and set to 100 + * + * @param {object} input - The array schema object from the OpenAPI spec + * @param {object} options - Rule configuration options + * @param {object} context - The context object containing the path and documentInventory + */ +export default (input, { maxItems }, { path }) => { + // Check for exception at the schema level + if (hasException(input, RULE_NAME)) { + collectException(input, RULE_NAME, path); + return; + } + + const errors = checkViolationsAndReturnErrors(input, path, maxItems); + if (errors.length > 0) { + return collectAndReturnViolation(path, RULE_NAME, errors); + } + + collectAdoption(path, RULE_NAME); +}; + +function checkViolationsAndReturnErrors(input, path, maxItems) { + try { + // Check if maxItems is defined + if (input.maxItems === undefined) { + return [{ + message: `Array must have maxItems property defined.`, + path, + }]; + } + // Check if maxItems is set to the required value + else if (input.maxItems !== maxItems) { + return [{ + message: `Array maxItems must be set to ${maxItems}, found: ${input.maxItems}.`, + path, + }]; + } + + return []; + } catch (e) { + handleInternalError(RULE_NAME, path, e); + } +} From 3a62aa111b6a32ed5ad3198e2f658a073ca9400e Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 15:58:10 +0100 Subject: [PATCH 02/13] docs and prettiers fix --- .../ipa/__tests__/IPA124ArrayMaxItems.test.js | 140 ++++++++++-------- tools/spectral/ipa/ipa-spectral.yaml | 1 - tools/spectral/ipa/rulesets/IPA-123.yaml | 1 + tools/spectral/ipa/rulesets/IPA-124.yaml | 8 +- tools/spectral/ipa/rulesets/README.md | 3 +- .../rulesets/functions/IPA124ArrayMaxItems.js | 40 ++--- 6 files changed, 104 insertions(+), 89 deletions(-) diff --git a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js index 7fea514f81..74b6a0c904 100644 --- a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js +++ b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js @@ -14,15 +14,15 @@ testRule('xgen-IPA-124-array-max-items', [ type: 'array', maxItems: 100, items: { - type: 'string' - } - } - } - } - } - } + type: 'string', + }, + }, + }, + }, + }, + }, }, - errors: [] + errors: [], }, { name: 'invalid array missing maxItems', @@ -35,22 +35,22 @@ testRule('xgen-IPA-124-array-max-items', [ items: { type: 'array', items: { - type: 'string' - } - } - } - } - } - } + type: 'string', + }, + }, + }, + }, + }, + }, }, errors: [ { code: 'xgen-IPA-124-array-max-items', message: 'Array must have maxItems property defined.', path: ['components', 'schemas', 'InvalidSchema', 'properties', 'items'], - severity: DiagnosticSeverity.Warning - } - ] + severity: DiagnosticSeverity.Warning, + }, + ], }, { name: 'invalid array with incorrect maxItems value', @@ -64,22 +64,22 @@ testRule('xgen-IPA-124-array-max-items', [ type: 'array', maxItems: 50, items: { - type: 'string' - } - } - } - } - } - } + type: 'string', + }, + }, + }, + }, + }, + }, }, errors: [ { code: 'xgen-IPA-124-array-max-items', message: 'Array maxItems must be set to 100, found: 50.', path: ['components', 'schemas', 'InvalidSchema', 'properties', 'items'], - severity: DiagnosticSeverity.Warning - } - ] + severity: DiagnosticSeverity.Warning, + }, + ], }, { name: 'array with exception should be skipped', @@ -92,18 +92,18 @@ testRule('xgen-IPA-124-array-max-items', [ items: { type: 'array', items: { - type: 'string' + type: 'string', }, 'x-xgen-IPA-exception': { - 'xgen-IPA-124-array-max-items': 'Reason' - } - } - } - } - } - } + 'xgen-IPA-124-array-max-items': 'Reason', + }, + }, + }, + }, + }, + }, }, - errors: [] + errors: [], }, { name: 'nested arrays should all be checked', @@ -117,26 +117,26 @@ testRule('xgen-IPA-124-array-max-items', [ type: 'array', maxItems: 100, items: { - type: 'array', + type: 'array', maxItems: 50, items: { - type: 'string' - } - } - } - } - } - } - } + type: 'string', + }, + }, + }, + }, + }, + }, + }, }, errors: [ { code: 'xgen-IPA-124-array-max-items', message: 'Array maxItems must be set to 100, found: 50.', path: ['components', 'schemas', 'NestedArrays', 'properties', 'outerArray', 'items'], - severity: DiagnosticSeverity.Warning - } - ] + severity: DiagnosticSeverity.Warning, + }, + ], }, { name: 'arrays in request/response bodies should be checked', @@ -153,25 +153,35 @@ testRule('xgen-IPA-124-array-max-items', [ items: { type: 'array', items: { - type: 'string' - } - } - } - } - } - } - } - } - } - } + type: 'string', + }, + }, + }, + }, + }, + }, + }, + }, + }, + }, }, errors: [ { code: 'xgen-IPA-124-array-max-items', message: 'Array must have maxItems property defined.', - path: ['paths', '/api/resources', 'post', 'requestBody', 'content', 'application/json', 'schema', 'properties', 'items'], - severity: DiagnosticSeverity.Warning - } - ] - } + path: [ + 'paths', + '/api/resources', + 'post', + 'requestBody', + 'content', + 'application/json', + 'schema', + 'properties', + 'items', + ], + severity: DiagnosticSeverity.Warning, + }, + ], + }, ]); diff --git a/tools/spectral/ipa/ipa-spectral.yaml b/tools/spectral/ipa/ipa-spectral.yaml index 0bce3fd930..644e740692 100644 --- a/tools/spectral/ipa/ipa-spectral.yaml +++ b/tools/spectral/ipa/ipa-spectral.yaml @@ -57,4 +57,3 @@ overrides: - '**#/paths/~1rest~1unauth~1version' # external reference, to be covered by CLOUDP-309694 rules: xgen-IPA-114-error-responses-refer-to-api-error: 'off' - diff --git a/tools/spectral/ipa/rulesets/IPA-123.yaml b/tools/spectral/ipa/rulesets/IPA-123.yaml index 61b0fc8bef..a599e95352 100644 --- a/tools/spectral/ipa/rulesets/IPA-123.yaml +++ b/tools/spectral/ipa/rulesets/IPA-123.yaml @@ -32,6 +32,7 @@ rules: - Validates that each enum array has 20 or fewer values - Reusable enum schemas will be ignored - Skips validation if the schema has an exception defined for this rule + - This validation threshold can be adjusted by changing the functionOptions.maxEnumValues parameter message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-123-allowable-enum-values-should-not-exceed-20' severity: warn resolved: false diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index 5548259850..77f120f809 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -8,13 +8,13 @@ rules: xgen-IPA-124-array-max-items: description: | Array fields must have a maxItems property defined with a value of 100. - + ##### Implementation details Rule checks for the following conditions: - + - All schema objects with type 'array' must have a maxItems property - The maxItems value must be set to 100 - - Schema objects with `x-xgen-IPA-exception` for this rule are excluded from validation + - This validation threshold can be adjusted by changing the functionOptions.maxItems parameter message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-124-array-max-items' severity: warn resolved: false @@ -22,4 +22,4 @@ rules: then: function: IPA124ArrayMaxItems functionOptions: - maxItems: 100 \ No newline at end of file + maxItems: 100 diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index ae108da320..3e5c5c42ba 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -841,6 +841,7 @@ Rule checks for the following conditions: - Validates that each enum array has 20 or fewer values - Reusable enum schemas will be ignored - Skips validation if the schema has an exception defined for this rule + - This validation threshold can be adjusted by changing the functionOptions.maxEnumValues parameter @@ -858,7 +859,7 @@ Rule checks for the following conditions: - All schema objects with type 'array' must have a maxItems property - The maxItems value must be set to 100 - - Schema objects with `x-xgen-IPA-exception` for this rule are excluded from validation + - This validation threshold can be adjusted by changing the functionOptions.maxItems parameter diff --git a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js index 32a86c6c9c..4780cf5fbc 100644 --- a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js +++ b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js @@ -16,35 +16,39 @@ const RULE_NAME = 'xgen-IPA-124-array-max-items'; * @param {object} context - The context object containing the path and documentInventory */ export default (input, { maxItems }, { path }) => { - // Check for exception at the schema level - if (hasException(input, RULE_NAME)) { - collectException(input, RULE_NAME, path); - return; - } + // Check for exception at the schema level + if (hasException(input, RULE_NAME)) { + collectException(input, RULE_NAME, path); + return; + } - const errors = checkViolationsAndReturnErrors(input, path, maxItems); - if (errors.length > 0) { - return collectAndReturnViolation(path, RULE_NAME, errors); - } + const errors = checkViolationsAndReturnErrors(input, path, maxItems); + if (errors.length > 0) { + return collectAndReturnViolation(path, RULE_NAME, errors); + } - collectAdoption(path, RULE_NAME); + collectAdoption(path, RULE_NAME); }; function checkViolationsAndReturnErrors(input, path, maxItems) { try { // Check if maxItems is defined if (input.maxItems === undefined) { - return [{ - message: `Array must have maxItems property defined.`, - path, - }]; + return [ + { + message: `Array must have maxItems property defined.`, + path, + }, + ]; } // Check if maxItems is set to the required value else if (input.maxItems !== maxItems) { - return [{ - message: `Array maxItems must be set to ${maxItems}, found: ${input.maxItems}.`, - path, - }]; + return [ + { + message: `Array maxItems must be set to ${maxItems}, found: ${input.maxItems}.`, + path, + }, + ]; } return []; From 540de2534e25fb925632d934745526e940ed0b43 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 16:19:00 +0100 Subject: [PATCH 03/13] given fix --- tools/spectral/ipa/rulesets/IPA-124.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index 77f120f809..bce65ee2dc 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -18,7 +18,7 @@ rules: message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-124-array-max-items' severity: warn resolved: false - given: $..[?(@.type=="array")] + given: $..[?(@ && @.type === "array")] then: function: IPA124ArrayMaxItems functionOptions: From 5fcbc743bde95fd1993e298829a10c05201bfffa Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 16:25:45 +0100 Subject: [PATCH 04/13] docs fix --- tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js | 4 ++-- tools/spectral/ipa/rulesets/IPA-124.yaml | 2 +- tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js index 74b6a0c904..cd5812f36b 100644 --- a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js +++ b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js @@ -46,7 +46,7 @@ testRule('xgen-IPA-124-array-max-items', [ errors: [ { code: 'xgen-IPA-124-array-max-items', - message: 'Array must have maxItems property defined.', + message: 'Array must have maxItems property defined to enforce an upper bound on the number of items.', path: ['components', 'schemas', 'InvalidSchema', 'properties', 'items'], severity: DiagnosticSeverity.Warning, }, @@ -168,7 +168,7 @@ testRule('xgen-IPA-124-array-max-items', [ errors: [ { code: 'xgen-IPA-124-array-max-items', - message: 'Array must have maxItems property defined.', + message: 'Array must have maxItems property defined to enforce an upper bound on the number of items.', path: [ 'paths', '/api/resources', diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index bce65ee2dc..a5421e34e4 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -7,7 +7,7 @@ functions: rules: xgen-IPA-124-array-max-items: description: | - Array fields must have a maxItems property defined with a value of 100. + Array fields must have a maxItems property defined to enforce an upper bound on the number of items (default: 100). ##### Implementation details Rule checks for the following conditions: diff --git a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js index 4780cf5fbc..334dbf0ded 100644 --- a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js +++ b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js @@ -36,7 +36,7 @@ function checkViolationsAndReturnErrors(input, path, maxItems) { if (input.maxItems === undefined) { return [ { - message: `Array must have maxItems property defined.`, + message: `Array must have maxItems property defined to enforce an upper bound on the number of items.`, path, }, ]; From b42377e0c86d6bb4717e8d86a6449690919a6f26 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 16:28:52 +0100 Subject: [PATCH 05/13] docs fix --- tools/spectral/ipa/rulesets/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index 3e5c5c42ba..ef13640348 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -852,7 +852,7 @@ Rules are based on [http://go/ipa/IPA-124](http://go/ipa/IPA-124). #### xgen-IPA-124-array-max-items ![warn](https://img.shields.io/badge/warning-yellow) -Array fields must have a maxItems property defined with a value of 100. +Array fields must have a maxItems property defined to enforce an upper bound on the number of items (default: 100). ##### Implementation details Rule checks for the following conditions: From 2dd09edbd7c2fe86b7fca288b060626c7979cff6 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 16:34:46 +0100 Subject: [PATCH 06/13] test fix --- .../ipa/__tests__/IPA124ArrayMaxItems.test.js | 20 +++++++++---------- .../rulesets/functions/IPA124ArrayMaxItems.js | 2 ++ 2 files changed, 12 insertions(+), 10 deletions(-) diff --git a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js index cd5812f36b..152b3ab1f0 100644 --- a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js +++ b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js @@ -10,7 +10,7 @@ testRule('xgen-IPA-124-array-max-items', [ ValidSchema: { type: 'object', properties: { - items: { + arrayProperty: { type: 'array', maxItems: 100, items: { @@ -32,7 +32,7 @@ testRule('xgen-IPA-124-array-max-items', [ InvalidSchema: { type: 'object', properties: { - items: { + arrayProperty: { type: 'array', items: { type: 'string', @@ -47,7 +47,7 @@ testRule('xgen-IPA-124-array-max-items', [ { code: 'xgen-IPA-124-array-max-items', message: 'Array must have maxItems property defined to enforce an upper bound on the number of items.', - path: ['components', 'schemas', 'InvalidSchema', 'properties', 'items'], + path: ['components', 'schemas', 'InvalidSchema', 'properties', 'arrayProperty'], severity: DiagnosticSeverity.Warning, }, ], @@ -60,7 +60,7 @@ testRule('xgen-IPA-124-array-max-items', [ InvalidSchema: { type: 'object', properties: { - items: { + arrayProperty: { type: 'array', maxItems: 50, items: { @@ -76,7 +76,7 @@ testRule('xgen-IPA-124-array-max-items', [ { code: 'xgen-IPA-124-array-max-items', message: 'Array maxItems must be set to 100, found: 50.', - path: ['components', 'schemas', 'InvalidSchema', 'properties', 'items'], + path: ['components', 'schemas', 'InvalidSchema', 'properties', 'arrayProperty'], severity: DiagnosticSeverity.Warning, }, ], @@ -89,7 +89,7 @@ testRule('xgen-IPA-124-array-max-items', [ ExceptionSchema: { type: 'object', properties: { - items: { + arrayProperty: { type: 'array', items: { type: 'string', @@ -116,7 +116,7 @@ testRule('xgen-IPA-124-array-max-items', [ outerArray: { type: 'array', maxItems: 100, - items: { + arrayProperty: { type: 'array', maxItems: 50, items: { @@ -133,7 +133,7 @@ testRule('xgen-IPA-124-array-max-items', [ { code: 'xgen-IPA-124-array-max-items', message: 'Array maxItems must be set to 100, found: 50.', - path: ['components', 'schemas', 'NestedArrays', 'properties', 'outerArray', 'items'], + path: ['components', 'schemas', 'NestedArrays', 'properties', 'outerArray', 'arrayProperty'], severity: DiagnosticSeverity.Warning, }, ], @@ -150,7 +150,7 @@ testRule('xgen-IPA-124-array-max-items', [ schema: { type: 'object', properties: { - items: { + arrayProperty: { type: 'array', items: { type: 'string', @@ -178,7 +178,7 @@ testRule('xgen-IPA-124-array-max-items', [ 'application/json', 'schema', 'properties', - 'items', + 'arrayProperty', ], severity: DiagnosticSeverity.Warning, }, diff --git a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js index 334dbf0ded..7d6070253c 100644 --- a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js +++ b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js @@ -16,6 +16,8 @@ const RULE_NAME = 'xgen-IPA-124-array-max-items'; * @param {object} context - The context object containing the path and documentInventory */ export default (input, { maxItems }, { path }) => { + console.log(input); + console.log(path); // Check for exception at the schema level if (hasException(input, RULE_NAME)) { collectException(input, RULE_NAME, path); From bf2a07ad8dee1673ae1768396b3d0825d53c6207 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 16:35:04 +0100 Subject: [PATCH 07/13] remove logs --- tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js | 2 -- 1 file changed, 2 deletions(-) diff --git a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js index 7d6070253c..334dbf0ded 100644 --- a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js +++ b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js @@ -16,8 +16,6 @@ const RULE_NAME = 'xgen-IPA-124-array-max-items'; * @param {object} context - The context object containing the path and documentInventory */ export default (input, { maxItems }, { path }) => { - console.log(input); - console.log(path); // Check for exception at the schema level if (hasException(input, RULE_NAME)) { collectException(input, RULE_NAME, path); From 9c2840aaefc1db69a7f0fe51ccb0b8e4b85b7624 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 17:14:36 +0100 Subject: [PATCH 08/13] parameter name check --- .../ipa/__tests__/IPA124ArrayMaxItems.test.js | 207 +++++++++++++++++- tools/spectral/ipa/rulesets/IPA-124.yaml | 7 +- .../rulesets/functions/IPA124ArrayMaxItems.js | 20 +- 3 files changed, 226 insertions(+), 8 deletions(-) diff --git a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js index 152b3ab1f0..afc4851781 100644 --- a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js +++ b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js @@ -38,6 +38,12 @@ testRule('xgen-IPA-124-array-max-items', [ type: 'string', }, }, + links: { + type: 'array', + items: { + type: 'object', + }, + }, }, }, }, @@ -62,7 +68,7 @@ testRule('xgen-IPA-124-array-max-items', [ properties: { arrayProperty: { type: 'array', - maxItems: 50, + maxItems: 101, items: { type: 'string', }, @@ -75,7 +81,7 @@ testRule('xgen-IPA-124-array-max-items', [ errors: [ { code: 'xgen-IPA-124-array-max-items', - message: 'Array maxItems must be set to 100, found: 50.', + message: 'Array maxItems must be set below 100, found: 101.', path: ['components', 'schemas', 'InvalidSchema', 'properties', 'arrayProperty'], severity: DiagnosticSeverity.Warning, }, @@ -118,7 +124,7 @@ testRule('xgen-IPA-124-array-max-items', [ maxItems: 100, arrayProperty: { type: 'array', - maxItems: 50, + maxItems: 101, items: { type: 'string', }, @@ -132,7 +138,7 @@ testRule('xgen-IPA-124-array-max-items', [ errors: [ { code: 'xgen-IPA-124-array-max-items', - message: 'Array maxItems must be set to 100, found: 50.', + message: 'Array maxItems must be set below 100, found: 101.', path: ['components', 'schemas', 'NestedArrays', 'properties', 'outerArray', 'arrayProperty'], severity: DiagnosticSeverity.Warning, }, @@ -184,4 +190,197 @@ testRule('xgen-IPA-124-array-max-items', [ }, ], }, + { + name: 'parameter arrays should be checked', + document: { + paths: { + '/api/resources': { + get: { + parameters: [ + { + name: 'ids', + in: 'query', + schema: { + type: 'array', + items: { + type: 'string', + }, + }, + }, + ], + }, + }, + }, + }, + errors: [ + { + code: 'xgen-IPA-124-array-max-items', + message: 'Array must have maxItems property defined to enforce an upper bound on the number of items.', + path: ['paths', '/api/resources', 'get', 'parameters', '0', 'schema'], + severity: DiagnosticSeverity.Warning, + }, + ], + }, + { + name: 'arrays with property names in the ignore list should be skipped', + document: { + components: { + schemas: { + IgnoredSchema: { + type: 'object', + properties: { + links: { + type: 'array', + items: { + type: 'object', + }, + }, + }, + }, + }, + }, + }, + errors: [], + }, + { + name: 'arrays in response content should be checked - invalid case', + document: { + paths: { + '/api/resources': { + get: { + responses: { + 200: { + content: { + 'application/vnd.atlas.2023-01-01+json': { + schema: { + type: 'array', + items: { + type: 'object', + }, + }, + }, + }, + }, + }, + }, + }, + }, + }, + errors: [ + { + code: 'xgen-IPA-124-array-max-items', + message: 'Array must have maxItems property defined to enforce an upper bound on the number of items.', + path: [ + 'paths', + '/api/resources', + 'get', + 'responses', + '200', + 'content', + 'application/vnd.atlas.2023-01-01+json', + 'schema', + ], + severity: DiagnosticSeverity.Warning, + }, + ], + }, + { + name: 'arrays in response content should be checked - valid case', + document: { + paths: { + '/api/resources': { + get: { + responses: { + 200: { + content: { + 'application/vnd.atlas.2023-01-01+json': { + schema: { + type: 'array', + maxItems: 100, + items: { + type: 'object', + }, + }, + }, + }, + }, + }, + }, + }, + }, + }, + errors: [], + }, + { + name: 'arrays in response content with excessive maxItems', + document: { + paths: { + '/api/resources': { + get: { + responses: { + 200: { + content: { + 'application/vnd.atlas.2023-01-01+json': { + schema: { + type: 'array', + maxItems: 500, + items: { + type: 'object', + }, + }, + }, + }, + }, + }, + }, + }, + }, + }, + errors: [ + { + code: 'xgen-IPA-124-array-max-items', + message: 'Array maxItems must be set below 100, found: 500.', + path: [ + 'paths', + '/api/resources', + 'get', + 'responses', + '200', + 'content', + 'application/vnd.atlas.2023-01-01+json', + 'schema', + ], + severity: DiagnosticSeverity.Warning, + }, + ], + }, + { + name: 'arrays in response content with exception should be skipped', + document: { + paths: { + '/api/resources': { + get: { + responses: { + 200: { + content: { + 'application/vnd.atlas.2023-01-01+json': { + schema: { + type: 'array', + items: { + type: 'object', + }, + 'x-xgen-IPA-exception': { + 'xgen-IPA-124-array-max-items': 'Large response array is necessary', + }, + }, + }, + }, + }, + }, + }, + }, + }, + }, + errors: [], + }, ]); diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index a5421e34e4..a6c60c1599 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -14,7 +14,10 @@ rules: - All schema objects with type 'array' must have a maxItems property - The maxItems value must be set to 100 - - This validation threshold can be adjusted by changing the functionOptions.maxItems parameter + + ##### Function options + - maxItems: Required integer parameter specifying the maximum allowed array size (default: 100) + - ignore: Required array parameter listing property names to be exempted from validation message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-124-array-max-items' severity: warn resolved: false @@ -23,3 +26,5 @@ rules: function: IPA124ArrayMaxItems functionOptions: maxItems: 100 + ignore: + - links diff --git a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js index 334dbf0ded..754c8238c5 100644 --- a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js +++ b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js @@ -15,13 +15,27 @@ const RULE_NAME = 'xgen-IPA-124-array-max-items'; * @param {object} options - Rule configuration options * @param {object} context - The context object containing the path and documentInventory */ -export default (input, { maxItems }, { path }) => { +export default (input, { maxItems, ignore = [] }, { path }) => { // Check for exception at the schema level if (hasException(input, RULE_NAME)) { collectException(input, RULE_NAME, path); return; } + let propertyName; + if (path.includes('parameters')) { + propertyName = input.name; + } else if (path.includes('content')) { + propertyName = null; + } else { + propertyName = path[path.length - 1]; + } + + // Check if the parameter name is in the ignore list + if (ignore.includes(propertyName)) { + return; + } + const errors = checkViolationsAndReturnErrors(input, path, maxItems); if (errors.length > 0) { return collectAndReturnViolation(path, RULE_NAME, errors); @@ -42,10 +56,10 @@ function checkViolationsAndReturnErrors(input, path, maxItems) { ]; } // Check if maxItems is set to the required value - else if (input.maxItems !== maxItems) { + else if (input.maxItems > maxItems) { return [ { - message: `Array maxItems must be set to ${maxItems}, found: ${input.maxItems}.`, + message: `Array maxItems must be set below ${maxItems}, found: ${input.maxItems}.`, path, }, ]; From f975393b0b7f98cd4af2fbaea7e5c8e9d0bceabc Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 17:16:10 +0100 Subject: [PATCH 09/13] docs fix --- tools/spectral/ipa/rulesets/README.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index ef13640348..9a74f50ef7 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -859,7 +859,10 @@ Rule checks for the following conditions: - All schema objects with type 'array' must have a maxItems property - The maxItems value must be set to 100 - - This validation threshold can be adjusted by changing the functionOptions.maxItems parameter + +##### Function options + - maxItems: Required integer parameter specifying the maximum allowed array size (default: 100) + - ignore: Required array parameter listing property names to be exempted from validation From 0209cd70bd8598318f0bc8ae6be1f08a3282c722 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 17:17:36 +0100 Subject: [PATCH 10/13] docs fix --- tools/spectral/ipa/rulesets/IPA-124.yaml | 2 +- tools/spectral/ipa/rulesets/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index a6c60c1599..7442700636 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -13,7 +13,7 @@ rules: Rule checks for the following conditions: - All schema objects with type 'array' must have a maxItems property - - The maxItems value must be set to 100 + - The maxItems value must be set below the threshold of 100 ##### Function options - maxItems: Required integer parameter specifying the maximum allowed array size (default: 100) diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index 9a74f50ef7..23fc798703 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -858,7 +858,7 @@ Array fields must have a maxItems property defined to enforce an upper bound on Rule checks for the following conditions: - All schema objects with type 'array' must have a maxItems property - - The maxItems value must be set to 100 + - The maxItems value must be set below the threshold of 100 ##### Function options - maxItems: Required integer parameter specifying the maximum allowed array size (default: 100) From c0055d9de8810de092b0ed3e61e5a6680c6b8184 Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 17:34:46 +0100 Subject: [PATCH 11/13] remove the extra file --- openapi/.raw/.ipaspectral.yaml | 36 ---------------------------------- 1 file changed, 36 deletions(-) delete mode 100644 openapi/.raw/.ipaspectral.yaml diff --git a/openapi/.raw/.ipaspectral.yaml b/openapi/.raw/.ipaspectral.yaml deleted file mode 100644 index cd73e22598..0000000000 --- a/openapi/.raw/.ipaspectral.yaml +++ /dev/null @@ -1,36 +0,0 @@ -# https://meta.stoplight.io/docs/spectral/cb95cf0d26b83-core-functions -extends: - - https://raw.githubusercontent.com/mongodb/openapi/a3dd7046e8dccd24bb0eb9ccc9ad8c3e39f47685/tools/spectral/ipa/ipa-spectral.yaml - -overrides: - - files: - - '**#/components/schemas/DataLakeDatabaseDataSourceSettings' # external field, to be covered by CLOUDP-293178 - - '**#/components/schemas/DataLakeAtlasStoreReadPreference' # external field, to be covered by CLOUDP-293178 - rules: - xgen-IPA-123-enum-values-must-be-upper-snake-case: 'off' - - files: - - '**#/components/schemas/DataLakeAtlasStoreInstance' # external field, to be covered by CLOUDP-293178 - rules: - xgen-IPA-112-avoid-project-field-names: 'off' - - files: - - '**#/components/schemas/ClusterProviderSettings/properties/providerName' # dynamic field which can't be documented - - '**#/components/schemas/DataLakeStoreSettings/properties/provider' # external field, to be covered by CLOUDP-293178 - rules: - xgen-IPA-117-description: 'off' - - files: - - '**#/components/schemas/DataLakeAzureBlobStore' # external field, to be covered by CLOUDP-293178 - - '**#/components/schemas/AdvancedClusterDescription/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 - - '**#/components/schemas/AtlasTenantClusterUpgradeRequest20240805/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 - - '**#/components/schemas/ClusterDescription20240805/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 - - '**#/components/schemas/LegacyAtlasCluster/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 - - '**#/components/schemas/LegacyAtlasTenantClusterUpgradeRequest/properties/mongoDBEmployeeAccessGrant' # unable to document exceptions, to be covered by CLOUDP-308286 - - '**#/components/schemas/AdvancedAutoScalingSettings/properties/diskGB' # unable to document exceptions, to be covered by CLOUDP-308286 - - '**#/components/schemas/UserSecurity/properties/customerX509' # unable to document exceptions, to be covered by CLOUDP-308286 - rules: - xgen-IPA-112-field-names-are-camel-case: 'off' - - files: - - '**#/components/schemas/DataLakeS3StoreSettings/allOf/1/properties/additionalStorageClasses' # unable to document exceptions, to be covered by CLOUDP-293178 - - '**#/components/schemas/DataLakeDatabaseDataSourceSettings/properties/databaseRegex' # unable to document exceptions, to be covered by CLOUDP-293178 - - '**#/components/schemas/DataLakeDatabaseDataSourceSettings/properties/collectionRegex' # unable to document exceptions, to be covered by CLOUDP-293178 - rules: - xgen-IPA-117-description-should-not-use-inline-links: 'off' \ No newline at end of file From 319c4d19a63baa587a91ce0d0f44487c18548daf Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Thu, 3 Apr 2025 17:44:44 +0100 Subject: [PATCH 12/13] address the comments --- .../ipa/__tests__/IPA124ArrayMaxItems.test.js | 27 +++++++++++++++---- tools/spectral/ipa/rulesets/IPA-124.yaml | 2 +- tools/spectral/ipa/rulesets/README.md | 2 +- .../rulesets/functions/IPA124ArrayMaxItems.js | 4 +-- 4 files changed, 26 insertions(+), 9 deletions(-) diff --git a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js index afc4851781..211616b255 100644 --- a/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js +++ b/tools/spectral/ipa/__tests__/IPA124ArrayMaxItems.test.js @@ -17,6 +17,13 @@ testRule('xgen-IPA-124-array-max-items', [ type: 'string', }, }, + anotherArrayProperty: { + type: 'array', + maxItems: 50, + items: { + type: 'string', + }, + }, }, }, }, @@ -81,7 +88,8 @@ testRule('xgen-IPA-124-array-max-items', [ errors: [ { code: 'xgen-IPA-124-array-max-items', - message: 'Array maxItems must be set below 100, found: 101.', + message: + 'The maxItems value for arrays must be set to 100 or below, found: 101. If the array field has the chance of being too large, the API should use a sub-resource instead.', path: ['components', 'schemas', 'InvalidSchema', 'properties', 'arrayProperty'], severity: DiagnosticSeverity.Warning, }, @@ -121,10 +129,10 @@ testRule('xgen-IPA-124-array-max-items', [ properties: { outerArray: { type: 'array', - maxItems: 100, + maxItems: 500, arrayProperty: { type: 'array', - maxItems: 101, + maxItems: 500, items: { type: 'string', }, @@ -138,7 +146,15 @@ testRule('xgen-IPA-124-array-max-items', [ errors: [ { code: 'xgen-IPA-124-array-max-items', - message: 'Array maxItems must be set below 100, found: 101.', + message: + 'The maxItems value for arrays must be set to 100 or below, found: 500. If the array field has the chance of being too large, the API should use a sub-resource instead.', + path: ['components', 'schemas', 'NestedArrays', 'properties', 'outerArray'], + severity: DiagnosticSeverity.Warning, + }, + { + code: 'xgen-IPA-124-array-max-items', + message: + 'The maxItems value for arrays must be set to 100 or below, found: 500. If the array field has the chance of being too large, the API should use a sub-resource instead.', path: ['components', 'schemas', 'NestedArrays', 'properties', 'outerArray', 'arrayProperty'], severity: DiagnosticSeverity.Warning, }, @@ -339,7 +355,8 @@ testRule('xgen-IPA-124-array-max-items', [ errors: [ { code: 'xgen-IPA-124-array-max-items', - message: 'Array maxItems must be set below 100, found: 500.', + message: + 'The maxItems value for arrays must be set to 100 or below, found: 500. If the array field has the chance of being too large, the API should use a sub-resource instead.', path: [ 'paths', '/api/resources', diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index 7442700636..e82f54228e 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -7,7 +7,7 @@ functions: rules: xgen-IPA-124-array-max-items: description: | - Array fields must have a maxItems property defined to enforce an upper bound on the number of items (default: 100). + Array fields must have a maxItems property defined to enforce an upper bound on the number of items (recommended max: 100). If the array field has the chance of being too large, the API should use a sub-resource instead.. ##### Implementation details Rule checks for the following conditions: diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index 23fc798703..6cc4e7615d 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -852,7 +852,7 @@ Rules are based on [http://go/ipa/IPA-124](http://go/ipa/IPA-124). #### xgen-IPA-124-array-max-items ![warn](https://img.shields.io/badge/warning-yellow) -Array fields must have a maxItems property defined to enforce an upper bound on the number of items (default: 100). +Array fields must have a maxItems property defined to enforce an upper bound on the number of items (recommended max: 100). If the array field has the chance of being too large, the API should use a sub-resource instead.. ##### Implementation details Rule checks for the following conditions: diff --git a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js index 754c8238c5..91429dd3ae 100644 --- a/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js +++ b/tools/spectral/ipa/rulesets/functions/IPA124ArrayMaxItems.js @@ -55,11 +55,11 @@ function checkViolationsAndReturnErrors(input, path, maxItems) { }, ]; } - // Check if maxItems is set to the required value + // Check if maxItems is larger than the recommended value else if (input.maxItems > maxItems) { return [ { - message: `Array maxItems must be set below ${maxItems}, found: ${input.maxItems}.`, + message: `The maxItems value for arrays must be set to ${maxItems} or below, found: ${input.maxItems}. If the array field has the chance of being too large, the API should use a sub-resource instead.`, path, }, ]; From 537dccadf840e1c216a6d4d843467a1adf2c311d Mon Sep 17 00:00:00 2001 From: Yeliz Henden Date: Fri, 4 Apr 2025 09:50:18 +0100 Subject: [PATCH 13/13] address the comments --- tools/spectral/ipa/rulesets/IPA-124.yaml | 2 +- tools/spectral/ipa/rulesets/README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/tools/spectral/ipa/rulesets/IPA-124.yaml b/tools/spectral/ipa/rulesets/IPA-124.yaml index e82f54228e..bac3432f43 100644 --- a/tools/spectral/ipa/rulesets/IPA-124.yaml +++ b/tools/spectral/ipa/rulesets/IPA-124.yaml @@ -7,7 +7,7 @@ functions: rules: xgen-IPA-124-array-max-items: description: | - Array fields must have a maxItems property defined to enforce an upper bound on the number of items (recommended max: 100). If the array field has the chance of being too large, the API should use a sub-resource instead.. + Array fields must have a maxItems property defined to enforce an upper bound on the number of items (recommended max: 100). If the array field has the chance of being too large, the API should use a sub-resource instead. ##### Implementation details Rule checks for the following conditions: diff --git a/tools/spectral/ipa/rulesets/README.md b/tools/spectral/ipa/rulesets/README.md index 6cc4e7615d..98d0babcf3 100644 --- a/tools/spectral/ipa/rulesets/README.md +++ b/tools/spectral/ipa/rulesets/README.md @@ -852,7 +852,7 @@ Rules are based on [http://go/ipa/IPA-124](http://go/ipa/IPA-124). #### xgen-IPA-124-array-max-items ![warn](https://img.shields.io/badge/warning-yellow) -Array fields must have a maxItems property defined to enforce an upper bound on the number of items (recommended max: 100). If the array field has the chance of being too large, the API should use a sub-resource instead.. +Array fields must have a maxItems property defined to enforce an upper bound on the number of items (recommended max: 100). If the array field has the chance of being too large, the API should use a sub-resource instead. ##### Implementation details Rule checks for the following conditions: