Add discriminator and some other pull request feedback

Author: lornajane

specification/parameters.md

@@ -73,7 +73,7 @@ Parameters can reside in different locations, indicated by the `in` field. The m
   > **NOTE**:
   > If any parameters are `in: query`, then `in: querystring` cannot be used.
 
-- `querystring` (OpenAPI 3.2+): The entire query string is treated as a single parameter with complex structure:
+- `querystring` (OpenAPI 3.2+): The entire query string is treated as a single parameter with complex structure, meaning that combinations of query parameters can be expressed using a well-defined Schema object:
 
   ```yaml
   paths:

upgrading/v3.1-to-v3.2.md

@@ -114,8 +114,8 @@ paths:
 ### Advanced HTTP Method Support
 
 - **QUERY method** for complex filtering with request bodies
-- **Custom HTTP methods** via additionalOperations
-- **Enhanced parameter handling** including querystring location
+- **Custom HTTP methods** via `additionalOperations`
+- **Enhanced parameter handling** including `in: querystring` location
 
 *See: [HTTP Methods](../specification/http-methods) for implementation details*
 
@@ -131,35 +131,25 @@ paths:
 ### Security Enhancements
 
 - **OAuth2 Device Authorization** flow for limited-input devices
-- **Enhanced metadata** support with oauth2MetadataUrl
+- **Enhanced metadata** support with `oauth2MetadataUrl`
 - **Deprecation marking** for security schemes
 - **URI-based references** for security schemes
 
 *See: [Security](../specification/security) for updated authentication methods*
 
-### Better Examples and Documentation
-
-- **Structured examples** with dataValue field
-- **Serialization examples** with serializedValue field
-- **Enhanced servers** with name fields
-- **Document identity** with $self field
+### Discriminator Improvements
 
-*See: [Providing Documentation and Examples](../specification/docs) for enhanced example handling*
+- **Use an optional value** for `discriminator`
+- **Provide fallback** configuration with `defaultMapping` for payloads that don't match the discriminator mapping
 
-## Upgrade Benefits
-
-## Gradual Enhancement Strategy
+### Better Examples and Documentation
 
-Consider adopting new features incrementally:
+- **Structured examples** with `dataValue` field
+- **Serialization examples** with `serializedValue` field
+- **Enhanced servers** with `name` fields
+- **Document identity** with `$self` field
 
-1. **Enhance server descriptions** - Add `name` fields to server objects
-2. **Improve examples** - Use `dataValue` and `serializedValue` for clearer examples
-3. **Add document identity** - Include `$self` field if URI resolution clarity is needed
-1. **Tag enhancements** - Convert `x-displayName` to `summary`, `x-tagGroups` to tag hierarchy
-2. **Remove custom extensions** - Replace with native 3.2 functionality where available
-1. **New HTTP methods** - Implement QUERY method for complex filtering scenarios
-2. **Streaming support** - Add sequential media types for real-time APIs
-3. **Enhanced security** - Implement OAuth2 device flow if relevant to your use cases
+*See: [Providing Documentation and Examples](../specification/docs) for enhanced example handling*
 
 ## Migration Checklist
 
@@ -171,9 +161,10 @@ Consider adopting new features incrementally:
 ### Gradual Enhancements (As Needed)
 
 - [ ] Replace custom extensions with native 3.2 features
-- [ ] Add `name` fields to server objects for better identification
-- [ ] Enhance examples with `dataValue`/`serializedValue` fields
 - [ ] Consider tag hierarchy for better API organisation
+- [ ] Enhance examples with `dataValue`/`serializedValue` fields
+- [ ] Add `name` fields to server objects for better identification
+- [ ] Set a `defaultMapping` for discriminators to use a default schema rather than trigger an error
 - [ ] Evaluate new HTTP methods for relevant use cases
 - [ ] Review security schemes for OAuth2 device flow applicability
 - [ ] Consider sequential media types for streaming or real-time APIs