Summary
A Path Item Object may write summary and description. Neither reaches the IR,
whether or not the item mounts an operation, and nothing reports it.
paths:
/p:
summary: PATH SUMMARY
description: PATH DESC
get: {operationId: getX, responses: {"200": {description: ok}}}
$ morphic compile p.yaml -skip-validate | grep -c 'PATH SUMMARY'
0
$ morphic compile p.yaml -skip-validate | grep -c 'PATH DESC'
0
The operation's own Docs carries the operation's summary and description; the
path item's are read by nothing. They are declared fields of the library's model,
so they never land in the operations map either, which is why the undeclared-key
census does not see them.
Why it is not part of the census work
Every other thing a path item writes now has a home: servers, x-* and
undeclared keys are kept under Unmodeled on each operation the item mounts, or —
for an item that mounts none — on the service. summary and description are
different in kind: they are documentation, and ir.Docs is a real IR field
rather than an Unmodeled payload, so keeping them verbatim would be the wrong
shape.
What is missing is a decision about how path-item docs relate to operation docs,
and OpenAPI does not settle it: the path item's summary applies to every operation
on the path, and each operation may have its own. So a lowering has to choose
between overriding, concatenating, or holding both — and ir.Docs has one
Summary and one Description.
Options
- Fill only when the operation writes none. Cheapest, and loses the path
item's text whenever an operation has its own.
- Keep both, with the path item's on a field
ir.Docs does not have yet.
Truthful; needs an IR field, which invariant 9 says should have existed from
day one, so it wants an ir-design.md change rather than a compiler one.
- Keep them verbatim under
Unmodeled on each mounted operation, as servers
already is. Lossless and available today, but it puts documentation in the
channel for things with no IR home when Docs plainly is one.
Method
Found while closing the unmounted-path-item gap, by checking whether the warning
that change emits was overclaiming what it keeps. It was, and the message was
narrowed to name servers, extensions and undeclared keys only. The code at
preserveUnmountedPathItem records this issue as the reason.
Summary
A Path Item Object may write
summaryanddescription. Neither reaches the IR,whether or not the item mounts an operation, and nothing reports it.
The operation's own
Docscarries the operation's summary and description; thepath item's are read by nothing. They are declared fields of the library's model,
so they never land in the operations map either, which is why the undeclared-key
census does not see them.
Why it is not part of the census work
Every other thing a path item writes now has a home:
servers,x-*andundeclared keys are kept under
Unmodeledon each operation the item mounts, or —for an item that mounts none — on the service.
summaryanddescriptionaredifferent in kind: they are documentation, and
ir.Docsis a real IR fieldrather than an
Unmodeledpayload, so keeping them verbatim would be the wrongshape.
What is missing is a decision about how path-item docs relate to operation docs,
and OpenAPI does not settle it: the path item's summary applies to every operation
on the path, and each operation may have its own. So a lowering has to choose
between overriding, concatenating, or holding both — and
ir.Docshas oneSummaryand oneDescription.Options
item's text whenever an operation has its own.
ir.Docsdoes not have yet.Truthful; needs an IR field, which invariant 9 says should have existed from
day one, so it wants an
ir-design.mdchange rather than a compiler one.Unmodeledon each mounted operation, asserversalready is. Lossless and available today, but it puts documentation in the
channel for things with no IR home when
Docsplainly is one.Method
Found while closing the unmounted-path-item gap, by checking whether the warning
that change emits was overclaiming what it keeps. It was, and the message was
narrowed to name servers, extensions and undeclared keys only. The code at
preserveUnmountedPathItemrecords this issue as the reason.