Document Pastoral API linked classes and groups [SA-22796]

[Scott-Newman]

Summary

Document linked classes/groups in the Pastoral create and PATCH APIs for SA-22796.

• Document linkedFolderIds, CSV/array inputs and per-student eligibility in bulk requests.
• Explain PATCH omission, replacement, clearing and retention of previously linked archived/ineligible folders.
• Define linkedFolders response objects with folder ID, name and codes.
• Include create, replace, clear and response examples; clarify that links use folder identity, not reused codes, and are not sent to external pastoral sync.

Companion application PR: https://github.com/alaress/schoolbox/pull/35977

Verification

• npm test passes (six existing warnings in unrelated path/course schemas).
• No test code or generated documentation builds added; source schemas/examples only.

[cloudflare-workers-and-pages]

Deploying schoolbox-api-docs with    Cloudflare Pages

Latest commit:	02f42a4
Status:	✅  Deploy successful!
Preview URL:	https://fd954acf.schoolbox-api-docs.pages.dev
Branch Preview URL:	https://task-develop-sa-22796.schoolbox-api-docs.pages.dev

View logs

[Copilot]

🔵 Needs a closer look

The documentation asserts numerous backend behaviors (eligibility, archived-link retention, exclusion from external sync) that depend on the companion application PR and cannot be verified from this docs repository alone.

Pull request overview

This PR documents (docs-only, OpenAPI source schemas/examples) the newly supported "linked classes/groups" feature for the Pastoral API, covering both the create (POST /pastoral/record/insert) and PATCH (/pastoral/record/update) endpoints. It adds a linkedFolders response object and a linkedFolderIds request input, along with examples describing eligibility, retention, clearing/replacement semantics, and exclusion from external pastoral synchronisation. The behavioral claims are backed by the companion application PR (alaress/schoolbox#35977).

Changes:

• Adds a new pastoral-linkedFolders.yaml schema (folder id, name, codes) and references it as linkedFolders in the create and partial pastoral response schemas, including examples.
• Documents linkedFolderIds request input (CSV string or integer array) in the create and PATCH request bodies with eligibility, retention, replacement, and clearing behavior.
• Adds request/response examples for creating a linked record, replacing links, and clearing links.

File summaries

File	Description
openapi/components/schemas/pastoral-linkedFolders.yaml	New response schema defining a linked folder's id, name, and codes.
openapi/components/schemas/pastoral-item.yaml	Adds linkedFolders to the create response schema and example.
openapi/components/schemas/pastoral-partial-item.yaml	Adds linkedFolders to the partial (PATCH) response schema and example.
openapi/components/requestBodies/pastoral-item.yaml	Documents linkedFolderIds create input and a linked-record example.
openapi/components/requestBodies/pastoral-partial-item.yaml	Documents linkedFolderIds PATCH input plus replace/clear examples.

Review details

• Files reviewed: 5/5 changed files
• Comments generated: 1
• Review effort level: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Scott-Newman]

Agreed. Added the codes property description in 02f42a4, using the same wording as courseFolderItem.yaml and curriculumNodeUsage-folderItem.yaml: "A list of class codes (if any) associated with this folder." This keeps the property documentation consistent; the parent description still explains that codes are current and may be empty for groups or archived folders. npm test (Redocly lint) passes with the same six existing unrelated warnings. No new tests were added for this documentation-only change.