Flag nullable fields and drop options rows that repeat the type

src/Elastic.ApiExplorer/Components/PropertyTree/ApiProperty.cs

@@ -147,6 +147,9 @@ public record ApiProperty
 	public required string AnchorId { get; init; }
 	public required int Depth { get; init; }
 	public required bool IsRequired { get; init; }
+
+	/// <summary>Whether the value can be <c>null</c>; the type annotation leaves <c>null</c> out, so a badge says it.</summary>
+	public bool IsNullable { get; init; }
 	public required bool IsLast { get; init; }
 	public required bool IsRecursive { get; init; }
 

src/Elastic.ApiExplorer/Components/PropertyTree/ApiPropertyMarkdown.cs

@@ -70,6 +70,8 @@ private static void WriteProperty(StringBuilder markdown, ApiProperty property,
 
 		if (property.IsRequest)
 			_ = markdown.Append(property.IsRequired ? " — required" : " — optional");
+		if (property.IsNullable)
+			_ = markdown.Append(" — nullable");
 		if (property.ShowDeprecatedBadge)
 			_ = markdown.Append(" — deprecated");
 		if (property.IsRecursive)

src/Elastic.ApiExplorer/Components/PropertyTree/ApiPropertyTreeBuilder.cs

@@ -205,6 +205,7 @@ private ApiProperty BuildProperty(PropertyRow row, PropertyTreeScope scope)
 			AnchorId = row.AnchorId,
 			Depth = scope.Depth,
 			IsRequired = row.IsRequired,
+			IsNullable = _analyzer.IsNullable(propSchema),
 			IsLast = row.IsLast,
 			IsRecursive = isRecursive,
 			IsRequest = scope.IsRequest,
@@ -341,6 +342,8 @@ private IReadOnlyList<TypePageLink> BuildAlsoIncludes(TypeInfo typeInfo) =>
 		if (expansion.ArrayUnion is { } arrayUnion && (namesItsOptions || arrayUnion.Expands))
 			return null;
 
+		var discriminator = _analyzer.GetUnionDiscriminator(propSchema)?.PropertyName;
+
 		var sortedOptions = (typeInfo.UnionOptions ?? [])
 			.DistinctBy(o => o.Name)
 			.OrderByDescending(o => o.IsArray)
@@ -353,6 +356,15 @@ private IReadOnlyList<TypePageLink> BuildAlsoIncludes(TypeInfo typeInfo) =>
 			.DistinctBy(static o => o.Text)
 			.ToArray();
 
+		// Any other union whose type already reads `number | string` would only repeat it, unless the row has more to say.
+		if (
+			namesItsOptions
+			&& !expansion.HasUnionOptions
+			&& discriminator is null
+			&& NamesTheSameOptions(typeInfo.TypeName!, sortedOptions.Select(static o => o.Text))
+		)
+			return null;
+
 		if (sortedOptions.Length > 0 || expansion.HasUnionOptions)
 		{
 			var mixed = MixesLiteralsWithObjects(typeInfo, expansion);
@@ -365,7 +377,7 @@ private IReadOnlyList<TypePageLink> BuildAlsoIncludes(TypeInfo typeInfo) =>
 			{
 				Kind = UnionDisplayKind.Badges,
 				Keyword = typeInfo.UnionKeyword,
-				DiscriminatorProperty = _analyzer.GetUnionDiscriminator(propSchema)?.PropertyName,
+				DiscriminatorProperty = discriminator,
 				Badges = badges.ToArray(),
 				MoreOptions = mixed ? MoreOptionsText(typeInfo) : null
 			};
@@ -374,6 +386,10 @@ private IReadOnlyList<TypePageLink> BuildAlsoIncludes(TypeInfo typeInfo) =>
 		return null;
 	}
 
+	/// <summary>Whether a type formula such as <c>number | string</c> names exactly these options, in any order.</summary>
+	private static bool NamesTheSameOptions(string typeName, IEnumerable<string> options) =>
+		new HashSet<string>(typeName.Split(" | ", StringSplitOptions.TrimEntries), StringComparer.Ordinal).SetEquals(options);
+
 	/// <summary>A union with literal members as well as object variants, e.g. a sort order: <c>asc</c>, <c>desc</c> or an object.</summary>
 	private static bool MixesLiteralsWithObjects(TypeInfo typeInfo, Expansion expansion) =>
 		typeInfo is { IsUnion: true, EnumValues.Length: > 0 } && expansion.HasUnionOptions;

src/Elastic.ApiExplorer/Components/PropertyTree/ListingContent.cs

@@ -71,6 +71,7 @@ private static void Append(StringBuilder text, ApiPropertyList? properties, Page
 				.Append(property.Type.Text)
 				.Append('|')
 				.Append(property.IsRequired)
+				.Append(property.IsNullable)
 				.Append('|')
 				.Append(property.IsRecursive)
 				.Append('|')

src/Elastic.ApiExplorer/Components/PropertyTree/_Partials/_PropertyItem.cshtml

@@ -13,6 +13,10 @@
 		{
 			<span class="required @SchemaHelpers.StatusCssClass">required</span>
 		}
+		@if (Model.IsNullable)
+		{
+			<span class="nullable-badge @SchemaHelpers.StatusCssClass" data-tippy-content="This value can be null">nullable</span>
+		}
 		@if (Model.ShowDeprecatedBadge)
 		{
 			<span class="deprecated-badge @SchemaHelpers.StatusCssClass">deprecated</span>

src/Elastic.ApiExplorer/Model/SchemaAnalyzer.cs

@@ -298,12 +298,43 @@ private static bool IsInlineObject(UnionOption option) =>
 	/// parent: <c>anyOf[anyOf[A, B], C]</c> offers A, B and C. Named unions stay one option, so cyclic references cannot recurse.
 	/// </summary>
 	private static IEnumerable<IOpenApiSchema> FlattenInlineUnions(IEnumerable<IOpenApiSchema> members) =>
-		members.SelectMany(
+		members
+		// A `{ "type": "null" }` member is no option to pick: it makes the value nullable (see IsNullable).
+		.Where(static m => !IsNullOnly(m)).SelectMany(
 			m => m is not OpenApiSchemaReference && m.Properties is not { Count: > 0 } && UnionSchemas.TryGet(m, out _, out var inner)
 				? FlattenInlineUnions(inner)
 				: [m]
 		);
 
+	private static bool IsNullOnly(IOpenApiSchema member) => member is OpenApiSchema { Type: JsonSchemaType.Null };
+
+	/// <summary>
+	/// Whether a value of <paramref name="schema"/> can be <c>null</c>: its type lists <c>null</c> (OpenAPI 3.1, or 3.0's
+	/// <c>nullable: true</c> once read), or its union lets <c>null</c> through, nested unions included. The type annotation
+	/// leaves <c>null</c> out, so the row says it with a badge instead.
+	/// </summary>
+	public bool IsNullable(IOpenApiSchema? schema) => AllowsNull(schema, [with(ReferenceEqualityComparer.Instance)]);
+
+	/// <summary>
+	/// A union lets <c>null</c> through when any branch accepts it, a <c>oneOf</c> too. Read strictly, <c>null</c> matching
+	/// two <c>oneOf</c> branches fails it, but generated specs write <c>oneOf: [string | null, number | null]</c> for a
+	/// field the API accepts <c>null</c> for, and a missing badge would read as "never null".
+	/// </summary>
+	private bool AllowsNull(IOpenApiSchema? schema, HashSet<IOpenApiSchema> visited)
+	{
+		var resolved = ResolveSchema(schema) ?? schema;
+		// A union that refers back to itself adds nothing on the second visit.
+		if (resolved is null || !visited.Add(resolved))
+			return false;
+		if (resolved.Type?.HasFlag(JsonSchemaType.Null) == true)
+			return true;
+
+		// Each branch is checked on its own path, so a schema two branches share counts for both.
+		return (resolved.OneOf ?? []).Concat(resolved.AnyOf ?? []).Any(
+			m => AllowsNull(m, new HashSet<IOpenApiSchema>(visited, ReferenceEqualityComparer.Instance))
+		);
+	}
+
 	/// <summary>
 	/// Whether a union option lists anything when expanded: properties of its own (an array option's come from its items),
 	/// a map value with properties, or a nested union option that does.

src/Elastic.Documentation.Site/Assets/api-docs.css

@@ -1811,6 +1811,15 @@ a.type-linked:hover {
 	color: #f04e98;
 }
 
+/* Muted, unlike required: it describes the value rather than asking the reader for something. */
+.nullable-badge.type-status {
+	color: #516381;
+	padding: 0;
+	background-color: transparent;
+	font-size: 13px;
+	line-height: 16px;
+}
+
 /* Auth scheme link — compact outlined button with a leading icon */
 .api-page-intro .api-security-badges .api-auth-button {
 	display: inline-flex;

tests/Elastic.ApiExplorer.Tests/NullableTests.cs

@@ -0,0 +1,125 @@
+// Licensed to Elasticsearch B.V under one or more agreements.
+// Elasticsearch B.V licenses this file to you under the Apache 2.0 License.
+// See the LICENSE file in the project root for more information
+
+using AwesomeAssertions;
+using Elastic.ApiExplorer.Components.PropertyTree;
+using static Elastic.ApiExplorer.Tests.TestSpecs;
+
+namespace Elastic.ApiExplorer.Tests;
+
+/// <summary>Values that can be <c>null</c> say so with a badge, and a type that names its options has no options row.</summary>
+public class NullableTests
+{
+	[Test]
+	public async Task BuildPropertyList_NullableMembers_AreFlaggedAndNotRepeated()
+	{
+		var json =
+			"""
+			{
+			  "openapi": "3.1.0",
+			  "info": { "title": "t", "version": "1" },
+			  "paths": {},
+			  "components": {
+			    "schemas": {
+			      "Cat": { "type": "object", "properties": { "lives": { "type": "integer" } } },
+			      "Dog": { "type": "object", "properties": { "barks": { "type": "boolean" } } },
+			      "Holder": {
+			        "type": "object",
+			        "properties": {
+			          "max_score": { "oneOf": [ { "type": "number" }, { "type": ["null", "string"] } ] },
+			          "name": { "type": ["string", "null"] },
+			          "count": { "type": "integer" },
+			          "pet": { "oneOf": [ { "$ref": "#/components/schemas/Cat" }, { "type": "null" } ] },
+			          "kind": {
+			            "oneOf": [ { "type": "string" }, { "type": "integer" } ],
+			            "discriminator": { "propertyName": "type" }
+			          }
+			        }
+			      }
+			    }
+			  }
+			}
+			""";
+		var document = await LoadSpecAsync(json);
+
+		var list = BuilderFor(document).BuildPropertyList(document.Components!.Schemas!["Holder"], new PropertyTreeScope { Prefix = "" })!;
+
+		ApiProperty Row(string name) => list.Items.Single(p => p.Name == name);
+
+		Row("max_score").Type.Text.Should().Be("union number | string");
+		Row("max_score").Union.Should().BeNull("the type already reads number | string");
+		Row("max_score").IsNullable.Should().BeTrue("a member allows null");
+		Row("name").IsNullable.Should().BeTrue();
+		Row("name").Type.Text.Should().Be("string", "null shows as a badge, not in the type");
+		Row("count").IsNullable.Should().BeFalse();
+		Row("pet").IsNullable.Should().BeTrue();
+		Row("pet").Union?.Badges.Select(b => b.Text).Should().NotContain("null", "a null member is no option to pick");
+		Row("kind").Union!.DiscriminatorProperty.Should().Be("type", "a row with more to say than its type keeps its options row");
+
+		var markdown = new System.Text.StringBuilder();
+		ApiPropertyMarkdown.WriteList(markdown, new ApiPropertyList([Row("name")]), "/api/doc/fixture");
+		markdown.ToString().Should().Contain("— nullable");
+	}
+
+	[Test]
+	public async Task BuildPropertyList_AnyUnionBranchAllowingNull_MakesTheFieldNullable()
+	{
+		var json =
+			"""
+			{
+			  "openapi": "3.1.0",
+			  "info": { "title": "t", "version": "1" },
+			  "paths": {},
+			  "components": {
+			    "schemas": {
+			      "Holder": {
+			        "type": "object",
+			        "properties": {
+			          "nested": { "oneOf": [ { "type": "integer" }, { "anyOf": [ { "type": "string" }, { "type": "null" } ] } ] },
+			          "oneOfTwice": { "oneOf": [ { "type": ["string", "null"] }, { "type": ["integer", "null"] } ] },
+			          "anyOfTwice": { "anyOf": [ { "type": ["string", "null"] }, { "type": ["integer", "null"] } ] }
+			        }
+			      }
+			    }
+			  }
+			}
+			""";
+		var document = await LoadSpecAsync(json);
+
+		var list = BuilderFor(document).BuildPropertyList(document.Components!.Schemas!["Holder"], new PropertyTreeScope { Prefix = "" })!;
+
+		bool Nullable(string name) => list.Items.Single(p => p.Name == name).IsNullable;
+
+		Nullable("nested").Should().BeTrue("null passes through the inner anyOf");
+		Nullable("oneOfTwice").Should().BeTrue("generated specs write a nullable field this way, so it reads as nullable");
+		Nullable("anyOfTwice").Should().BeTrue("an anyOf lets null through when any branch accepts it");
+	}
+
+	[Test]
+	public async Task BuildPropertyList_OpenApi30Nullable_IsFlagged()
+	{
+		var json =
+			"""
+			{
+			  "openapi": "3.0.3",
+			  "info": { "title": "t", "version": "1" },
+			  "paths": {},
+			  "components": {
+			    "schemas": {
+			      "Holder": { "type": "object", "properties": { "note": { "type": "string", "nullable": true } } }
+			    }
+			  }
+			}
+			""";
+		var document = await LoadSpecAsync(json);
+
+		var note = BuilderFor(document).BuildPropertyList(
+			document.Components!.Schemas!["Holder"],
+			new PropertyTreeScope { Prefix = "" }
+		)!.Items.Single();
+
+		note.IsNullable.Should().BeTrue();
+		note.Type.Text.Should().Be("string");
+	}
+}

tests/Elastic.ApiExplorer.Tests/UnionOptionTests.cs

@@ -78,7 +78,7 @@ public async Task BuildPropertyList_InlineUnionWithAlias_NamesTheAliasInItsType(
 		var property = await PropertyAsync("node_or_count");
 
 		property.Type.Text.Should().Be("union NodeId | integer");
-		Badges(property).Should().Equal("NodeId", "integer");
+		property.Union.Should().BeNull("the type already reads NodeId | integer, so an options row would only repeat it");
 	}
 
 	[Test]