From cdd3cdda5272b53f797fde448ac8de01900367be Mon Sep 17 00:00:00 2001 From: Marcus Messer Date: Fri, 21 Aug 2026 13:37:25 +0100 Subject: [PATCH 1/2] Added `vendorExtensions` support for platform-specific data and namespace registry documentation --- CONTRIBUTING.md | 9 +++++ README.md | 10 +++++ VENDOR_EXTENSIONS.md | 44 ++++++++++++++++++++++ paths/chat/schemas/ChatRequest.yml | 11 ++++++ paths/evaluate/schemas/EvaluateRequest.yml | 5 +++ paths/shared/schemas/User.yml | 5 +++ paths/shared/schemas/VendorExtensions.yml | 15 ++++++++ 7 files changed, 99 insertions(+) create mode 100644 VENDOR_EXTENSIONS.md create mode 100644 paths/shared/schemas/VendorExtensions.yml diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0b67df7..56b98f7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,15 @@ When creating an issue, include: Use issues to capture bugs, unclear parts of the specification, and proposed API changes before implementation when the scope is non-trivial. +## Vendor-specific fields + +If you need a field that's specific to your platform and not something +every implementer needs, it likely belongs under `vendorExtensions` +rather than as a new core schema field. See +[VENDOR_EXTENSIONS.md](VENDOR_EXTENSIONS.md) for how to namespace your +data and the bar for when something becomes a core schema addition +(≥2 independent platforms needing the identical shape). + ## Contributing 1. Start from the latest `main` branch. diff --git a/README.md b/README.md index 958bb34..8a29b50 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,16 @@ At a high level, the API specifies endpoints for: All request/response shapes, validation rules, and examples live in the spec files. +## Extending the spec for your platform + +Platform-specific data that isn't common across implementers doesn't +belong in core schemas. Use the `vendorExtensions` extension point +(namespaced under `x-` keys) instead of forking or +proposing vendor-specific fields into the core spec. See +[VENDOR_EXTENSIONS.md](VENDOR_EXTENSIONS.md) for the namespace registry, +usage details, and the rule for when a concept graduates into a core +schema. + ## Development ### Prerequisites diff --git a/VENDOR_EXTENSIONS.md b/VENDOR_EXTENSIONS.md new file mode 100644 index 0000000..bc1ab68 --- /dev/null +++ b/VENDOR_EXTENSIONS.md @@ -0,0 +1,44 @@ +# Vendor Extensions Registry + +µEd-api core schemas cover only the shapes that are common across +platforms. Anything platform-specific belongs in `vendorExtensions`, +a reusable, open-ended (`additionalProperties: true`) extension point +defined once in `paths/shared/schemas/VendorExtensions.yml` and referenced +from `context`, `configuration`, and `User` schemas. + +## How it works + +- Vendors add exactly one top-level key inside `vendorExtensions`, named + `x-` (following the OpenAPI Specification Extensions + convention, e.g. `x-lf`). +- µEd-api does **not** define, host, or validate the contents under a + vendor's namespace. Each vendor is responsible for documenting and + versioning the shape of its own `x-` object in its own + repository or docs. +- This file exists **only** to reserve namespace slugs and prevent + collisions between vendors — it is not a schema registry and does not + imply any endorsement or validation by µEd-api. + +## Registering a namespace + +To reserve a namespace, open a PR adding a row to the table below with +your slug, an identifying owner/organization, and a link to where your +fields are actually documented (your own repo, docs site, or spec). + +| Namespace (`x-`) | Owner | Docs / Repo | +|---|---|---| +| _(none registered yet)_ | | | + +## When does a vendor extension become a core schema? + +A concept only graduates from a vendor extension into a typed core/shared +schema in this repository once **at least two independent platforms** +need the identical shape. Until then, it stays vendor-extension territory, +even if it looks broadly useful — this keeps core schemas free of +single-vendor assumptions (this is exactly the mistake that motivated +`vendorExtensions` in the first place: module/set/question concepts were +found to be Lambda-Feedback-specific, not universal). + +To propose a graduation, open an issue showing the ≥2 independent +platforms and their (already converging) shapes, so the core addition +can be modeled from real, shared usage rather than guessed in advance. diff --git a/paths/chat/schemas/ChatRequest.yml b/paths/chat/schemas/ChatRequest.yml index 8b8d850..e180114 100644 --- a/paths/chat/schemas/ChatRequest.yml +++ b/paths/chat/schemas/ChatRequest.yml @@ -26,6 +26,12 @@ properties: - "null" description: Optional educational context (e.g., course material, task context). additionalProperties: true + properties: + vendorExtensions: + description: > + Optional vendor/platform-specific data namespaced under + x- keys. See VendorExtensions.yml for details. + $ref: "../../shared/schemas/VendorExtensions.yml" configuration: type: - object @@ -59,3 +65,8 @@ properties: - "null" allOf: - $ref: "../../shared/schemas/ExecutionPolicy.yml" + vendorExtensions: + description: > + Optional vendor/platform-specific configuration namespaced under + x- keys. See VendorExtensions.yml for details. + $ref: "../../shared/schemas/VendorExtensions.yml" diff --git a/paths/evaluate/schemas/EvaluateRequest.yml b/paths/evaluate/schemas/EvaluateRequest.yml index 044d459..889a13a 100644 --- a/paths/evaluate/schemas/EvaluateRequest.yml +++ b/paths/evaluate/schemas/EvaluateRequest.yml @@ -79,3 +79,8 @@ properties: - "null" allOf: - $ref: "../../shared/schemas/ExecutionPolicy.yml" + vendorExtensions: + description: > + Optional vendor/platform-specific configuration namespaced under + x- keys. See VendorExtensions.yml for details. + $ref: "../../shared/schemas/VendorExtensions.yml" diff --git a/paths/shared/schemas/User.yml b/paths/shared/schemas/User.yml index 1d220ab..73f0478 100644 --- a/paths/shared/schemas/User.yml +++ b/paths/shared/schemas/User.yml @@ -32,3 +32,8 @@ properties: - "null" description: Optional information about the user's progress on this task/topic. additionalProperties: true + vendorExtensions: + description: > + Optional vendor/platform-specific user data namespaced under + x- keys. See VendorExtensions.yml for details. + $ref: "./VendorExtensions.yml" diff --git a/paths/shared/schemas/VendorExtensions.yml b/paths/shared/schemas/VendorExtensions.yml new file mode 100644 index 0000000..50842a1 --- /dev/null +++ b/paths/shared/schemas/VendorExtensions.yml @@ -0,0 +1,15 @@ +type: [object, "null"] +description: > + Optional vendor/platform-specific data that does not (yet) have a place + in the core µEd schemas. Vendors namespace their fields under a single + top-level key of the form `x-` (following the OpenAPI + Specification Extensions convention), e.g. `vendorExtensions.x-lf`. +

+ µEd-api does not define, host, or validate the contents of any vendor's + namespace — each vendor owns and documents its own fields in its own + repository. µEd-api only maintains a namespace registry to prevent + collisions between vendors. See the registry, usage guidance, and the + rule for when a concept graduates from a vendor extension into a core + schema at: + https://github.com/mued-api/spec/blob/main/VENDOR_EXTENSIONS.md +additionalProperties: true From 5904b164d1ebde431c858aa20972ce556066a145 Mon Sep 17 00:00:00 2001 From: Marcus Messer Date: Wed, 26 Aug 2026 17:06:12 +0100 Subject: [PATCH 2/2] Register x-lf namespace in the vendor extensions registry Lambda Feedback's x-lf schema fragments are published at lambda-feedback/mued-vendor-spec. Co-Authored-By: Claude Sonnet 5 Claude-Session: https://claude.ai/code/session_017BgnWSuAQFVeeTDrUmo4Uc --- VENDOR_EXTENSIONS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/VENDOR_EXTENSIONS.md b/VENDOR_EXTENSIONS.md index bc1ab68..85e741e 100644 --- a/VENDOR_EXTENSIONS.md +++ b/VENDOR_EXTENSIONS.md @@ -27,7 +27,7 @@ fields are actually documented (your own repo, docs site, or spec). | Namespace (`x-`) | Owner | Docs / Repo | |---|---|---| -| _(none registered yet)_ | | | +| `x-lf` | Lambda Feedback | https://github.com/lambda-feedback/mued-vendor-spec | ## When does a vendor extension become a core schema?