From a Document to a Check

A convention that nothing checks is a description of the past. It was true when somebody wrote it, and it drifts from that day forward at the speed your team ships.

This chapter is about which half of a style guide a machine can carry, and what the other half is then free to do.

What a check can see

A checker reads one document and answers questions about it. Four kinds of question cover almost everything worth automating.

Presence. Does this operation have a summary, does this parameter have a description, does this endpoint declare an error response. These are the rules that decide whether generated documentation is readable.

Form. Does this name match the convention, does this server URL use HTTPS, does this path contain a query string. Pattern matching is cheap and it catches the drift that accumulates one endpoint at a time.

Uniqueness. Do two operations share an identifier, do two paths resolve to the same route, does an enum repeat a value. These produce real defects downstream rather than untidiness.

Agreement. Does the path template match the declared parameters, does every reference resolve, does the example validate against the schema it illustrates. This is the most valuable group, because a document that disagrees with itself misleads every reader and every generator.

What a check will never see

The boundary is sharper than it looks, and it is worth naming so that nobody expects the tool to hold the line alone.

A checker cannot tell you whether the resource model fits the domain. It will happily approve an API where a single POST /process hides four different operations, because the document is perfectly well formed.

It cannot tell you whether a name means anything. GET /items/{id} passes every naming rule ever written, and so does a field called data2.

It cannot tell you whether a description is true. A summary that was accurate two releases ago satisfies the presence rule forever.

It cannot tell you whether this endpoint should exist. Duplication across two teams is invisible to a tool that reads one document at a time.

The rules in the middle

Between the two groups sits a band of rules that are right most of the time, and those are the ones that decide whether people trust the output.

A rule that flags schema properties whose names look like passwords or card numbers is a heuristic. It will occasionally be wrong, and it is worth keeping, because the case it catches is expensive. A rule that requires pagination parameters on every operation returning a collection is also a heuristic, and it will fire on the endpoint that legitimately returns a fixed set of nine currencies.

Judge these by what a false positive costs. If somebody can dismiss it in five seconds, it belongs at a low severity and it earns its place. If it requires an argument every time, it will train people to stop reading the output, which costs you the rules that were never wrong.

Turning a sentence into a condition

A written convention becomes checkable by splitting it into three parts, and the sentence usually resists the first attempt.

Take the house rule that every operation must be owned by a team. The check needs a target, which is the operation, a field, which is the description or an extension, and a condition, which is that the field matches a pattern naming a known team. If none of the three can be filled in, the rule is not checkable as written, and the useful move is to change the convention rather than to give up.

Sometimes that change is an improvement on its own. A rule that cannot be expressed usually turns out to be two rules, or one rule and an opinion. Rules of your own covers what a condition can carry and where that stops.

Where the check has to run

The same rule produces a different result depending on where it fires.

A check that runs while somebody is editing is a correction, because the person who made the decision is still in the file and the fix costs seconds. A check that runs in a nightly report is a list, and lists accumulate. By the time anyone reads it, the author has moved on and each entry has become an archaeology task.

The practical arrangement is two points rather than one. Rules run continuously while the description is being written, and they run again when a version is released, which is where the small set of blocking rules belongs. Validating and linting OpenAPI covers the mechanics of running the rules themselves.

What a review is for afterwards

Automating the mechanical half is what makes a design review worth attending.

A review that spends forty minutes on plural nouns and missing descriptions is doing a tool's job slowly. Once those never reach the meeting, the same forty minutes can go to the questions nothing else will ask. Does this resource model match how the business talks about the thing. Is this endpoint a duplicate of one another team already ships. What happens to a caller when this fails, and can they tell the difference between the three ways it can.

That is the split worth aiming for. The machine takes everything that has a right answer, and the people take everything that does not.

In Routebase

The built-in rules cover the four question types above, and they run against the specification you are editing rather than against a file you remember to lint.

Violations appear in an issues panel at the bottom of the designer, grouped by rule, with per-severity counts that double as filters. Many carry a one-click fix, and a single button applies every available fix at once, which is what makes the first pass over an imported API survivable. A summary badge sits in the header, the endpoint and schema tree carries badges whose tooltips list the violations, and the publish dialog lists whatever is left.

Custom rules cover the house conventions that have no built-in equivalent, within the limits the next chapter describes. The Style Guide guide covers the rules and where each violation surfaces.