Skip to content
187 changes: 171 additions & 16 deletions src/Microsoft.OpenApi/Models/BaseOpenApiReference.cs
Original file line number Diff line number Diff line change
Expand Up @@ -13,28 +13,66 @@ namespace Microsoft.OpenApi
/// </summary>
public class BaseOpenApiReference : IOpenApiSerializable
{
private string? _externalResource;
/// <summary>
/// External resource in the reference.
/// It maybe:
/// 1. a absolute/relative file path, for example: ../commons/pet.json
/// 2. a Url, for example: http://localhost/pet.json
/// </summary>
public string? ExternalResource { get; init; }
public string? ExternalResource
{
get => _externalResource;
init
{
if (!string.Equals(_externalResource, value, StringComparison.Ordinal))
{
_externalResource = value;
_referenceV3 = null;
_isStandalone = false;
}
}
}

private ReferenceType _type;
/// <summary>
/// The element type referenced.
/// </summary>
/// <remarks>This must be present if <see cref="ExternalResource"/> is not present.</remarks>
public ReferenceType Type { get; init; }
public ReferenceType Type
{
get => _type;
init
{
if (_type != value)
{
_type = value;
_referenceV3 = null;
}
}
}

private string? _id;
/// <summary>
/// The identifier of the reusable component of one particular ReferenceType.
/// If ExternalResource is present, this is the path to the component after the '#/'.
/// For example, if the reference is 'example.json#/path/to/component', the Id is 'path/to/component'.
/// If ExternalResource is not present, this is the name of the component without the reference type name.
/// For example, if the reference is '#/components/schemas/componentName', the Id is 'componentName'.
/// </summary>
public string? Id { get; init; }
public string? Id
{
get => _id;
init
{
if (!string.Equals(_id, value, StringComparison.Ordinal))
{
_id = value;
_referenceV3 = null;
_isStandalone = false;
}
}
}

/// <summary>
/// Gets a flag indicating whether this reference is an external reference.
Expand All @@ -46,10 +84,36 @@ public class BaseOpenApiReference : IOpenApiSerializable
/// </summary>
public bool IsLocal => ExternalResource == null;

private bool _isFragment;
/// <summary>
/// Gets a flag indicating whether a file is a valid OpenAPI document or a fragment
/// </summary>
public bool IsFragment { get; init; }
public bool IsFragment
{
get => _isFragment;
init
{
if (_isFragment != value)
{
_isFragment = value;
_referenceV3 = null;
if (value)
{
_isStandalone = false;
}
}
}
}

private bool _isStandalone;
/// <summary>
/// Gets or sets a flag indicating whether this reference points directly to a standalone external resource rather than a component within it.
/// </summary>
internal bool IsStandalone
{
get => _isStandalone;
set => _isStandalone = value;
}

private OpenApiDocument? hostDocument;
/// <summary>
Expand Down Expand Up @@ -144,10 +208,13 @@ public BaseOpenApiReference() { }
public BaseOpenApiReference(BaseOpenApiReference reference)
{
Utils.CheckArgumentNull(reference);
ExternalResource = reference.ExternalResource;
Type = reference.Type;
Id = reference.Id;
HostDocument = reference.HostDocument;
_externalResource = reference._externalResource;
_type = reference._type;
_id = reference._id;
hostDocument = reference.hostDocument;
_isFragment = reference._isFragment;
_isStandalone = reference._isStandalone;
_referenceV3 = reference._referenceV3;
Comment thread
Copilot marked this conversation as resolved.
Resolved
}

/// <inheritdoc/>
Expand Down Expand Up @@ -241,6 +308,11 @@ public virtual void SerializeAsV2(IOpenApiWriter writer)

private string? GetExternalReferenceV3()
{
if (IsStandalone)
{
return ExternalResource;
}

if (Id != null)
{
if (IsFragment)
Expand Down Expand Up @@ -319,24 +391,107 @@ protected virtual void SetAdditional31MetadataFromMapNode(JsonObject jsonObject)

internal void SetJsonPointerPath(string pointer, ParsingContext context)
{
if (IsExternal)
{
IsStandalone = pointer.IndexOf('#') < 0;
}

// Relative reference to internal JSON schema node/resource (e.g. "#/properties/b")
#if NETSTANDARD2_1 || NETCOREAPP2_1_OR_GREATER || NET5_0_OR_GREATER
if (pointer.StartsWith("#/", StringComparison.OrdinalIgnoreCase) && !pointer.Contains("/components/schemas", StringComparison.OrdinalIgnoreCase))
#else
if (pointer.StartsWith("#/", StringComparison.OrdinalIgnoreCase) && !pointer.ToLowerInvariant().Contains("/components/schemas"))
#endif
if (pointer.StartsWith("#/", StringComparison.OrdinalIgnoreCase) && !pointer.StartsWith("#/components/", StringComparison.OrdinalIgnoreCase))
{
ReferenceV3 = ResolveRelativePointer(context.GetLocation(), pointer);
}

// Absolute reference or anchor (e.g. "#/components/schemas/..." or full URL)
else if ((pointer.Contains('#') || pointer.StartsWith("http", StringComparison.OrdinalIgnoreCase))
&& !string.Equals(ReferenceV3, pointer, StringComparison.OrdinalIgnoreCase))
// Absolute reference, anchor, or relative pointer (e.g. "#/components/schemas/...", full URL, or "schemas/uuid.schema.json")
else if (!string.IsNullOrEmpty(_referenceV3)
? !string.Equals(_referenceV3, pointer, StringComparison.OrdinalIgnoreCase)
: !MatchesDefaultReferenceV3(pointer))
{
ReferenceV3 = pointer;
}
}

private bool MatchesDefaultReferenceV3(string pointer)
{
if (IsExternal)
{
if (IsStandalone || Id is null)
{
return string.Equals(ExternalResource, pointer, StringComparison.OrdinalIgnoreCase);
}

if (IsFragment)
{
return ExternalResource is not null &&
pointer.Length == ExternalResource.Length + 1 + Id.Length &&
pointer.StartsWith(ExternalResource, StringComparison.OrdinalIgnoreCase) &&
pointer[ExternalResource.Length] == '#' &&
pointer.EndsWith(Id, StringComparison.OrdinalIgnoreCase);
}

if (Id.StartsWith("http://", StringComparison.OrdinalIgnoreCase) ||
Id.StartsWith("https://", StringComparison.OrdinalIgnoreCase))
{
return string.Equals(Id, pointer, StringComparison.OrdinalIgnoreCase);
}

var externalTypeName = GetReferenceTypeDisplayName(Type);
if (ExternalResource is null || externalTypeName is null)
{
return false;
}

const string ComponentsPrefix = "#/components/";
var expectedExternalLength = ExternalResource.Length + ComponentsPrefix.Length + externalTypeName.Length + 1 + Id.Length;
return pointer.Length == expectedExternalLength &&
pointer.StartsWith(ExternalResource, StringComparison.OrdinalIgnoreCase) &&
string.Compare(pointer, ExternalResource.Length, ComponentsPrefix, 0, ComponentsPrefix.Length, StringComparison.OrdinalIgnoreCase) == 0 &&
string.Compare(pointer, ExternalResource.Length + ComponentsPrefix.Length, externalTypeName, 0, externalTypeName.Length, StringComparison.OrdinalIgnoreCase) == 0 &&
pointer[ExternalResource.Length + ComponentsPrefix.Length + externalTypeName.Length] == '/' &&
pointer.EndsWith(Id, StringComparison.OrdinalIgnoreCase);
}

if (Type is ReferenceType.Tag or ReferenceType.SecurityScheme)
{
return string.Equals(Id, pointer, StringComparison.OrdinalIgnoreCase);
}

if (!string.IsNullOrEmpty(Id) && Id is not null &&
(Id.StartsWith("http://", StringComparison.OrdinalIgnoreCase) ||
Id.StartsWith("https://", StringComparison.OrdinalIgnoreCase) ||
Id.IndexOf("#/components", StringComparison.OrdinalIgnoreCase) >= 0))
{
return string.Equals(Id, pointer, StringComparison.OrdinalIgnoreCase);
}

var typeName = GetReferenceTypeDisplayName(Type) ?? string.Empty;
var idSegment = Id ?? string.Empty;
const string LocalComponentsPrefix = "#/components/";
var expectedLocalLength = LocalComponentsPrefix.Length + typeName.Length + 1 + idSegment.Length;
return pointer.Length == expectedLocalLength &&
pointer.StartsWith(LocalComponentsPrefix, StringComparison.OrdinalIgnoreCase) &&
string.Compare(pointer, LocalComponentsPrefix.Length, typeName, 0, typeName.Length, StringComparison.OrdinalIgnoreCase) == 0 &&
pointer[LocalComponentsPrefix.Length + typeName.Length] == '/' &&
pointer.EndsWith(idSegment, StringComparison.OrdinalIgnoreCase);
}

private static string? GetReferenceTypeDisplayName(ReferenceType type) => type switch
{
ReferenceType.Schema => OpenApiConstants.Schemas,
ReferenceType.Response => OpenApiConstants.Responses,
ReferenceType.Parameter => OpenApiConstants.Parameters,
ReferenceType.Example => OpenApiConstants.Examples,
ReferenceType.RequestBody => OpenApiConstants.RequestBodies,
ReferenceType.Header => OpenApiConstants.Headers,
ReferenceType.SecurityScheme => OpenApiConstants.SecuritySchemes,
ReferenceType.Link => OpenApiConstants.Links,
ReferenceType.Callback => OpenApiConstants.Callbacks,
ReferenceType.Tag => OpenApiConstants.Tags,
ReferenceType.PathItem => OpenApiConstants.PathItems,
ReferenceType.MediaType => OpenApiConstants.MediaTypes,
_ => type.GetDisplayName(),
};

private static string ResolveRelativePointer(string nodeLocation, string relativeRef)
{
// Convert nodeLocation to path segments
Expand Down
64 changes: 50 additions & 14 deletions src/Microsoft.OpenApi/Models/OpenApiDocument.cs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright (c) Microsoft Corporation. All rights reserved.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT license.

using System;
Expand Down Expand Up @@ -631,7 +631,12 @@ private static string ConvertByteArrayToString(byte[] hash)

string uriLocation;
var id = reference.Id;
if (!string.IsNullOrEmpty(id) && id!.Contains('/')) // this means its a URL reference
var isStandaloneExternal = reference.IsExternal && IsStandaloneExternalReference(reference);
if (isStandaloneExternal)
{
uriLocation = reference.ExternalResource ?? id ?? string.Empty;
}
else if (!string.IsNullOrEmpty(id) && id!.IndexOf('/') >= 0)
{
uriLocation = id!;
}
Expand Down Expand Up @@ -662,33 +667,64 @@ private static string ConvertByteArrayToString(byte[] hash)
relativePath = $"#{OpenApiConstants.ComponentsSegment}{reference.Type.GetDisplayName()}/{id}";
}

Uri? externalResourceUri = useExternal ? Workspace?.GetDocumentId(reference.ExternalResource, BaseUri) : null;
Uri? externalResourceUri = useExternal
? (BaseUri is not null ? Workspace?.GetDocumentId(reference.ExternalResource, BaseUri) : Workspace?.GetDocumentId(reference.ExternalResource))
: null;

uriLocation = useExternal && externalResourceUri is not null
? externalResourceUri.AbsoluteUri + relativePath
: BaseUri + relativePath;
}

var absoluteUri =
#if NETSTANDARD2_1 || NETCOREAPP || NET5_0_OR_GREATER
uriLocation.StartsWith('#')
#else
uriLocation.StartsWith("#", StringComparison.OrdinalIgnoreCase)
#endif
switch
Uri? resolvedUri = null;
if (isStandaloneExternal && useExternal && reference.ExternalResource is not null &&
(BaseUri is not null ? Workspace?.GetDocumentId(reference.ExternalResource, BaseUri) : Workspace?.GetDocumentId(reference.ExternalResource)) is Uri extDocUri)
{
true => new Uri(BaseUri, uriLocation).AbsoluteUri,
false => new Uri(uriLocation).AbsoluteUri
};
resolvedUri = extDocUri;
}
else if (BaseUri is not null && Uri.TryCreate(BaseUri, uriLocation, out var relCombinedUri))
{
resolvedUri = relCombinedUri;
}
else if (Uri.TryCreate(uriLocation, UriKind.Absolute, out var absUri))
{
resolvedUri = absUri;
}

if (resolvedUri is null)
{
return null;
}

if (reference.Type is ReferenceType.Schema && absoluteUri.Contains('#') && parentSchema is not null)
var absoluteUri = resolvedUri.AbsoluteUri;

if (reference.Type is ReferenceType.Schema && absoluteUri.IndexOf('#') >= 0 && parentSchema is not null)
{
return Workspace?.ResolveJsonSchemaReference(absoluteUri, parentSchema);
}

return Workspace?.ResolveReference<IOpenApiReferenceable>(absoluteUri);
}

private static bool IsStandaloneExternalReference(BaseOpenApiReference reference)
{
if (reference.IsStandalone)
{
return true;
}

var referenceV3 = reference.ReferenceV3;
if (!string.IsNullOrEmpty(referenceV3))
{
return referenceV3!.IndexOf('#') < 0;
}

return reference.Type == ReferenceType.Schema &&
reference.Id is { } id &&
id.IndexOf('#') < 0 &&
id.IndexOf('/') >= 0;
}

private static bool IsSubComponent(string reference)
{
// Normalize fragment part only
Expand Down
26 changes: 17 additions & 9 deletions src/Microsoft.OpenApi/Reader/Services/OpenApiWorkspaceLoader.cs
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
using System;
using System;
using System.Collections.Generic;
using System.Linq;
using System.Runtime.CompilerServices;
Expand Down Expand Up @@ -95,17 +95,25 @@ private async Task<bool> LoadNextReferenceAsync(
return false;
}

using var input = await _loader.LoadAsync(frame.Document.BaseUri, new Uri(resource, UriKind.RelativeOrAbsolute), cancellationToken).ConfigureAwait(false);
var result = await OpenApiModelFactory.ReadDocumentAsync(input, format, uri, _readerSettings, cancellationToken).ConfigureAwait(false);
if (result.Diagnostic is { } externalDiagnostic)
try
{
diagnostic.AppendDiagnostic(externalDiagnostic, uri.AbsoluteUri);
using var input = await _loader.LoadAsync(frame.Document.BaseUri, new Uri(resource, UriKind.RelativeOrAbsolute), cancellationToken).ConfigureAwait(false);
var result = await OpenApiModelFactory.ReadDocumentAsync(input, format, uri, _readerSettings, cancellationToken).ConfigureAwait(false);
if (result.Diagnostic is { } externalDiagnostic)
{
diagnostic.AppendDiagnostic(externalDiagnostic, uri.AbsoluteUri);
}
loadedDocument = result.Document;
documents.Add(uri.AbsoluteUri, loadedDocument);
if (loadedDocument is not null)
{
RegisterDocument(loadedDocument, frame.Depth + 1, references, pending);
}
}
loadedDocument = result.Document;
documents.Add(uri.AbsoluteUri, loadedDocument);
if (loadedDocument is not null)
catch (Exception ex) when (ex is not OperationCanceledException)
{
RegisterDocument(loadedDocument, frame.Depth + 1, references, pending);
diagnostic.Errors.Add(new(reference.ReferenceV3, ex.Message));
documents[uri.AbsoluteUri] = null;
}
}

Expand Down
Loading
Loading