If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/JamesNK/Newtonsoft.Json shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 4w ago
• 30+ active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 69% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live JamesNK/Newtonsoft.Json repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JamesNK/Newtonsoft.Json.

What it runs against: a local clone of JamesNK/Newtonsoft.Json — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in JamesNK/Newtonsoft.Json | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 61 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JamesNK/Newtonsoft.Json. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JamesNK/Newtonsoft.Json.git
#   cd Newtonsoft.Json
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of JamesNK/Newtonsoft.Json and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JamesNK/Newtonsoft.Json(\\.git)?\\b" \\
  && ok "origin remote is JamesNK/Newtonsoft.Json" \\
  || miss "origin remote is not JamesNK/Newtonsoft.Json (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "Src/Newtonsoft.Json/JsonConvert.cs" \\
  && ok "Src/Newtonsoft.Json/JsonConvert.cs" \\
  || miss "missing critical file: Src/Newtonsoft.Json/JsonConvert.cs"
test -f "Src/Newtonsoft.Json/Serialization/JsonSerializer.cs" \\
  && ok "Src/Newtonsoft.Json/Serialization/JsonSerializer.cs" \\
  || miss "missing critical file: Src/Newtonsoft.Json/Serialization/JsonSerializer.cs"
test -f "Src/Newtonsoft.Json/Linq/JToken.cs" \\
  && ok "Src/Newtonsoft.Json/Linq/JToken.cs" \\
  || miss "missing critical file: Src/Newtonsoft.Json/Linq/JToken.cs"
test -f "Src/Newtonsoft.Json/JsonReader.cs" \\
  && ok "Src/Newtonsoft.Json/JsonReader.cs" \\
  || miss "missing critical file: Src/Newtonsoft.Json/JsonReader.cs"
test -f "Src/Newtonsoft.Json/JsonWriter.cs" \\
  && ok "Src/Newtonsoft.Json/JsonWriter.cs" \\
  || miss "missing critical file: Src/Newtonsoft.Json/JsonWriter.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 61 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~31d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/JamesNK/Newtonsoft.Json"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Json.NET is a high-performance, feature-rich JSON serialization and deserialization library for .NET that handles complex object graphs, LINQ-to-JSON transformations, and custom type conversion with minimal boilerplate. It provides JsonTextReader/JsonTextWriter for streaming, JToken/LINQ for in-memory manipulation, and JsonConvert for simple serialize/deserialize operations—solving the problem of parsing, querying, and generating JSON in .NET applications without external dependencies. Traditional monolithic structure: Source code in a single Src directory (inferred from 6.5MB C# footprint), documentation in Doc/ with samples organized by feature (Doc/Samples/Bson/, Doc/Samples/Json/, Doc/Samples/Linq/, Doc/Samples/JsonPath/), and build automation in Build/ using PowerShell (build.ps1, psake.psm1, Sign-Package.ps1). Supports multiple .NET target frameworks compiled from a shared codebase.

.NET developers building applications that need robust JSON handling—from web APIs and microservices to desktop apps and data pipelines. Specifically: backend engineers who need flexible deserialization of API responses, library authors who want to avoid System.Text.Json limitations, and teams migrating legacy .NET Framework code that relied on Json.NET before Microsoft's built-in serializers.

Highly mature and production-ready. Json.NET is one of the most-downloaded NuGet packages ever (billions of downloads), has been actively maintained for 15+ years, and shows consistent releases in the Release Notes section. The CI/CD pipeline is set up with Azure DevOps (visible in badge and .github/workflows/codeql.yml), code analysis is automated, and the maintainer (JamesNK) actively manages issues and releases.

Low technical risk but single-maintainer dependency risk. The repository is tightly controlled by James NK with a clear CONTRIBUTING.md process, minimizing community friction. However, adoption of System.Text.Json in .NET Core / .NET 5+ means some teams migrate away; watch the GitHub issues and release cycle for momentum changes. No significant security vulnerabilities are evident from the file structure, but pinning a version is recommended for long-term stability.

No recent activity is visible in the provided file list snapshot, but the repository maintains an active release cycle (see Release Notes link in README). The presence of CodeQL analysis (.github/workflows/codeql.yml) indicates ongoing security scanning. Check the GitHub releases page and Azure DevOps pipeline for the latest version and active PRs.

git clone https://github.com/JamesNK/Newtonsoft.Json.git
cd Newtonsoft.Json
cd Build
.\runbuild.cmd

Or use PowerShell directly: .\build.ps1 in the Build directory. This invokes the psake-based build system defined in Build/psake.psm1 and Build/build.ps1, which handles compilation, testing, and packaging.

Daily commands: Build: cd Build && .\runbuild.cmd (Windows) or .\runbuild.ps1 (PowerShell). This triggers the full build pipeline (compile, test, package). For development iteration, use .\build.ps1 with specific targets. Tests run as part of the build; no separate test runner is exposed—check the Build/build.ps1 script for test targets (likely xUnit or NUnit based on .NET convention).

• Src/Newtonsoft.Json/JsonConvert.cs — Primary public API entry point for serialization and deserialization; every contributor must understand how JsonConvert.SerializeObject/DeserializeObject work.
• Src/Newtonsoft.Json/Serialization/JsonSerializer.cs — Core serialization engine that handles object-to-JSON conversion; essential for understanding the serialization pipeline and customization points.
• Src/Newtonsoft.Json/Linq/JToken.cs — Abstract base class for LINQ-to-JSON DOM model; foundational for both parsing and in-memory JSON manipulation across the codebase.
• Src/Newtonsoft.Json/JsonReader.cs — Abstract base class for JSON parsing; all reader implementations inherit from this, making it critical for understanding deserialization flow.
• Src/Newtonsoft.Json/JsonWriter.cs — Abstract base class for JSON writing; all writer implementations inherit from this, essential for understanding serialization output.
• Src/Newtonsoft.Json/Serialization/ContractResolver.cs — Determines how types are serialized by resolving contracts; key extension point that every advanced user needs to understand.
• Build/build.ps1 — Main build script that orchestrates compilation, testing, and packaging; contributors must follow this flow for local builds.

Add a Custom JsonConverter for a Specific Type

1. Create a new class inheriting from JsonConverter<T> in Src/Newtonsoft.Json/Converters/ (Src/Newtonsoft.Json/Converters/JsonConverter.cs)
2. Override CanConvert(Type objectType) to identify target types (YourCustomConverter.cs)
3. Implement ReadJson(JsonReader, Type, object, JsonSerializer) for deserialization logic (YourCustomConverter.cs)
4. Implement WriteJson(JsonWriter, object, JsonSerializer) for serialization logic (YourCustomConverter.cs)
5. Register converter via JsonSerializerSettings.Converters or [JsonConverter] attribute on the target type (Src/Newtonsoft.Json/JsonSerializerSettings.cs)

Extend ContractResolver for Custom Serialization Rules

1. Create a new class inheriting from DefaultContractResolver in Src/Newtonsoft.Json/Serialization/ (Src/Newtonsoft.Json/Serialization/DefaultContractResolver.cs)
2. Override CreateObjectContract(Type objectType) to customize object contract creation (YourCustomResolver.cs)
3. Override CreatePropertyList(Type type, MemberSerialization) to control which properties serialize (YourCustomResolver.cs)
4. Pass your resolver instance to JsonSerializerSettings.ContractResolver (Src/Newtonsoft.Json/JsonSerializerSettings.cs)

Create a Custom JsonReader for Non-Standard Input

1. Inherit from JsonReader abstract base class (Src/Newtonsoft.Json/JsonReader.cs)
2. Implement ReadAsInt32Async(), ReadAsStringAsync(), ReadAsDecimalAsync() and other Read* methods (YourCustomReader.cs)
3. Override MoveToContentAsync() to advance through tokens (YourCustomReader.cs)
4. Use JsonSerializer.Deserialize(JsonReader) or JsonConvert methods with your reader (Src/Newtonsoft.Json/JsonConvert.cs)

Add Support for a New Built-in Type via Converter

1. Create converter class in Src/Newtonsoft.Json/Converters/ following naming convention *Converter.cs (Src/Newtonsoft.Json/Converters/)
2. Implement CanConvert() to recognize the target type (YourNewConverter.cs)
3. Implement ReadJson() with parsing logic using JsonReader token methods (YourNewConverter.cs)
4. Implement WriteJson() with serialization logic using JsonWriter Write* methods (YourNewConverter.cs)
5. Register in JsonSerializerSettings.CreateDefaultSettings() or JsonConvert static initialization (Src/Newtonsoft.Json/JsonSerializerSettings.cs)

• C# / .NET — Primary target platform; Json.NET is a .NET library requiring language-level integration with reflection, attributes, and CLR type system.
• Streaming Reader/Writer Pattern — Enables

PowerShell build scripts: Build/build.ps1 uses psake (imported from Build/psake.psm1); requires PowerShell 5+ or Core on non-Windows. Multi-targeting complexity: The codebase compiles to multiple .NET versions (Framework, Core, Standard); conditional compilation directives are likely scattered throughout Src/. Signing: Build/Sign-Package.ps1 requires a certificate for official releases; local builds may skip this. Documentation format: Doc files use .aml (Sandcastle format), not Markdown; editing requires understanding the schema. No visible package.json or project file snippet: infer the actual .csproj structure by cloning; likely .NET Framework + SDK-style hybrid projects.

• Streaming JSON Reader/Writer Pattern — Json.NET's JsonReader/JsonWriter implement a token-based streaming model for efficient memory usage on large JSON files; understanding this is essential for high-performance scenarios
• Contract Resolution & Reflection-Based Serialization — Json.NET uses ContractResolver to map CLR types to JSON via reflection; customizing this is the key to implementing advanced scenarios like conditional serialization and type-specific conversion rules
• LINQ-to-JSON (DOM Queries) — JToken and its subclasses (JObject, JArray) provide a queryable in-memory representation of JSON, allowing XPath-like traversal and LINQ integration—distinct from the streaming API
• JsonConverter Plugin Architecture — Json.NET's extensibility model relies on custom JsonConverter subclasses; understanding how to write converters for domain-specific types is central to adapting the library
• Object Reference Preservation & $ref/$id — Json.NET supports preserving circular references and object identity across serialization using $ref and $id metadata; critical for serializing graphs with cycles
• JsonPath Query Syntax — SelectToken and related methods implement a JSONPath-like query language for navigating JToken trees; essential for extracting nested data without manual traversal
• BSON Serialization — Json.NET includes native BSON (Binary JSON) support for MongoDB and other databases; the parallel reader/writer architecture mirrors the JSON implementation

• dotnet/runtime — Contains System.Text.Json, Microsoft's built-in JSON serializer that competes with Json.NET on modern .NET; understanding its design helps contextualize Json.NET's advantages
• JamesNK/JsonSchema.NET — Companion library by the same author for JSON Schema validation and generation, often used alongside Json.NET for schema-driven development
• protobuf-net/protobuf-net — Alternative serialization framework for .NET focusing on Protocol Buffers; relevant for teams choosing between JSON and binary formats
• ServiceStack/ServiceStack.Text — Lightweight JSON serializer for .NET used in ServiceStack framework; simpler than Json.NET but with fewer features for comparison
• JamesNK/Newtonsoft.Json.Schema — Official JSON Schema validator built on Json.NET; the primary way users add schema validation to Json.NET workflows

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive JsonPath query documentation with escaped property examples

The Doc/Samples/JsonPath directory contains examples for regex queries, strict equals, and token selection, but lacks documentation for common edge cases like escaped property names, nested path traversal, and wildcard filtering. The existing QueryJsonSelectTokenEscaped.aml sample suggests this is a known pain point. A new .aml file documenting escaped properties, array slicing, and recursive descent would reduce Stack Overflow questions tagged json.net about JsonPath syntax.

• [ ] Review existing Doc/Samples/JsonPath/*.aml files to identify gaps
• [ ] Create Doc/Samples/JsonPath/EscapedPropertyNamesAndEdgeCases.aml with code examples
• [ ] Add documentation for bracket notation vs dot notation edge cases
• [ ] Include examples of wildcard and recursive descent operators (*, ..)
• [ ] Cross-reference from Doc/QueryingLINQtoJSON.aml main documentation

Add BSON serialization round-trip unit tests with edge cases

The Doc/Samples/Bson directory contains only 3 basic examples (Deserialize, DeserializeCollection, Serialize), but there are no evident comprehensive unit tests covering edge cases like null handling, circular references, date precision, and nested collections. Given BSON is a specialized format with specific type coercion rules, this is a high-risk area for bugs that contributors can meaningfully test.

• [ ] Locate the main test project directory (likely Src/Newtonsoft.Json.Tests)
• [ ] Create or extend Src/Newtonsoft.Json.Tests/Bson/BsonRoundTripTests.cs
• [ ] Add test cases for: nested objects, arrays, null values, DateTime precision, ObjectId handling, Binary data
• [ ] Add tests for deserializing corrupted or truncated BSON data
• [ ] Ensure tests cover round-trip consistency (serialize → deserialize → serialize)

Add GitHub Actions workflow for cross-platform test matrix (.NET Framework/Core/Standard)

While .github/workflows/codeql.yml exists for code analysis, there is no visible workflow file for running the test suite across multiple .NET platforms (.NET Framework, .NET Core, .NET Standard targets). Json.NET's multi-platform support is a key selling point, but the current CI setup (Azure Pipelines per README) is not visible in the GitHub workflows directory. Adding a GitHub Actions test matrix would improve visibility and allow faster CI feedback.

• [ ] Check Build/build.ps1 and Build/runbuild.ps1 to identify how tests are invoked
• [ ] Create .github/workflows/test-matrix.yml with jobs for net48, net6.0, net8.0, and netstandard2.0
• [ ] Include steps to restore, build, and run xunit/nunit tests (identify test runner from .csproj files)
• [ ] Add code coverage reporting (e.g., Codecov) to the workflow
• [ ] Configure workflow to run on push to main branches and PRs

• Add comprehensive XML documentation comments to underutilized converter classes in Src/Newtonsoft.Json/Converters/ that lack inline examples—helps both IDE IntelliSense and the Doc/Samples/Json generation process
• Create a new Doc/Samples/Linq example demonstrating conditional property serialization with ConditionalAttribute (referenced in Doc/ConditionalProperties.aml but no runnable sample in Samples/Linq/), bridging the gap between the concept and practical usage
• Write unit tests for edge cases in JsonPath queries (Doc/Samples/JsonPath/) such as escaped characters in property names and regex queries on null/missing tokens—currently the samples lack corresponding test coverage

Json.NET is a mature and widely-used JSON serialization library with generally good security practices. The primary security concerns relate to the inherent risks of deserialization of untrusted data (which is documented and manageable through proper configuration) and build pipeline integrity. No critical vulnerabilities were identified in the visible file structure. The codebase appears to follow standard .NET security practices. Recommendations focus on: (1) maintaining strict deserialization security patterns, (2) securing build scripts, (3) adding a security policy, and (4) properly managing build configurations. Regular dependency updates and security audits are essential for this widely-dependent library.

• Medium · Potential Deserialization Security Risk — Core serialization/deserialization components. Json.NET is a serialization library that handles untrusted JSON input. Deserialization of untrusted data can lead to arbitrary code execution if custom converters or type handlers are not properly validated. The library's flexibility with custom converters and object creation could be exploited if not carefully configured. Fix: Implement strict type validation, use TypeNameHandling.None by default, employ SerializationBinder for type validation, validate all custom JsonConverter implementations, and keep the library updated to the latest security patches.
• Medium · Build Script Security Configuration — Build/Sign-Package.ps1, Build/build.ps1, Build/runbuild.ps1, Build/runbuild.cmd. PowerShell scripts in the Build directory (Sign-Package.ps1, build.ps1, runbuild.ps1) may execute with elevated privileges. These scripts could be vulnerable to injection attacks or manipulation if build environment variables are not properly sanitized. Fix: Implement strict input validation in all build scripts, use Set-StrictMode in PowerShell scripts, avoid dynamic script generation, implement code signing verification, and restrict build script execution to trusted CI/CD pipelines only.
• Low · Missing Security Policy Documentation — Repository root. No visible SECURITY.md or security policy file in the repository root for reporting vulnerabilities responsibly. Fix: Create a SECURITY.md file with responsible disclosure guidelines and security contact information to encourage proper vulnerability reporting.
• Low · Build Configuration Exposure — Build/appsettings.json, Build/version.json. Build configuration files (Build/appsettings.json, Build/version.json) may contain sensitive information if not properly managed. These files could expose internal build details or version information. Fix: Review these configuration files to ensure no sensitive data is stored. Use environment variables for sensitive configuration and implement .gitignore rules to prevent accidental commits of sensitive build artifacts.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.