I find myself in a lot of “rules don’t matter” conversations with folks, telling me that Spectral rules alone won’t govern enterprise API operations. It is a perspective that also plagues OpenAPI and other artifacts, where people think having OpenAPI won’t fix API operations either. This is the same mindset that has allowed artificial intelligence to spread—-people who see outputs as the thing, content, JSON, YAML, Markdown, and code as the thing, and refuse to see any of the human things that go into the thing. People are right when they say 250 Spectral rules aren’t going to fix API operations, but you know what does?
- People Understanding - People producing APIs learning about a specific pattern that is expressed as a rule.
- People Coordinating - People working together to refine and evolve a rule to meet the needs across teams.
- Schema Awareness - People doing the work to dial in the JSON path reference to a specific aspect of schema.
- Policy Provenance - People being able to get up to speed on the provenance of why a policy exists for a rule.
- Consistent Automation - Being able to consistently automate the shared understanding expressed within a single rule.
The value of OpenAPI rarely is the OpenAPI itself-—it is the work and collaboration going into the OpenAPI. The value of a Spectral rule is rarely the rule itself—it is the work, provenance, and guidance represented by the rule. Technologists tend to only see technology, and miss all of the human bits that go into making something happen, as well as something good happen. If you see artifacts as simple outputs that configure a system, they will rarely accomplish what you need, but if you see them as an accumulation of the work done by humans across teams to align and configure the humans and the machines, you are going to get closer to hitting that target you envision.
