Glossary

In brief

• Every term below means something specific here, and nothing to a reader who has not met it yet.
• Each row is one clause, and the term links to the section where the concept is actually argued.
• The grouping is by owning document, so this page doubles as a map of which guide owns which idea.
• When a row and the document it points at disagree, the document is right and the row is a bug.

This set invents vocabulary, and it is right to: drift and Deferred and the marker are each precise, and each of them means nothing on first contact. Every guide links a term here the first time it uses one, which is the rule this page exists to serve, so a reader who starts in the middle of a document is one click from the word that stopped them.

It carries no reasoning, deliberately. A definition and its justification in two places is the shape the same rules forbid, because the copy is what goes stale. So a row is a clause and a pointer, short enough that it cannot drift into a second explanation, and the section it links to is the authority.

OpenAPI Support

What the package reads, and what it refuses to. openapi-support.md.

Term	In one clause
Support level	One of five verdicts the package publishes for every OpenAPI construct: Supported, Partial, Ignored, Deferred or Rejected.
Deferred	The level meaning recognized, planned, and not built yet, as against Ignored, which is not planned.
Rejected	The level meaning the package refuses the document rather than serving it wrong.
Fault	Something wrong the reading pipeline found, carried back with whatever it still managed to read rather than thrown.

Code Generation

The build itself

code-generation/index.md.

Term	In one clause
The invariant	The one property every build rule serves: a build never destroys human work, on any machine, however many times it runs.
The generated tree	The directory and namespace the build owns completely, app/Http/Generated by default.
The marker	The @generated by lara-spec-first line every generated file carries, and the only thing that lets the build delete a file.
Pruning	The build removing a generated file the contract no longer describes, touching nothing that lacks the marker.
The two layers	The interface and the abstract class the build emits for one generated type, split so a project can commit the small one and ignore the noisy one.
The split	A generated abstract or interface extended by a class a human writes, which is what turns a contract change into a static analysis error.

Anatomy of a generated file

generated-file-anatomy.md.

Term	In one clause
The source map	The JSON pointer every generated file carries, naming the exact position in the specification it came from.
An operation's identity	Its path and HTTP method with path parameters reduced to positions, as against its name, which is what the build generates from.

Scaffolding, publishing and DTOs

Term	In one clause
Scaffolding	spec:make creating one file you will own, on request, which the build itself never does.
The public copy	The sanitized specification the build can emit for publication, with internal operations removed. Not built yet.
A DTO factory	The generated class beside a response DTO whose one job is building it, and the seam a project overrides instead of the DTO. Not built yet.

Controllers

The controller of one operation. controllers.md.

Term	In one clause
routeAction	The one method every generated controller carries, and the only method a route ever points at.
SpecController	The single thin abstract base every generated controller extends, holding no per-operation knowledge.
The two-class seam	The generated parent and the custom child an operation gets when it declares x-controller, found by name rather than by a scan.
x-controller	The extension naming an operation's custom controller, and the only thing that makes a generated controller extendable.
x-model	The extension naming an operation's Eloquent model, which is what turns on route-model binding and the CRUD defaults.
A marker interface	An empty interface a generated controller implements to state the CRUD semantic the build detected, carrying no methods on purpose.
HasModel and InteractsWithModel	The interface declaring the model contract, and the trait shipping the half of it that can be written once for everyone.

The Doctor

What the package reports about your contract. doctor.md.

Term	In one clause
Document fault	A finding whose owner is the specification's author: the document is invalid, inconsistent, or breaks a rule this package requires.
Package limit	A finding whose owner is this package: the document is correct and the construct is not honored.
Drift	The generated code and the specification disagreeing, which is what happens when somebody edits the contract and forgets to build.
Shadowing	An earlier templated path matching every request a later one was meant to answer, so the later route never runs.
An acknowledgement	A consumer's recorded opt-out of a package limit, which changes what the doctor does rather than only what it prints.

Operation Lifecycle

How strong a promise an operation carries. lifecycle.md.

Term	In one clause
x-audience	The extension saying who an operation is promised to, public or internal; absent means public.
x-lifecycle	The extension saying how strong that promise is, beta or stable; a public operation that says nothing is beta.
x-sunset	The extension stating the date an endpoint stops being served, which a deprecation is required to carry.
The baseline	The previously committed version of the specification, read from git, that a breaking-change comparison runs against.
The protection report	The doctor line counting how many public operations are actually stable, so protection that is off never looks like protection that passed.
The sunset horizon	The configurable number of days before a sunset date at which the doctor starts mentioning it, 90 by default.

Drivers, pagination and rate limiting

The mechanism behind every feature OpenAPI never standardized, and the two features built on it.

Term	In one clause
A driver	A class that knows where a structure is declared in a document, and never what this project calls its fields.
A mapping	The configuration naming those fields for one project, which is what makes the driver beside it portable.
The envelope	The wrapper a paginated response puts its collection in, generated as its own DTO per paginated operation.
A window	The period a rate limit is expressed over, plural from the first release rather than assumed to be a minute.

Remote References

A $ref that reaches over the network. remote-references.md.

Term	In one clause
A vendored reference	A remote $ref fetched once, on request, and committed into the repository as a dependency rather than a cache entry.
The allowlist	The configured set of hosts a remote reference may be fetched from, empty by default so nothing is fetched until a project says so.

What this document does not cover

• Any reason at all. A row states what a term means and points at the section that says why. If you want the argument, follow the link; it is always one clause away and it is always the authority.
• Words that are not coined here. $ref, Path Item, Operation Object and the rest belong to OpenAPI, and the support matrix says what this package does with each rather than redefining them.
• The vocabulary of writing the documentation. covers, a doc smell, the summary rule and the tag list are for somebody editing this set rather than using the package, and they live in documentation.md.
• A seam, in general. The set uses the word for several different joints: the version strategy, getQuery(), the 501 an unimplemented operation answers. Only the two-class seam is a term, and the rest is a metaphor that each use qualifies for itself.