Dimension.cs

using System.Collections.Generic;
using System.Text.Json;
using System.Text.Json.Serialization;

namespace JSONstat.Models;

/// <summary>
/// A dataset dimension. Carries its <see cref="T:Category"/> and metadata, and
/// exposes the Toolkit-parity <c>Category</c> navigation family.
/// Source: <c>../wiki/dimensions.md</c>.
/// </summary>
public sealed class Dimension
{
    /// <summary>JSON-stat version (present on dimension responses).</summary>
    public string? Version { get; set; }

    /// <summary>Response class (present on dimension responses; omitted for dataset dimensions).</summary>
    public ResponseClass? Class { get; set; }

    /// <summary>Short descriptive text for the dimension.</summary>
    public string? Label { get; set; }

    /// <summary>The category information (wire property <c>category</c>).</summary>
    [JsonPropertyName("category")]
    public Category CategoryInfo { get; set; } = new Category();

    /// <summary>URL to an external dimension definition.</summary>
    public string? Href { get; set; }

    /// <summary>Provider-specific extension.</summary>
    public JsonElement? Extension { get; set; }

    /// <summary>Related resources.</summary>
    public Link? Link { get; set; }

    /// <summary>Annotations.</summary>
    public string[]? Note { get; set; }

    /// <summary>Provider-specific extension properties not modelled explicitly.</summary>
    [JsonExtensionData]
    public IDictionary<string, JsonElement>? ExtensionData { get; set; }

    /// <summary>The dimension id (set from the surrounding <c>dimension</c> map key).</summary>
    [JsonIgnore]
    public string Id { get; internal set; } = "";

    /// <summary>The resolved role (Toolkit convention; never written to the wire).</summary>
    [JsonIgnore]
    public DimensionRole Role { get; internal set; } = DimensionRole.Classification;

    /// <summary>The category labels in order.</summary>
    [JsonIgnore]
    public IReadOnlyList<string> CategoryLabels => CategoryInfo.Labels;

    /// <summary>The categories as entries.</summary>
    [JsonIgnore]
    public IReadOnlyList<CategoryEntry> Categories => CategoryInfo.Entries;

    /// <summary>Gets the category at <paramref name="index"/>, or <c>null</c>.</summary>
    public CategoryEntry? Category(int index) => CategoryInfo.Entry(index);

    /// <summary>Gets the category with id <paramref name="id"/>, or <c>null</c>.</summary>
    public CategoryEntry? Category(string id) => CategoryInfo.Entry(id);

    /// <summary>Builds the category order. Called by the owning dataset (or, for
    /// a dimension response, with size 0 to derive the count from the index).</summary>
    internal void Wire(int size) => CategoryInfo.Build(size);
}