feature: assertions

Request for comments

This feature request is not yet actionable. We need to collect some feedback first.

---

Is your feature request related to a problem? Please describe. We need a generic rules to be used in cases which our other built-in rules do not cover.

Describe the solution you’d like I’d like to have a set of built-in rules which can be configured to enforce different generic usecases:

• enum to enforce a value to be among set of predefined values
• pattern - to enforce a value to match a regex
• casing - to enforce specific casing style (camelCase, kebab-case, snake_case, PascalCase)
• mutuallyExclusive - to mark some properties as mutually exclusive (a or b but not a and b together)
• defined/undefined/nonEmpty
• length - to enforce length of specific array or string
• sortOrder - to enforce sort order in array of strings or array of objects (collection)

Example usage:

lint:
  rules:
    enforcements: # I would like a better suggestion here
      - on: SecuritySchema.type
        description: Only API key authorization is allowed
        severity: error
        enum:
          - apiKey
      - on: 'MediaTypeMap.$keys'
          enum:
          - apiKey
        - on: MediaTypeMap.$keys
          description: Only application/json can be used
          enum:
            - 'application/json'
    nonEmpty:
      description: Schema title and description should be non-empty
      locations:
        - on: Schema.description
        - on: Schema.title

Additional context none

[jacobator]

I like per-key approach better (allowing “on” to be an array makes it even better)

[slavikbez]

Do you see any issues with the suggested format that can complicate the UI in the future.

Depending on the selected format the UI will be different. In the original case we’re grouping by node type and I see flow in the UI like the following: (you may think of chain items as form controls):

select node type(s) -> select rule(s) -> provide rule(s) values -> severity -> description -> etc.

In the alternative case we’re grouping by rule and then pull in node types, so in the UI selecting rule should go before selecting node type:

select rule(s) -> select node type(s) -> provide rule(s) values -> severity -> description -> etc.

Also, what do you think about enforcements approach vs alternative per-rule approach?

I prefer the enforcements approach. For me it’s more naturally when you take a node and then describe a rule for it, not vice versa. Other benefits from it what I see so far are:

1. Easier to generate code for the rule. For example this configuration

    - on: # on can be an array too
          - Schema.description
          - Schema.title
        nonEmpty: true
        regex: '/.$/' # we can also apply also other enforcements
        description: Schema description and title should be non-empty and should end with a dot.
   

   will result in 4 different rules:

   • schema-description-non-empty
   • schema-description-regex
   • schema-title-non-empty
   • schema-title-regex

2. With more atomic rules we will get more granularity for severity and error messages