This PR implements support for all JSON Schema 2020-12 metadata annotations on OpenApiSchemaReference, enabling developers to override schema properties at the reference level as specified in OpenAPI 3.1.

Changes Made

Core Implementation

• Added metadata annotation fields to OpenApiReference: default, title, deprecated, readOnly, writeOnly, examples
• Updated OpenApiSchemaReference properties to use the same override pattern as Description:
  • Reference annotation values take precedence over target schema values
  • Falls back to target schema values when reference annotations are not set
• Added Summary property to OpenApiSchemaReference for completeness

Serialization & Deserialization

• OpenAPI v3.1 serialization: Includes all annotation fields when present
• OpenAPI v3.0 serialization: Only includes $ref (correct behavior, annotations not supported)
• Updated parser: Correctly reads annotation fields from JSON/YAML input
• Full round-trip support: All annotation fields are preserved during parse → serialize cycles

Example Usage

var schemaRef = new OpenApiSchemaReference("Pet", document)
{
    Title = "Pet Response Schema",           // Overrides target schema title
    Description = "A pet from the API",     // Overrides target schema description  
    Deprecated = true,                      // Overrides target schema deprecated flag
    ReadOnly = true,                        // Overrides target schema readOnly flag
    Default = JsonValue.Create("{}"),       // Overrides target schema default value
    Examples = [JsonValue.Create("{\"name\": \"Fluffy\"}")]  // Overrides target examples
};

JSON Schema 2020-12 Compliance

Supports the metadata vocabulary as defined in the JSON Schema specification:

• title - Short description of the data
• description - Longer description with CommonMark support
• default - Default value for the schema
• deprecated - Indicates if the schema is deprecated
• readOnly - Indicates if the property is read-only
• writeOnly - Indicates if the property is write-only
• examples - Example values for the schema

Testing

• 854 existing tests pass ✅ (no regressions)
• Comprehensive unit tests covering all annotation fields
• Integration test verifying full parsing and serialization round-trip
• Public API compatibility maintained

OpenAPI Output Examples

OpenAPI 3.1 (with annotations):

{
  "summary": "Pet Summary",
  "description": "A pet object",
  "title": "Pet Schema", 
  "deprecated": true,
  "readOnly": true,
  "default": {"name": "default"},
  "examples": [{"name": "example"}],
  "$ref": "#/components/schemas/Pet"
}

OpenAPI 3.0 (reference only):

{
  "$ref": "#/components/schemas/Pet"
}

This enables the ASP.NET Core scenario mentioned in the issue where XML comments can be used to apply rich metadata annotations to schema references, providing better API documentation and tooling support.

Fixes #2369.

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.