Add Examples table to spec

[mikeschinkel]

Added an Examples table, and the rest of the changes followed from that to improve structure, clarity, and consistency (with no normative changes).

Summary of changes

• Added a quick-reference table summarizing all examples
• Promoted Examples to a top-level non-normative section
• Added Array Move and Array Replace examples
• Standardized headings and ordering (Update, Copy, Move, Array)
• Adjusted anchors, grammar, and appendix order (File Naming → A, Revision History → B)

All content above ## Examples remains unchanged except to fix broken links.

[mikeschinkel]

Note that my motivation for this PR — already mentioned — was to provide ways for people who were expecting keywords like move to easily find how to achieve the same by visually scanning the table, and all other changes I made were merely in service of adding this table.

I am new to contributing to a spec so please forgive me is any of my changes are not appropriate for a spec, and if so just let me know and I will correct them post haste.

[ralfhandl]

Please sync with the current state after merging #150

[ralfhandl]

I like the old phrasing better, it links to both the actions keyword and the Action Object.

[mikeschinkel]

@ralfhandl — AFAIK I did sync with the current state. I did a fresh clone after #150 and then applied my changes over top of the latest version of 1.1.0-dev.md:

e8089d5 (HEAD -> examples-table, origin/examples-table, main) docs: Add Examples table to spec
506688d (origin/main, origin/HEAD) Merge pull request #221 from OAI/baywet-patch-1
a99858c Update CODEOWNERS to remove the tsc team
66a9d85 Merge pull request #220 from ralfhandl/1.1-json-rfc-reference
4f8073b Merge pull request #216 from ralfhandl/1.1-merge-explained

[mikeschinkel]

I like the old phrasing better, it links to both the actions keyword and the Action Object.

Then it would be more clear if the links were using different keywords so it was obvious where clicking the link will take the reader, no?

Maybe this?

An Overlay is a JSON or YAML structure containing an ordered list of 
[Action Objects](#action-object) that are to be applied to the target 
document via the [`actions` field](#overlay-actions). Each Action Object 
has a `target` property and a modifier type (`update`, `remove`, or 
`copy`). The `target` property is a [[RFC9535|RFC9535 JSONPath]] 
query expression that identifies the elements of the target document 
to be updated and the modifier determines the change.

[ralfhandl]

I don't see this as an appendix.

Besides, the revision history is Appendix A, so it would have to go after that.

[mikeschinkel]

@ralfhandl — FWIW, I wasn't sure and asked ChatGPT to help me decide and it recommended appendix.

But I will move back out if you feel strongly.

[mikeschinkel]

Alternately I will move to Appendix B.

[ralfhandl]

My rationale for not moving it to the appendix: if @lornajane would have wanted it to be an appendix, she would have done so. Apparently ChatGPT didn't consider this 😎

[ralfhandl]

@mikeschinkel Sorry for my brief first review, I should have given some context before going into details.

The Markdown file edited in the repo is the source for the HTML document published at https://spec.openapis.org/, side by side with the Arazzo and OpenAPI specifications. This HTML document is produced with ReSpec.

• Added a quick-reference table summarizing all examples

I think this table adds maintenance overhead for the specification authors and adds very little value for readers because ReSpec automatically produces a table of contents that is (on sufficiently wide screens) positioned to the left of the text and shows all examples at a glance:

• Adjusted anchors, grammar, and appendix order (File Naming → A, Revision History → B)

The anchors you added won't work as you expect in the final HTML document produced by ReSpec. ReSpec automatically adds section anchors by lower-casing all words and replacing spaces with dashes. Links to these automatic anchors position the text correctly when following them. Additional anchors before the headings don't position correctly, they are noticeably off.

Please remove all of these additional anchors before headlines.

The Overlay spec is published side-by-side with the Arazzo and OpenAPI specification, and these have the revision history in Appendix A, and additional appendices after that starting with B: https://spec.openapis.org/oas/latest.html#appendix-a-revision-history.

[ralfhandl]

Suggested change

	### RFC9535 compliance
	### RFC9535 Compliance

[mikeschinkel]

@ralfhandl — Thank you for those details. That was extemely helpful for me as it was context I did not previously have.

I now realize I was thinking less about individual examples and more about use-cases. IOW, the tasks authors are trying to accomplish, e.g., rename a path item, copy between operations, move an array element, etc.

The TOC provides structure for examples, but it does not group or surface them by intent.

What I would still find valuable is way to surface Use-Cases and information about how to achieve those use-case.possibly via a matrix table that helps readers understand how to accomplish their task — e.g. a move requires an update, a copy, then a remove — as well as a link to an example matching their task.

I’d be happy to explore that alternative if it feels more aligned with this document’s purpose.

[mikeschinkel]

@ralfhandl — If maintenance remains a main concern, I could automate table generation during the ReSpec build step as the repo already runs scripts/md2html/build.sh to transform Markdown to HTML. Inserting a small preprocessor to auto-assemble a Use-Case Index would eliminate manual upkeep.

[ralfhandl]

I‘d rather stick with the table of contents produced by ReSpec. It is clearly visible to the left or at the top of the spec, depending on screen width.

A second table of examples somewhere in the middle of the document is less prominent and in my opinion not worth the effort.

[ralfhandl]

Please remove all of these anchors next to headings, see long comment.

[mikeschinkel]

@ralfhandl — 

Please remove all of these anchors next to headings, see long comment.

Done.

[ralfhandl]

My rationale for not moving it to the appendix: if @lornajane would have wanted it to be an appendix, she would have done so. Apparently ChatGPT didn't consider this 😎

[ralfhandl]

• Promoted Examples to a top-level non-normative section
• Added Array Move and Array Replace examples

The combined effects of the changes in this PR produces a very confusing diff that makes it impossible for me to review this PR as is.

Maybe it is worth breaking this up into at least two smaller PRs:

• Reorder sections and heading levels without text changes
• Adjust section headings and text, and add new examples

[lornajane]

My high-level comments:

• given how the spec is presented when it is published (https://spec.openapis.org/overlay/v1.0.0.html), I don't think the table is needed.
• this pull request cannot be reviewed as it is, since it contains multiple unrelated changes. I'll mark it as draft for now rather than closing, while you consider the comments and decide whether to update it or replace it.

As a general point, a pull request that has clear intent (with a description) makes it easier for reviewers to understand and review a proposed change. Even if you're using tools to update a specification, either do not allow unrelated changes, or commit them separately and offer them as separate pull requests.

[mikeschinkel]

@lornajane —

Thank you for taking the time to review and comment.

I completely understand the point about separating unrelated changes; that was my oversight. I will make sure future PRs have a single, clear intent going forward.

Regarding the table: after reflecting on your and @ralfhandl’s feedback, I realize I was really thinking in terms of use-cases rather than individual examples. The published spec already presents examples clearly, but it does not group them by intent (for example, update an object, move a path item, modify an array) nor make those use-cases directly discoverable.

My primary goal with this PR was to improve scannability for readers looking for how-to accomplish a task. That motivation originally came from wanting a move verb, but instead I decided to "color between the lines" and update the docs to make that workflow easier to find rather than propose a new command.

The format I proposed was informed by usability research from the Nielsen Norman Group on how people forage for information, and how they scan instead of reading. Their work shows that users rely on information scent (the perceived relevance of visual or textual cues) to decide where to focus attention. When content is presented in a structured, scannable format such as a table, those cues become clearer, enabling users to find what they need faster and with less cognitive effort: Information Foraging Theory and The F-Shaped Pattern for Reading Web Content.

In short, I believe a concise use-case matrix would provide benefit without duplicating the existing TOC. If maintenance remains the main concern, we could potentially auto-generate the matrix during the ReSpec build so that it stays in sync automatically. I welcome discussion on whether that approach could best balance usability, maintainability, and fitness for purpose.

[mikeschinkel]

@ralfhandl —

Maybe it is worth breaking this up into at least two smaller PRs:

Understood.

Let us first decide if there is room for a use-case matrix as I proposed to @lornajane. at least before I refactor the PR because if not then the motivation for this PR will be moot, anyway.

[ralfhandl]

Regarding the table: after reflecting on your and @ralfhandl’s feedback, I realize I was really thinking in terms of use-cases rather than individual examples.

I think this would be great content for the learn site https://learn.openapis.org/.

Please consider adding the use case table/matrix there and keep the spec minimalistic.