Shorter, more focused referencing guide #80
Conversation
This reworks the less-controversial parts of a prevoius attempt at a referencing guide that was over-ambitious, among other things.
referencing/what.md
Outdated
| | 3.x | Path Item Object | `"$ref"` | allowed under some circumstances | logically replace the Path Item Object containing the `"$ref"` with a Path Item Object that combines the fields of the target Path Item Object with the non-`"$ref"` fields of the Path Item Object containing the `"$ref"`, as long as none of those fields conflict | | ||
| | 3.1 | Schema Object | `"$ref"` | allowed | Apply the target Schema Object to the same instance location as the Schema Object containing the `"$ref"`, and combine the results with the results of other keywords in the Schema Object containing the `"$ref"` just as you would any other keyword results; this is more-or-less equivalent to using a one-element `"allOf"` | | ||
| | 3.x | Link Object | `"operationRef"` | allowed, except `"operationId"` | treat the reference target as the target of the link described by the Link Object | | ||
| | 3.x | Discriminator Object | `"mapping"` | n/a | for each name under `"mapping"`, if the value is not the name of a Schema Object under the Components Object, treat it as a reference to the schema to use when the discriminator field matches the mapping name | |
There was a problem hiding this comment.
Very informative. Just to check, for the 3.x labels these are all going to be unchanged in 3.2+ until moonwalk?
There was a problem hiding this comment.
@notEthan thanks! They will remain compatible, more so than 3.0 to 3.1. I think we might deprecate some things like the special Path Item Object $ref behavior, but we won't remove anything.
|
Thanks @handrews! I need more time to look at this properly, there are some really great nuggets in here of what doesn't work and why, but I think we might also add some "do it this way" advice and some examples to try to lead people out of the dark place in which they find themselves. Would it be okay for me to add changes directly to this pull request to restructure some of the content? |
|
@lornajane I'd had more content and guidance in a previous iteration of this, and had intended to add more in a later PR. But I'd very much welcome and appreciate collaboration on this. If it's easier for you to edit this PR in place, please go right ahead! I look forward to seeing the changes. |
|
I forgot to add that I put the rendered changes up here: |
|
Thanks for being open to some content restructure @handrews - I shifted things out of FAQ format (not considered current practice in documentation, and not an established pattern in these docs) mostly because those articles can get long and difficult to navigate. The content is split into topics, with each page added to the sidebar. In general, I think paragraphs might be easier to read than bullet points, but I suggest we don't block the pull request for that (I've done enough holding this one up already!). I would have loved to have seen at least one or two examples in the text, I think that's something that the learn site can excel at - but we can add them later, maybe after hearing user feedback. |
|
@lornajane thanks! I will look at this in detail soon. Just to respond to a few comments first:
Great! I'm not up on current best practices and was not attached to a FAQ format at all.
I've been told "bullet points, not paragraphs!" over and over by people who outright refuse to read anything I write in prose because I'm too wordy. I'm happy for anyone else to restructure it, I'm just hyper-sensitive at this point.
I am horrible at examples. I learn theory-first, unless the theory just isn't articulated and I have to construct it from examples. Most people learn examples-first. I've never understood how to connect with that, so hopefully others will fill them in. I'm happy to provide a topic list or feedback, though. |
|
Let's leave the bullet points and not worry too much about the examples. They can be fleshed out over time - I do think they're useful, but let's add them as we see them in the wild or something! |
|
@handrews I think this is an improvement and we should merge if you're happy enough to let this version go as-is. |
This reworks the less-controversial parts of a prevoius attempt (#69) at a referencing guide that was over-ambitious, among other things. It's amazing how being in better health makes my writing less cranky and confrontational! 😅