Skip to content

CLOUDP-272001: IPA-112: Disallow usages of project in the api #566

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 5 commits into from
Mar 19, 2025
Merged

CLOUDP-272001: IPA-112: Disallow usages of project in the api #566

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
372fc95
CLOUDP-272001: IPA-112: Disallow usages of project in the api
yelizhenden-mdb Mar 19, 2025
2ba7eac
fixes
yelizhenden-mdb Mar 19, 2025
456f9b0
prettier fix
yelizhenden-mdb Mar 19, 2025
63174ba
address the comments
yelizhenden-mdb Mar 19, 2025
35a1f9e
prettier fix
yelizhenden-mdb Mar 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
234 changes: 234 additions & 0 deletions tools/spectral/ipa/__tests__/IPA112AvoidProjectFieldNames.test.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,234 @@
import testRule from './__helpers__/testRule';
import { DiagnosticSeverity } from '@stoplight/types';

testRule('xgen-IPA-112-avoid-project-field-names', [
{
name: 'valid schema - no project field names',
document: {
components: {
schemas: {
SchemaName: {
properties: {
group: { type: 'string' },
groupId: { type: 'string' },
otherField: { type: 'number' },
},
},
},
},
},
errors: [],
},
{
name: 'invalid schema - with project field name',
document: {
components: {
schemas: {
SchemaName: {
properties: {
project: { type: 'string' },
},
},
},
},
},
errors: [
{
code: 'xgen-IPA-112-avoid-project-field-names',
message: 'Field name "project" should be avoided. Consider using "group" instead.',
path: ['components', 'schemas', 'SchemaName', 'properties', 'project'],
severity: DiagnosticSeverity.Warning,
},
],
},
{
name: 'invalid schema - with projects field name',
document: {
components: {
schemas: {
SchemaName: {
properties: {
projects: { type: 'array' },
},
},
},
},
},
errors: [
{
code: 'xgen-IPA-112-avoid-project-field-names',
message: 'Field name "projects" should be avoided. Consider using "group" instead.',
path: ['components', 'schemas', 'SchemaName', 'properties', 'projects'],
severity: DiagnosticSeverity.Warning,
},
],
},
{
name: 'invalid schema - with projectId field name',
document: {
components: {
schemas: {
SchemaName: {
properties: {
projectId: { type: 'string' },
},
},
},
},
},
errors: [
{
code: 'xgen-IPA-112-avoid-project-field-names',
message: 'Field name "projectId" should be avoided. Consider using "group" instead.',
path: ['components', 'schemas', 'SchemaName', 'properties', 'projectId'],
severity: DiagnosticSeverity.Warning,
},
],
},
{
name: 'invalid schema - with different case variants',
document: {
components: {
schemas: {
SchemaName: {
properties: {
Project: { type: 'string' },
PROJECTID: { type: 'string' },
},
},
},
},
},
errors: [
{
code: 'xgen-IPA-112-avoid-project-field-names',
message: 'Field name "Project" should be avoided. Consider using "group" instead.',
path: ['components', 'schemas', 'SchemaName', 'properties', 'Project'],
severity: DiagnosticSeverity.Warning,
},
{
code: 'xgen-IPA-112-avoid-project-field-names',
message: 'Field name "PROJECTID" should be avoided. Consider using "group" instead.',
path: ['components', 'schemas', 'SchemaName', 'properties', 'PROJECTID'],
severity: DiagnosticSeverity.Warning,
},
],
},
{
name: 'invalid schema with exception - project field name with exception',
document: {
components: {
schemas: {
SchemaName: {
properties: {
project: {
type: 'string',
'x-xgen-IPA-exception': {
'xgen-IPA-112-avoid-project-field-names': 'reason',
},
Comment on lines +126 to +128
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Q: Is it possible to have exceptions on properties? IIRC when we did the enum rule we had to have the exception on the schema

Copy link
Collaborator Author

@yelizhenden-mdb yelizhenden-mdb Mar 19, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

For enum one, we have the exceptions on the property level. Ex:


"roleName": {
            "description": "Human-readable label that identifies a group of privileges assigned to a database user. This value can either be a built-in role or a custom role.",
            "enum": [
              "atlasAdmin",
               ...
            ],
            "type": "string",
            "x-xgen-IPA-exception": {
              "xgen-IPA-123-enum-values-must-be-upper-snake-case": "Schema predates IPA validation"
            }
          }

which is equivalent of Schema annotation for the property itself on Java. I kept the same level for exception. Are you asking keeping the exception level for Schema annotation level but for the schema level?

Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah thanks for clarifying, I misremembered and thought it was on the schema level higher up. LGTM 👍

},
},
},
},
},
},
errors: [],
},
{
name: 'field name containing project substring',
document: {
components: {
schemas: {
SchemaName: {
properties: {
myProjectDetails: { type: 'object' },
},
},
},
},
},
errors: [
{
code: 'xgen-IPA-112-avoid-project-field-names',
message: 'Field name "myProjectDetails" should be avoided. Consider using "group" instead.',
path: ['components', 'schemas', 'SchemaName', 'properties', 'myProjectDetails'],
severity: DiagnosticSeverity.Warning,
},
],
},
{
name: 'exception - field with project substring',
document: {
components: {
schemas: {
SchemaName: {
properties: {
myProjectDetails: {
type: 'object',
'x-xgen-IPA-exception': {
'xgen-IPA-112-avoid-project-field-names': 'Reason',
},
},
},
},
},
},
},
errors: [],
},
{
name: 'exception - multiple project fields',
document: {
components: {
schemas: {
SchemaName: {
properties: {
projectId: {
type: 'string',
'x-xgen-IPA-exception': {
'xgen-IPA-112-avoid-project-field-names': 'Reason',
},
},
projects: {
type: 'array',
'x-xgen-IPA-exception': {
'xgen-IPA-112-avoid-project-field-names': 'Reason',
},
},
},
},
},
},
},
errors: [],
},
{
name: 'mixed valid, invalid, and exception fields',
document: {
components: {
schemas: {
SchemaName: {
properties: {
project: {
type: 'string',
'x-xgen-IPA-exception': {
'xgen-IPA-112-avoid-project-field-names': 'Reason',
},
},
projectId: { type: 'string' },
group: { type: 'string' },
},
},
},
},
},
errors: [
{
code: 'xgen-IPA-112-avoid-project-field-names',
message: 'Field name "projectId" should be avoided. Consider using "group" instead.',
path: ['components', 'schemas', 'SchemaName', 'properties', 'projectId'],
severity: DiagnosticSeverity.Warning,
},
],
},
]);
1 change: 1 addition & 0 deletions tools/spectral/ipa/ipa-spectral.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ extends:
- ./rulesets/IPA-107.yaml
- ./rulesets/IPA-108.yaml
- ./rulesets/IPA-109.yaml
- ./rulesets/IPA-112.yaml
- ./rulesets/IPA-113.yaml
- ./rulesets/IPA-123.yaml

Expand Down
26 changes: 26 additions & 0 deletions tools/spectral/ipa/rulesets/IPA-112.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
# IPA-112: Field Names
# http://go/ipa/112

functions:
- IPA112AvoidProjectFieldNames

rules:
xgen-IPA-112-avoid-project-field-names:
description: |
Schema field names should avoid using "project", "projects", or "projectId".

##### Implementation details
Rule checks for the following conditions:
- Searches through all schemas in the API definition
- Identifies property names that match "project" (case-insensitive)
- Reports any instances where these field names are used
- Suggests using "group", "groups", or "groupId" as alternatives
message: '{{error}} https://mdb.link/mongodb-atlas-openapi-validation#xgen-IPA-112-avoid-project-field-names'
severity: warn
given: '$.components.schemas..properties[*]~'
then:
function: 'IPA112AvoidProjectFieldNames'
functionOptions:
prohibitedFieldNames:
- name: 'project'
alternative: ['group']
18 changes: 18 additions & 0 deletions tools/spectral/ipa/rulesets/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -426,6 +426,24 @@ Rule checks for the following conditions:



### IPA-112

Rules are based on [http://go/ipa/IPA-112](http://go/ipa/IPA-112).

#### xgen-IPA-112-avoid-project-field-names

![warn](https://img.shields.io/badge/warning-yellow)
Schema field names should avoid using "project", "projects", or "projectId".

##### Implementation details
Rule checks for the following conditions:
- Searches through all schemas in the API definition
- Identifies property names that match "project" (case-insensitive)
- Reports any instances where these field names are used
- Suggests using "group", "groups", or "groupId" as alternatives



### IPA-113

Rules are based on [http://go/ipa/IPA-113](http://go/ipa/IPA-113).
Expand Down
52 changes: 52 additions & 0 deletions tools/spectral/ipa/rulesets/functions/IPA112AvoidProjectFieldNames.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,52 @@
import { hasException } from './utils/exceptions.js';
import {
collectAdoption,
collectAndReturnViolation,
collectException,
handleInternalError,
} from './utils/collectionUtils.js';
import { resolveObject } from './utils/componentUtils.js';

const RULE_NAME = 'xgen-IPA-112-avoid-project-field-names';

export default (input, options, { path, documentInventory }) => {
const oas = documentInventory.resolved;
const property = resolveObject(oas, path);

if (hasException(property, RULE_NAME)) {
collectException(property, RULE_NAME, path);
return;
}

const errors = checkViolationsAndReturnErrors(input, options, path);
if (errors.length !== 0) {
return collectAndReturnViolation(path, RULE_NAME, errors);
}
collectAdoption(path, RULE_NAME);
};

function checkViolationsAndReturnErrors(input, options, path) {
try {
const prohibitedFieldNames = options?.prohibitedFieldNames || [];
const lowerPropertyName = input.toLowerCase();

// Check if the property name includes any of the prohibited terms
for (const prohibitedItem of prohibitedFieldNames) {
const prohibitedName = prohibitedItem.name || '';
const alternative = prohibitedItem.alternative || '';

if (lowerPropertyName.includes(prohibitedName.toLowerCase())) {
return [
{
path,
message: `Field name "${input}" should be avoided. Consider using ${alternative.map((alt) => `"${alt}"`)} instead.`,
},
];
}
}

return [];
} catch (e) {
handleInternalError(RULE_NAME, path, e);
}
}
Loading