2.0.0-preview1 release notes

Overview

Version 2.0-preview1 brings major enhancements, including OpenAPI 3.1 support, improved performance, and bug fixes to enhance user experience. These changes introduce some breaking changes, so migrating to this new version may require updates in existing implementations.

Upgrade Steps

• Bump up Microsoft.OpenApi and Microsoft.OpenApi.Readers packages to 2.0.0-preview1 from NuGet.

Breaking Changes

1. Update namespaces

Since most of the loading code has moved to the core library, you will be required to update the namespaces in your classes to reflect the change.

Example:
If you're using an instance of our OpenApiReaderSettings, you'll need to update the namespace from Microsoft.OpenApi.Readers to Microsoft.OpenApi.Reader

2. Use Load/LoadAsync/Parse pattern for loading OpenApi documents

We've introduced a simplified static loading pattern for OpenAPI documents, removing the need for a secondary reader.
We have also introduced a registry class that allows users to register different OpenAPI format providers and their implementations for customized scenarios.

Reading from a JSON stream:

    var settings = new OpenApiReaderSettings();
    var readResult = OpenApiDocument.Load(stream, "json", settings);
    var doc = readResult.OpenApiDocument;

To enable YAML parsing, you'll have to register our OpenApiYamlReader with our reader registry for us to take a dependency on the SharpYaml library.

Reading from a YAML stream:

    OpenApiReaderRegistry.RegisterReader(OpenApiConstants.Yaml, new OpenApiYamlReader());
    var doc = OpenApiDocument.Load(stream, "yaml", settings).OpenApiDocument;

Reading string input:

    var doc = OpenApiDocument.Parse(input, "yaml").OpenApiDocument;

Reading from a file path or URL:

    var doc = await OpenApiDocument.LoadAsync(filePath).OpenApiDocument;

3. Migration to JsonNode for examples and extensions

Schema examples and extensions now use JsonNode instead of IOpenApiAny, ensuring JSON Schema compatibility and fixing parsing errors.
You'll be required to import the System.Text.Json.Nodes namespace to facilitate this.

v1.x example:

    Example = new OpenApiObject
    {
        ["name"] = new OpenApiString("Puma"),
        ["id"] = new OpenApiLong(1)
    }

v2.0 example:

    Example = new JsonObject
    {
        ["name"] = "Puma",
        ["id"] = 1
    }

v1.x extensions:

    Extensions = new Dictionary<string, IOpenApiExtension>
    {
        {
            "x-ms-docs-operation-type", new OpenApiString("function")
        }
    }

v2.0 extensions:

    Extensions = new Dictionary<string, IOpenApiExtension>
    {
        {
            "x-ms-docs-operation-type", new OpenApiAny("function")
        }
    }

4. JSON schema Type has changed from string to JsonSchemaType enum

In line with JSON Schema, the type keyword can now define multiple types for a schema with an array. Swap nullable for type arrays.
Schema example in v1.x:

    Type = "array",
    Items = new() { Type = "string" }

Schema example in v2.0:

    Type = JsonSchemaType.Array,
    Items = new() { Type = JsonSchemaType.String }

5. Use Proxy Reference object in place of OpenApiReference in your model

We have optimized the reference resolution step by implementing a proxy pattern where dereferencing happens by lazy loading when one tries to access an object's properties that contains a $ref.

Example

Items = new OpenApiSchema 
        { 
            UnresolvedReference = true, 
            Reference = new OpenApiReference 
            { 
                Type = ReferenceType.Schema, 
                Id = "GeoJSON.position" 
            }
        }    

changes to:

Items = new OpenApiSchemaReference("GeoJSON.position", null),

The proxy objects exist within the Microsoft.OpenApi.Models.References namespace so make sure to add a reference to this in your class.
Note: For the reference to be resolved, make sure to pass a host document instance.

6. Modify validation rules to add CRUD operations

Modifies validation rules to add Create, Read, Update and Delete operations to allow for a configurable experience by clients.

New Features

1. OpenAPI 3.1 support in line with the OpenApi 3.1 specification.These include:

   • Webhooks support
   • summary property in the info object
   • license SPDX identifier
   • Add a root property JSON schema dialect
   • Allow overloading of summary and description fields alongside $ref for non-JSON schema objects.

2. JSON schema support

   • Support the core and validation keywords from the latest JSON schema specification JSON Schema Specification Draft 2020-12.
   • Add support for keywords such as $schema, $id, $comment, $vocabulary, $dynamicRef, $dynamicAnchor.
   • Swap nullable for type arrays
   • Map nullable keyword to null type
   • ExclusiveMinimum and ExclusiveMaximum now represent distinct values
   • Add support for PatternProperties
   • Support for examples defined as an array

3. Local and external document dereferencing using a $ref locator to schema identifiers using $id

Enhancements and Perf improvements

1. Proxy Pattern for reference resolution

Simplifies reference resolution using proxy reference objects that implement lazy loading during property access thus eliminating the need for a secondary parse.

2. System.Text.Json for parsing

Replaces older parsers with System.Text.Json to improve efficiency and native integration.

3. Optimized JSON parsing

Completely bypasses the YAML parser to parse JSON documents, significantly improving performance.

4. Avoid buffering JSON data into a new MemoryStream during parsing

This increases efficiency by reducing memory usage and allowing the program to respond faster as JSON data can be read asynchronously, especially in cases with large or streaming data.

Bug Fixes

• Fix validation errors during examples validation resulting into data type mismatches
• Fix example values and extension strings switching type
• Fix property getter that changes model data
• Fix Parsing error when path key exceeds 1023 characters by using STJ
• Fixes consumes in global context not being propagated to request body
• Fixes examples serialization in request/response objects during v2->v3 upcasting and vice versa
• Fix ValidationRuleSet.Rules should be IEnumerable not IList
• Simplify null checks
• Remove validation rule to make both paths and webhooks optional in v2.0
• Writing $ref values that have a $Id as a value are incorrectly prepending #/components/schema/
• Fix concurrency error with reader registry

Other Changes

• Update our commandline tool-hidi to validate and transform 3.1 documents