---
title: "Load entity matching rules from JSONL in C#"
url: https://recursiveai.org/onenlp/cookbook/load-entity-rules-from-jsonl/
description: "Load phrase and token rules from a UTF-8 file, label entities in text, and save the rules as JSON Lines with OneNLP."
version: "1.0.0"
---

# Load entity matching rules from JSONL in C#

**OneNLP** is a free, open-source natural language processing library for .NET from Recursive AI. MIT or Apache-2.0, no native dependencies.

[NuGet](https://www.nuget.org/packages/RecursiveAI.OneNlp) · [GitHub](https://github.com/recursive-ai-oss/onenlp-csharp) · [Docs](https://recursiveai.org/onenlp/docs/) · [Download example (.zip)](https://recursiveai.org/onenlp/cookbook/load-entity-rules-from-jsonl/load-entity-rules-from-jsonl.zip)

Save this UTF-8 text as `rules.jsonl` next to the project, or use the copy in the zip:

```json
{"label":"ORG","pattern":"North Vale"}
{"label":"TICKET","pattern":[{"ORTH":"A17"}]}
```

```shell
dotnet add package RecursiveAI.OneNlp
```

Requires [.NET 10](https://dotnet.microsoft.com/download/dotnet/10.0) (net10.0); .NET 9 and earlier aren’t supported.

```csharp
using RecursiveAI.OneNlp;
using RecursiveAI.OneNlp.Matching;

var ruler = new EntityRuler();
ruler.LoadPatterns("rules.jsonl");
var doc = Nlp.Analyze(
    "North Vale filed A17.");
ruler.Process(doc);
foreach (var entity in doc.Ents)
    Console.WriteLine(
        $"{entity.Label}: {entity}");
ruler.SavePatterns("saved.jsonl");
```

```text
ORG: North Vale
TICKET: A17
```

Unzip [the example](https://recursiveai.org/onenlp/cookbook/load-entity-rules-from-jsonl/load-entity-rules-from-jsonl.zip), then `dotnet run`.

## Full program

```csharp
using RecursiveAI.OneNlp;
using RecursiveAI.OneNlp.Matching;

var ruler = new EntityRuler();
ruler.LoadPatterns("rules.jsonl");
ruler.SavePatterns("saved.jsonl");

var reloaded = new EntityRuler();
reloaded.LoadPatterns("saved.jsonl");
var doc = Nlp.Analyze("North Vale filed A17.");
reloaded.Process(doc);
foreach (var entity in doc.Ents)
    Console.WriteLine($"{entity.Label}: {entity}");
Console.WriteLine("Saved and reloaded saved.jsonl");
```

`dotnet run` prints:

```text
ORG: North Vale
TICKET: A17
Saved and reloaded saved.jsonl
```

The snippet at the top writes `saved.jsonl`; the full program reloads it into a fresh ruler before labeling the text.

No model is needed. An invalid rule file throws `PatternFormatException` without adding any rules from that file.

## Variations

**Load from an open stream.** Use this in place of the first `LoadPatterns` call in the full program:

```csharp
using (var input = File.OpenRead("rules.jsonl"))
    ruler.LoadPatterns(input);
```

## Related recipes

- [Add rule-based entities](https://recursiveai.org/onenlp/cookbook/add-rule-based-entities/)
- [Match token patterns](https://recursiveai.org/onenlp/cookbook/match-token-patterns/)

---

## The short answer

Call `EntityRuler.LoadPatterns` with the path to your UTF-8 file, then call `Process(doc)` and read `doc.Ents`. `SavePatterns` writes the rule set, not the entities found in a particular document. Load the saved file into a new ruler and you can apply the same rules to another document.

## When should I use JSONL instead of JSON for entity rules?

Use JSON Lines when you want one complete rule per line. You can add a rule without editing an enclosing array or inserting a comma after the previous rule. Use a JSON array if an editor or another tool already exports the rules that way. `LoadPatterns` accepts both formats; `SavePatterns` always writes JSON Lines and replaces an existing destination file. Keep your input and output paths separate if you want to retain the source file as written.

## How do I write phrase and token rules in a JSONL file?

Each object has a `label` and a `pattern`. A string pattern matches a phrase: the ruler tokenizes `North Vale` before matching it. An array pattern describes tokens: `[{"ORTH":"A17"}]` tests the exact spelling of one token. Use several objects in that array when a rule must check several token positions. The outer JSONL file still has one rule per line, regardless of how many token positions a rule describes.

The optional `id` identifies an individual rule. Give rules different IDs when they share an entity label but you need to know which rule matched. See the [pattern format](https://recursiveai.org/onenlp/docs/matching/) for accepted token attributes and predicates.

`LoadPatterns` adds to the ruler’s existing rules. To replace a rule set after editing a file, load it into a new ruler rather than adding the file again. If a JSONL load fails, start with the line named in the error: check for malformed JSON, an unknown token attribute, or a string where the rule expects an array.
