RsqlParserNet.AspNetCore 1.0.0

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: 1.0.0 is the first stable release for the aligned package family.

Installation

Choose the smallest package that owns the behavior you need:

Selectors are parsed as text. They are not reflected onto entity properties by the core package. Application code and adapters should explicitly allowlist the selectors they accept.

Core parser:

dotnet add package RsqlParserNet

LINQ adapter:

dotnet add package RsqlParserNet.Linq

ASP.NET Core binding:

dotnet add package RsqlParserNet.AspNetCore

Entity Framework Core helpers:

dotnet add package RsqlParserNet.EntityFrameworkCore

FastEndpoints helpers:

dotnet add package RsqlParserNet.FastEndpoints

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

Swashbuckle helpers:

dotnet add package RsqlParserNet.Swashbuckle

NSwag helpers:

dotnet add package RsqlParserNet.NSwag

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.

For API responses, diagnostics can be projected without depending on any ASP.NET Core adapter:

var result = RsqlParser.TryParse(filter);

if (!result.Success)
{
    var errors = result.Diagnostics.Select(diagnostic => new
    {
        diagnostic.Code,
        diagnostic.Message,
        diagnostic.Start.Line,
        diagnostic.Start.Column
    });

    return Results.BadRequest(errors);
}

Core AST Model

The core parser returns a typed AST and does not assign query semantics to application fields:

Use RsqlNodeExtensions.Comparisons() when you only need to inspect every comparison node:

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

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

Manual AST Filtering

Use the core package directly when an endpoint supports a small, controlled subset and does not need RsqlParserNet.Linq.

This example supports only:

• AND groups
• ==
• exactly one value
• explicitly allowlisted selectors

using RsqlParserNet;

static IQueryable<Product> ApplyProductFilter(IQueryable<Product> query, RsqlNode node)
{
    return node switch
    {
        RsqlComparisonNode comparison => ApplyProductComparison(query, comparison),
        RsqlLogicalNode { Operator: RsqlLogicalOperator.And } logical =>
            logical.Children.Aggregate(query, ApplyProductFilter),
        RsqlLogicalNode { Operator: RsqlLogicalOperator.Or } =>
            throw new NotSupportedException("OR is not supported by this endpoint."),
        _ => throw new NotSupportedException("Unsupported RSQL node.")
    };
}

static IQueryable<Product> ApplyProductComparison(
    IQueryable<Product> query,
    RsqlComparisonNode comparison)
{
    if (comparison.Operator is not RsqlComparisonOperator.Equal)
    {
        throw new NotSupportedException("Only == is supported by this endpoint.");
    }

    if (comparison.Values.Count is not 1)
    {
        throw new NotSupportedException("Only one comparison value is supported.");
    }

    var value = comparison.Values[0].Text
        ?? throw new NotSupportedException("Null values are not supported by this endpoint.");

    return comparison.Selector switch
    {
        "status" => query.Where(product => product.Status == value),
        "title" => query.Where(product => product.Title == value),
        _ => throw new ArgumentException($"Unsupported filter field '{comparison.Selector}'.")
    };
}

Endpoint code can parse first, return syntax diagnostics, and then apply the allowlisted subset:

var result = RsqlParser.TryParse(filter);

if (!result.Success)
{
    return Results.BadRequest(result.Diagnostics.Select(diagnostic => new
    {
        diagnostic.Code,
        diagnostic.Message,
        diagnostic.Start.Line,
        diagnostic.Start.Column
    }));
}

var products = ApplyProductFilter(db.Products, result.Query!.Root);

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