Add vendorExtensions mechanism for platform-specific data

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.

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-<platform-slug>` 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

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-<platform-slug>` (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-<platform-slug>` 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-<slug>`) | Owner | Docs / Repo |
+|---|---|---|
+| `x-lf` | Lambda Feedback | https://github.com/lambda-feedback/mued-vendor-spec |
+
+## 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.

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-<platform-slug> 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-<platform-slug> keys. See VendorExtensions.yml for details.
+        $ref: "../../shared/schemas/VendorExtensions.yml"

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-<platform-slug> keys. See VendorExtensions.yml for details.
+        $ref: "../../shared/schemas/VendorExtensions.yml"

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-<platform-slug> keys. See VendorExtensions.yml for details.
+    $ref: "./VendorExtensions.yml"

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-<platform-slug>` (following the OpenAPI
+  Specification Extensions convention), e.g. `vendorExtensions.x-lf`.
+  <br><br>
+  µ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