RsqlParserNet 0.3.0-preview.1

RsqlParserNet

Package	Latest Release	Downloads
RsqlParserNet
RsqlParserNet.Linq
RsqlParserNet.AspNetCore
RsqlParserNet.EntityFrameworkCore
RsqlParserNet.FastEndpoints
RsqlParserNet.OpenApi
RsqlParserNet.Swashbuckle
RsqlParserNet.NSwag

A dependency-light .NET parser for RSQL/FIQL-style REST API query expressions.

RsqlParserNet parses query text into a typed AST with source spans and structured diagnostics. The core package does not depend on ASP.NET Core, LINQ, Entity Framework Core, or ORM APIs.

Current status: all packages are aligned for 0.3.0-preview.1. The package family is ready for the next preview release, but public API changes are still possible before 1.0.0.

Installation

Core parser:

dotnet add package RsqlParserNet --prerelease

LINQ adapter:

dotnet add package RsqlParserNet.Linq --prerelease

ASP.NET Core binding:

dotnet add package RsqlParserNet.AspNetCore --prerelease

Entity Framework Core helpers:

dotnet add package RsqlParserNet.EntityFrameworkCore --prerelease

FastEndpoints helpers:

dotnet add package RsqlParserNet.FastEndpoints --prerelease

RsqlParserNet.FastEndpoints currently requires FastEndpoints 7.0.1 or newer. Applications on older FastEndpoints versions can still use the ASP.NET Core query models directly through RsqlQueryRequest.Parse(...).

OpenAPI helpers:

dotnet add package RsqlParserNet.OpenApi --prerelease

Swashbuckle helpers:

dotnet add package RsqlParserNet.Swashbuckle --prerelease

NSwag helpers:

dotnet add package RsqlParserNet.NSwag --prerelease

For local development, reference the project directly:

<ProjectReference Include="src/RsqlParserNet/RsqlParserNet.csproj" />
<ProjectReference Include="src/RsqlParserNet.Linq/RsqlParserNet.Linq.csproj" />
<ProjectReference Include="src/RsqlParserNet.AspNetCore/RsqlParserNet.AspNetCore.csproj" />
<ProjectReference Include="src/RsqlParserNet.EntityFrameworkCore/RsqlParserNet.EntityFrameworkCore.csproj" />
<ProjectReference Include="src/RsqlParserNet.FastEndpoints/RsqlParserNet.FastEndpoints.csproj" />
<ProjectReference Include="src/RsqlParserNet.OpenApi/RsqlParserNet.OpenApi.csproj" />
<ProjectReference Include="src/RsqlParserNet.Swashbuckle/RsqlParserNet.Swashbuckle.csproj" />
<ProjectReference Include="src/RsqlParserNet.NSwag/RsqlParserNet.NSwag.csproj" />

Quick Start

using RsqlParserNet;

var query = RsqlParser.Parse("""status=="active";title=="Bike*"""");

foreach (var comparison in query.Root.Comparisons())
{
    Console.WriteLine($"{comparison.Selector} {comparison.Operator} {comparison.Values[0].Text}");
}

For non-exception flows, use TryParse:

var result = RsqlParser.TryParse("status==");

if (!result.Success)
{
    foreach (var diagnostic in result.Diagnostics)
    {
        Console.WriteLine($"{diagnostic.Code}: {diagnostic.Message}");
    }
}

Supported Syntax

Common RSQL/FIQL forms are supported:

status==active
status=="active"
title=="SUP*"
status=in=(active,draft)
createdAt>=2026-01-01
status==active;title=="SUP*"
status==active,title=="Bike*"
(status==active;title=="SUP*"),status==draft

Logical operators:

; = AND
, = OR

AND has higher precedence than OR. Parentheses can override precedence.

See docs/syntax.md for the full grammar, selector rules, value behavior, custom operators, and wildcard/date semantics.

Options

Parser behavior can be configured:

var options = RsqlParseOptions.Default with
{
    AllowWordLogicalOperators = false,
    AllowDottedSelectors = true,
    CustomOperators =
    [
        new RsqlCustomOperator("=contains="),
        new RsqlCustomOperator("=all=", RequiresMultipleValues: true)
    ]
};

var result = RsqlParser.TryParse("title=contains=Bike", options);

Custom operators must use FIQL-style syntax such as =contains=, must not duplicate built-in operators, and must not be configured more than once.

Diagnostics

Parse errors are returned as structured diagnostics:

var result = RsqlParser.TryParse("status==");
var diagnostic = result.Diagnostics[0];

Console.WriteLine(diagnostic.Code);
Console.WriteLine(diagnostic.Message);
Console.WriteLine(diagnostic.Span.Start);
Console.WriteLine(diagnostic.Start.Line);
Console.WriteLine(diagnostic.Start.Column);

Current diagnostic codes:

RsqlParser.Parse throws ArgumentException for empty input and RsqlParseException for invalid syntax. RsqlParseException.Diagnostics contains the same structured diagnostics returned by TryParse.

LINQ Adapter

The repository includes an early RsqlParserNet.Linq adapter project. It translates parsed AST nodes into expression tree predicates using explicit selector mappings:

using RsqlParserNet;
using RsqlParserNet.Linq;

var query = RsqlParser.Parse("status=in=(active,draft);count>=10");

var filtered = products.ApplyRsql(query, options =>
{
    options.Allow("status", x => x.Status);
    options.Allow("count", x => x.Count);
});

You can also build the predicate separately when another layer should decide how to compose or apply it:

var predicate = RsqlPredicateBuilder.BuildPredicate<Product>("status==active", options =>
{
    options.Allow("status", x => x.Status);
});

var filtered = products.Where(predicate);

For repeated endpoint/query contracts, put mappings in a reusable profile:

public sealed class ProductRsqlProfile : RsqlLinqProfile<Product>
{
    public override RsqlParseOptions ConfigureParseOptions(RsqlParseOptions options)
    {
        return options.WithLinqOperators();
    }

    public override void Configure(RsqlLinqOptions<Product> options)
    {
        options.Allow("name", x => x.Name);
        options.Allow("status", x => x.Status);
        options.Allow("count", x => x.Count);
        options.Allow("tags", x => x.Tags);
        options.AllowStringContainsOperator();
        options.AllowStringStartsWithOperator();
        options.AllowStringEndsWithOperator();
        options.AllowCollectionAnyOperator();
        options.AllowCollectionAllOperator();
    }
}

var filtered = products.ApplyRsql("status==active;name=contains=ik", new ProductRsqlProfile());

The adapter currently supports:

Values are converted using the mapped member type, including common scalar types, enums, Guid, DateTime, DateTimeOffset, DateOnly, and TimeOnly.

String helper operators and wildcard equality use the LINQ provider's string comparison behavior by default. APIs can opt into endpoint-wide case-insensitive string matching through RsqlLinqOptions<T>.StringComparisonMode.

Custom operators can be translated explicitly after they are configured in parser options:

var parseOptions = RsqlParseOptions.Default with
{
    CustomOperators = [new RsqlCustomOperator(RsqlLinqOperators.Contains)]
};

var filtered = products.ApplyRsql("name=contains=ik", options =>
{
    options.Allow("name", x => x.Name);
    options.AllowStringContainsOperator();
}, parseOptions);

Collection fields can use explicit custom operators:

tags=any=(bike,outdoor)
tags=all=(bike,outdoor)

String equality supports common * wildcards by default:

name==B*    -> StartsWith("B")
name==*met  -> EndsWith("met")
name==*ik*  -> Contains("ik")
name==Bo*d  -> StartsWith("Bo") && EndsWith("d")

See docs/linq-adapter.md for wildcard behavior, value conversion, and adapter limitations. See docs/aspnet-core-usage.md for ASP.NET Core request handling examples.

ASP.NET Core Binding

RsqlParserNet.AspNetCore adds bindable query wrappers for request query strings. Minimal APIs can accept RsqlQueryRequest directly to reuse parsed filter, sort, and page state:

builder.Services.AddRsqlQueryRequest(
    configureFilter: options =>
    {
        options.ParseOptions = ProductRsqlProfile.Instance.ConfigureParseOptions(RsqlParseOptions.Default);
    },
    configurePage: options => options.MaxPageSize = 100);

app.MapGet("/products", async (
    RsqlQueryRequest request,
    AppDbContext db) =>
{
    if (!request.IsValid)
    {
        return Results.ValidationProblem(request.ToValidationErrors());
    }

    if (!request.TryApplyTo(db.Products, ProductRsqlProfile.Instance, out var query, out var errors))
    {
        return Results.ValidationProblem(request.ToValidationErrors(errors));
    }

    query = request.Sort.HasRequest
        ? query
        : query.OrderBy(product => product.Id);

    var result = await query.ToRsqlPageAsync(request.PageRequest);

    return Results.Ok(result);
});

Adapter Direction

Expression trees are a good fit for LINQ and Entity Framework Core integration, but they belong in separate adapter packages rather than the parser core.

The intended adapter shape is explicit and allowlisted:

query.ApplyRsql(filter, options =>
{
    options.Allow("title", x => x.Title);
    options.Allow("status", x => x.Status);
    options.Allow("createdAt", x => x.CreatedAt);
});

The core parser should not expose arbitrary reflected entity/property access. Future adapters should translate the AST into expression trees only through configured field mappings.

Framework adapters should stay separate when they need framework-specific dependencies. RsqlParserNet.AspNetCore owns ASP.NET Core binding helpers.

RsqlParserNet.EntityFrameworkCore owns EF Core async execution helpers, including paged result helpers that return items and pagination metadata. Sorting uses the same allowlisted profile mappings as filtering with sort=field, sort=-field, and multi-field sort text such as sort=-createdAt,name.

RsqlParserNet.FastEndpoints owns FastEndpoints-specific validation glue. It reuses the ASP.NET Core query models and adds ValidationFailure entries to the endpoint, so FastEndpoints APIs can keep their normal validation response flow.

RsqlParserNet.OpenApi owns endpoint-scoped OpenAPI query parameter documentation helpers for filter, sort, page, and pageSize.

RsqlParserNet.Swashbuckle owns Swashbuckle operation filters for documenting the same query parameters through SwaggerGen.

RsqlParserNet.NSwag owns NSwag operation processors for documenting the same query parameters through NSwag and FastEndpoints.Swagger-style OpenAPI generation.

Development

dotnet build RsqlParserNet.sln
dotnet test RsqlParserNet.sln
dotnet test RsqlParserNet.sln --collect:"XPlat Code Coverage"
dotnet pack src/RsqlParserNet/RsqlParserNet.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.Linq/RsqlParserNet.Linq.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.AspNetCore/RsqlParserNet.AspNetCore.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.EntityFrameworkCore/RsqlParserNet.EntityFrameworkCore.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.FastEndpoints/RsqlParserNet.FastEndpoints.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.OpenApi/RsqlParserNet.OpenApi.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.Swashbuckle/RsqlParserNet.Swashbuckle.csproj --configuration Release --output artifacts/packages
dotnet pack src/RsqlParserNet.NSwag/RsqlParserNet.NSwag.csproj --configuration Release --output artifacts/packages

Coverage is collected locally with Coverlet. A public percentage badge will be added after coverage publishing is wired into CI.

Release Automation

Pushing a v* tag builds, tests, packs, and creates a GitHub Release with every package artifact. Tags also publish all generated .nupkg and .snupkg files to NuGet.org when the repository secret NUGET_API_KEY is configured.

The manual Publish NuGet workflow remains available for retrying one package from a release tag.

Project Notes

• Versioning: CHANGELOG.md
• Syntax details: docs/syntax.md
• LINQ adapter details: docs/linq-adapter.md
• ASP.NET Core usage: docs/aspnet-core-usage.md
• EF Core helpers: docs/entity-framework-core.md
• FastEndpoints usage: docs/fastendpoints-usage.md
• OpenAPI usage: docs/openapi-usage.md
• Swashbuckle usage: docs/swashbuckle-usage.md
• NSwag usage: docs/nswag-usage.md
• 1.0.0 readiness: docs/v1-readiness.md
• Release process: docs/release.md