docs: document required schemas and capability advertisement for composition functions#1064
Conversation
✅ Deploy Preview for crossplane ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
kruthiwusirika5
force-pushed
the
docs/required-schemas-and-capabilities
branch
from
49c2d7c to
c755c14
Compare
|
Hi @jbw976 PR is ready for review when someone has time. Summary: Documents two composition function features (Fixes #1040, #1041): (1) Required schemas — how functions request OpenAPI schemas via Netlify deploy preview is ready. Happy to adjust wording or scope. |
|
Thank you very much for taking a pass at documenting this feature! i'd like to include this in the v2.3 release so we don't go another release without having this documented 😉 I'm not sure why but Github isn't showing some of the required checks, so I'm going to close and re-open the PR to see if that will kick them again 🤔 |
|
there we go, that got the checks running again. Looks like some errors/warnings flagged by Vale, could you take a look at fixing those? https://github.com/crossplane/docs/actions/runs/26071066553/job/76652415266?pr=1064 how to use Vale from the contributing guide: https://docs.crossplane.io/contribute/vale/ |
jbw976
left a comment
jbw976
left a comment
There was a problem hiding this comment.
This looks pretty good, thank you for the helpful contribution! a couple suggestions to help clarify a few things. Don't forget the vale fixes and to incorporate any feedback into both master and v2.2 directories.
Thank you so much for your help and initiative here! 🙇♂️
|
|
||
| ### Capability advertisement | ||
|
|
||
| Crossplane populates `RequestMeta.capabilities` with all protocol features it |
There was a problem hiding this comment.
what do you think about including a note box to say that capabilities advertisement doesn't exist prior to v2.2? if capabilities is completely missing/empty, then some features may still exist and be supported, but functions will not be able to know without trying them 😇
| Example (Python): check for a capability before using the feature: | ||
|
|
||
| ```python | ||
| from crossplane.function import request, response |
There was a problem hiding this comment.
i think this import statement would be useful too:
import crossplane.function.proto.v1.run_function_pb2 as fnv1
…osition functions
- Add Required schemas section: functions can request OpenAPI schemas via
requirements.schemas; Crossplane populates required_schemas (Fixes crossplane#1040).
- Add Capability advertisement section: meta.capabilities lists supported
features; functions should check and fall back (Fixes crossplane#1041).
- Add intro mention of meta.capabilities in How composition functions work.
- Crossplane v2.2+; references design one-pagers and PR 7022.
Signed-off-by: Kruthi Wusirika <kruthiwusirika@gmail.com>
Fix the Vale errors and warnings flagged by the workflow. Add a hint box noting that Crossplane versions older than v2.2 don't advertise capabilities, with a pointer to the `advertises_capabilities` / `AdvertisesCapabilities` SDK helpers. Add the missing `fnv1` import to the Python example. Sync the same content into content/v2.3/composition/compositions.md. Signed-off-by: Jared Watts <jbw976@gmail.com>
jbw976
force-pushed
the
docs/required-schemas-and-capabilities
branch
from
c755c14 to
4924479
Compare
jbw976
left a comment
jbw976
left a comment
There was a problem hiding this comment.
i pushed a commit to this branch to go ahead and address the final review feedback and backport to v2.3 now that the v2.3 release is done - this should be good to go!
Thanks again for this great addition to the docs @kruthiwusirika5, we really appreciate it! 🙇♂️
2 participants
What
requirements.schemas; Crossplane populatesrequired_schemason the next request. Covers bootstrap (Composition) and dynamic requests, with a YAML example.RequestMeta.capabilities—Crossplane lists supported protocol features so functions can check before using a feature and fall back on older controllers. Includes capability table and Python example.meta.capabilitiesin "How composition functions work" with a link to the new section.Why
Content requested in #1040 and #1041; implementation is in crossplane/crossplane#7022 (v2.2). Matches existing style (e.g. Required resources section).