Recursive AI

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.

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"}]}
Terminal
dotnet add package RecursiveAI.OneNlp

Requires .NET 10 (net10.0); .NET 9 and earlier aren’t supported.

C#
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, then dotnet run.

Full program

C#
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:

C#
using (var input = File.OpenRead("rules.jsonl"))
    ruler.LoadPatterns(input);

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 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.

All onenlp recipes