Aliases everywhere for everyone

[philsturgeon]

The Aliases feature in Spectral was little known and little used, as it was very early on in its development when progress froze.

The idea was to help 90% of people never have to touch a JSONPath, unless they really really wanted to, because most of us really don't like using it, myself included and I've built more Spectral Rulesets than anyone.

• JSONPath is very flexible but having to write selectors like given: "$.paths[*]..responses[?(@property.match(/^(4|5)/))].content.*~", makes you feel like you're paired programming with a very skittish horse who cannot stop kicking you in the head.
• Redocly and Speccy used "Named Identifiers" which are OpenAPI specific, then trying to target other bits of a document or other formats gets hard.

Aliases provide a middleground, where particular selectors can be nicknamed then the nickname used over the JSONPath.

aliases:
  HeaderNames:
    - "$..parameters.[?(@.in === 'header')].name"
  Info:
    - "$..info"
  InfoDescription:
    - "#Info.description"
  ErrorResponseContent:
    - "$.paths[*]..responses[?(@property.match(/^(4|5)/))].content"
  Paths:
    - "$.paths[*]~"

Notice how with the #Info.description the #Info is actually another alias, so you can do a minor bit of JSONPathing to modify the results instead of having to go 100% head injury every time.

Implementation

From memory, and from kicking around the code, I cannot find any default list for OAS2 or OAS3, meaning it's possible the list was only defined in the hosted Stoplight Platform version of Spectral.

The goal for me was always to try and get Aliases into not just the spectral:oas ruleset, but the "OpenAPI Format". If "core aliases" could be bound to a format, then anyone creating any ruleset for anything OpenAPI could use the core OAS aliases and never have to think about JSONPath unless they wanted to do something off menu.

[mikekistler]

+1 to allowing aliases to be bound to formats. As a corollary to this, it might be nice to allow the same alias name to be defined for different formats. This could be useful, e.g., so that schemas could be "$.definitions[]" in oas2 and "#.components.schemas[]" in oas3.x.

I'd also like to throw in the idea of "custom aliases" ... along the same lines as "custom functions". The idea here is that you could define an alias that is defined by a function that returns an enumeration of elements from the document. An example of where this would be useful is again schemas, since these can show up in so many places in an OpenAPI doc.

[philsturgeon]

Absolutely. The best way to think of aliases is that they only exist currently as "custom aliasas", and we want "core aliases" tied to the format, but we still need the custom functionality so people can define their own aliases for a ruleset or an organization or whatever.