OpenSourceInitiative.LicenseApi 3.0.0

OpenSourceInitiative.LicenseApi

A lightweight, multi-targeted (.NET 10 / netstandard2.0) client library for the Open Source Initiative License API. Fetches the OSI license catalog, supports filtering by SPDX ID, name, keyword, and steward, and extracts human-readable license text from the OSI HTML pages. No caching layer — every call goes to the network; callers that want caching add their own decorator.

Quick start

DI registration (recommended)

services.AddOsiLicensesClient();

// With options
services.AddOsiLicensesClient(options =>
{
    options.BaseAddress = new Uri("https://...");   // default: OSI API
});

Resolve IOsiClient from the container:

var client = sp.GetRequiredService<IOsiClient>();

// Stream all licenses
await foreach (var license in client.GetAllLicensesAsyncEnumerable())
    Console.WriteLine(license?.Name);

// Filter
var gplFamily = await client.GetBySpdxIdAsync("GPL*");
var popular   = await client.GetByKeywordAsync(OsiLicenseKeyword.PopularStrongCommunity);

Standalone (no DI)

await using var client = new OsiClient();
var mit = await client.GetByOsiIdAsync("mit");
Console.WriteLine(mit?.LicenseText);

Public API surface

IOsiClient

The primary interface for all license queries. Lives at OpenSourceInitiative.LicenseApi.Interfaces.

Implements IDisposable and IAsyncDisposable.

Input handling: id/name/steward/keyword arguments are always treated as opaque values and escaped before being combined with the configured BaseAddress — a caller passing a full URL, a //host reference, or .. segments through one of these methods cannot redirect the request to a different host. Don't rely on this as input validation, though: garbage in still means "license not found" or a JsonException, not a meaningful error.

OsiClient

public sealed class — the concrete HTTP implementation of IOsiClient. Registered as a typed IHttpClientFactory client named "OsiClient" when using DI.

Constructor: OsiClient(ILogger<OsiClient>? logger, OsiClientOptions? options, HttpClient? httpClient) — all parameters optional. When httpClient is null, the client owns and disposes the inner HttpClient; when provided externally it is not disposed.

License text is fetched automatically per license via a two-step strategy:

1. OSI HTML page — extracts the node with CSS class license-content.
2. Steward HTML URL — last resort, only used if the steward URL doesn't already point at a .txt file.

If both steps fail (network error, unreachable page, markup without a license-content node), LicenseText is left as an empty string rather than throwing — a scraping failure on a single license does not fail the whole call.

OsiClientOptions

public sealed class — configures the DI registration. Lives at OpenSourceInitiative.LicenseApi.Options.

OsiLicense

public sealed record — represents one OSI license entry. Lives at OpenSourceInitiative.LicenseApi.Models.

OsiLicenseExtensions adds license.GetLicenseText(httpClient, token) and license.GetAndSetLicenseText(httpClient, token) for re-fetching or backfilling the text on an existing instance.

OsiLicenseKeyword

public enum — OSI classification keywords. Lives at OpenSourceInitiative.LicenseApi.Enums.

Values: PopularStrongCommunity, International, SpecialPurpose, NonReusable, Superseded, VoluntarilyRetired, RedundantWithMorePopular, OtherMiscellaneous, Uncategorized.

Serializes to/from the OSI API string tokens (e.g. popular-strong-community) via OsiLicenseKeywordsConverter.

ServiceCollectionExtensions

public static class — the single registration entry point. Lives at OpenSourceInitiative.LicenseApi.Extensions.

AddOsiLicensesClient(this IServiceCollection, Action<OsiClientOptions>?) — registers a named IHttpClientFactory client ("OsiClient") and IOsiClient → OsiClient as transient.

OsiException / OsiInitializationException

public abstract/sealed class — base and derived exception types. Live at OpenSourceInitiative.LicenseApi.Exceptions.

OsiInitializationException is thrown by the obsolete OsiLicensesClient.InitializeAsync when the catalog fetch fails.

CustomFormatDateTimeConverter

public class JsonConverter<DateTime?> — handles the yyyyMMdd date format used by the OSI API for submission and approval dates. Registered via [JsonConverter] attributes on OsiLicense. Null and empty strings deserialize to null; an unrecognized format throws JsonException.

IOsiLicensesClient / OsiLicensesClient (deprecated)

[Obsolete] — wraps IOsiClient with an eager-loading, snapshot-based API kept for backward compatibility. Use IOsiClient directly for new code. Unlike IOsiClient, its SearchAsync/Search assume every entry returned by the API has a non-null Id/Name; a malformed catalog entry missing either field will throw a NullReferenceException here rather than being filtered out.

Target frameworks