Provide a way to enforce file names

[rkrauskopf]

Currently, you can only create visitors for a node type. We would like to be able specify a visitor for a file.

An example would be if I would like to enforce that all the schemas in a file need to be in alphabetical order.

Currently, to add rules for a specific file I have to specify a random OpenAPISchema type definition in a rule, check that the context.filePath is in the file that I expect, and then apply my validation rules.

[RomanHotsiy]

Oh, that's an interesting idea. We're not sure how to fit into our internal concept.

We will discuss it internally and get back to you soon.

[JamesMessinger]

This would be a killer feature for us. We want to use openapi-cli as a linter that enforces a consistent folder/file structure in all of our APIs, so any developer in the company can easily work on any API in the company without having to learn a new structure each time. Here's the structure that we're enforcing:

|-- openapi.yaml      (the main/entry file)
|-- info.yaml         (the info section)
|-- tags.yaml         (the tags section)
|-- paths/
| |-- foo/
|   |-- bar/
|     |-- path.yaml   (the definition of the /foo/bar path)
|     |-- get.yaml    (the definition of the GET /foo/bar operation)
|     |-- post.yaml   (the definition of the POST /foo/bar operation)
|
|-- schemas/
  |-- enums.yaml      (all enumerations are defined here)
  |-- fizz.yaml       (the JSON schema for fizz objects)
  |-- buzz.yaml       (the JSON schema for buzz objects)

So we need to be able to create file-level rules such as:

• The main entry file of the API definition must be named openapi.yaml
• info.yaml must exist and must contain the API's info section
• tags.yaml must exist and must contain the list of tags
• Every path in the API must have a corresponding paths/xxx/yyy/path.yaml file
• Every operation in the API must have a corresponding paths/xxx/yyy/VERB.yaml file
• Every object schema must be defined in a corresponding schemas/xxx.yaml file
• All enumerations must be in enums.yaml
• The enumerations in enums.yaml must be in alphabetical order

[adamaltman]

@JamesMessinger what are you doing in the case of path parameters with your paths folder structure? For example:

• foo/get.yaml <-- gets a collection of foos
• foo/{id}/get.yaml <-- gets a foo with a specific {id}

[JamesMessinger]

Yes, exactly. Path parameters are just part of the folder structure.

[adamaltman]

This is done (I think). @RomanHotsiy we should add an example of enforcing file names. For example, Rebilly uses PascalCase for component file names with two exceptions: headers (some hybrid of kebab-case and PascalCase == Kebab-Case) and parameters (camelCase). How about a sample rule that enforces a particular case for filenames.

[adamaltman]

@RomanHotsiy this is effectively done with the $ref assertion, right?

[RomanHotsiy]

Not exactly but it can be used for some file-names checks for sure.

[adamaltman]

I'm going to close this since it can be used for $ref filename checks. I'm not sure what other filename would want to be checked besides the root file?