Document Types aka "Formats"

[philsturgeon]

Let's list out all the formats we'd like to support.

OAI and friends:

• OpenAPI
• AsyncAPI
• Arazzo
• Overlays
• OpenLint Rulesets (meta!)

Do we want to specifically try and cover JSON Schema seperately now that we're mostly past the OpenAPI Schema <!=> JSON Schema issues?

What about the following:

• GitHub Actions

This is not intended to be a list of Core Rulesets (as in, we don't need to write rules for all these), it's just a list of formats that we can recognise, which folks might want to write their own rulesets to be applied if matched.

[kinlane]

+1 on covering JSON Schema!

[kinlane]

Markdown will be important.

[joostfarla]

Small terminology nit: could we call these "document types" (or something similar) rather than "formats"? "Format" usually refers to serialization (JSON/YAML), while OpenAPI, AsyncAPI, Arazzo, etc. are document/spec types. Not a blocker, but this distinction may be useful later.

[philsturgeon]

I've renamed for the sake of the discussion at least, and we can decide if the change should make it through to the code because formats is a thing in Spectral currently.

$ tree packages/formats/src
packages/formats/src
├── arazzo.ts
├── asyncapi.ts
├── index.ts
├── jsonSchema.ts
└── openapi.ts

There are "formats" and "formatters" which are nothing to do with each other, with formatters being the result output format: JUnit, GitHub Actions, Markdown. I'd be happy to see the situation improved as I think it's already caused confusion in this thread. Am I right @kinlane?

At Stoplight I made attempts to standardize the way we talk about different types of format, with "Description Formats" (OpenAPI, JSON Schema), Message Formats like JSON-API, HAL, Siren, etc, and "Data Formats" like JSON, YAML. I put this into https://github.com/apisyouwonthate/api-glossary too out of sheer desperation for standard language beyond just what Stoplight was up to.

[joostfarla]

Thanks for renaming, and good to see your glossary already covers part of this. I think the issue isn't the word "format" itself, but using it on its own for different things, like Spectral does. So I'd always qualify it:

• Document type: what a ruleset targets (OpenAPI, AsyncAPI, GitHub Actions workflow, Markdown)
• Serialization format: how a document is stored or exchanged (JSON, YAML)
• Result format: how a linter reports its results (SARIF, JUnit XML, Spectral's JSON output)

I'd avoid "description" in the name. The term fits OpenAPI/AsyncAPI/Arazzo, but is less suitable for Overlays, OpenLint rulesets, GitHub Actions workflows and Markdown, which are all on the list.

[jerzyn]

linting openlint rulesets should be a core feature IMHO.

Github-style actions could be an interesting direction. I'd put on the list also:

• GraphQL SDL - this is not yaml anymore, but good for completing the "API Area" within an organization
• cloud events
• protobuff - also not a yaml