/// <summary>
///     Simplified representation of a JSON Schema used in OpenAPI specs.
/// </summary>
public sealed class OpenApiSchema
{
    /// <summary>Schema type (e.g. <c>object</c>, <c>array</c>, <c>string</c>, <c>integer</c>).</summary>
    public string Type { get; set; } = "";
    /// <summary>Format qualifier (e.g. <c>int64</c>, <c>date-time</c>, <c>uuid</c>).</summary>
    public string Format { get; set; } = "";
    /// <summary>Referenced type name (from <c>$ref</c>), without the path prefix.</summary>
    public string? RefName { get; set; }
    /// <summary>For <c>array</c> types, the schema of the array items.</summary>
    public OpenApiSchema? Items { get; set; }
    /// <summary>For <c>object</c> types, the named properties.</summary>
    public Dictionary<string, OpenApiSchema> Properties { get; } = new(StringComparer.Ordinal);
    /// <summary>List of required property names for object schemas.</summary>
    public List<string> RequiredProperties { get; } = [];
    /// <summary>Human-readable description of this schema.</summary>
    public string Description { get; set; } = "";
    /// <summary>Enum values, if this is an enum schema.</summary>
    public List<string> EnumValues { get; } = [];

    /// <summary>
    ///     Returns a concise display string for this schema (e.g. <c>string</c>,
    ///     <c>User</c>, <c>Pet[]</c>, <c>integer (int64)</c>).
    /// </summary>
    public string ToDisplayString()
    {
        if (RefName is not null)
        {
            return RefName;
        }

        if (Type == "array" && Items is not null)
        {
            return $"{Items.ToDisplayString()}[]";
        }

        if (!string.IsNullOrEmpty(Format))
        {
            return $"{Type} ({Format})";
        }

        return string.IsNullOrEmpty(Type) ? "object" : Type;
    }
}