feat(new-rule): ibm-schema-casing-convention

dpopp07 commented 1 year ago

This adds a new rule to verify that schema names (i.e. the keys in the 'schemas' object in the 'components' object) are upper camel case, as specified in the API Handbook.

PR summary

PR Checklist

General checklist

Please make sure that your PR fulfills the following requirements:

[x] The commit message follows the Angular Commit Message Guidelines.
[x] Tests for the changes have been added (for bug fixes / features)
[x] Docs have been added / updated (for bug fixes / features)
[x] Dependencies have been updated as needed
[x] .secrets.baseline updated as needed?

Checklist for adding a new validation rule:

[x] Added new validation rule definition (packages/ruleset/src/rules/*.js, index.js)
[x] If necessary, added new validation rule implementation (packages/ruleset/src/functions/*.js, updated index.js)
[x] Added new rule to default configuration (packages/ruleset/src/ibm-oas.js)
[x] Added tests for new rule (packages/ruleset/test/*.test.js)
[x] Added docs for new rule (docs/ibm-cloud-rules.md)

dpopp07 commented 12 months ago

I was wondering if we should consider checking the name and/or title fields

That's a good question, needed to take some time to think it through. I'm not sure if there is a name field for schemas, but from what I read in the JSONSchema spec, title seems to be a field to declare the purpose of the schema, not give it a name. I can't remember if we use it for SDK Gen or not but even if we do, tooling isn't as much in scope IMO since we adjust casing per language anyways.

Another thing is, we do have a rule to check for schemas not being defined inline. For the exceptions to that rule, we probably don't need names anyways and so I don't think they're important to check with this rule. That said - I will mark this rule dependent on that rule. Something I'm trying to get in the habit of is view the rules as atomic but still inter-connected and allow rules to make assumptions based on what we check for in other rules. I want to keep track of what those assumptions are in the comments and I missed that for that rule, so I'm glad you reminded me!

In terms of implementation, I think I would advocate for keeping the check limited to components.schemas. Let me know how you feel about that

padamstx commented 12 months ago

Let me know how you feel about that

That's fine.

IBM / openapi-validator