# json-path/jsonpath architecture

> Architecture diagram of the GitHub repository json-path/jsonpath, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/json-path/jsonpath
- Repository: https://github.com/json-path/jsonpath

## Overview

Jayway JsonPath is a Java library for querying and modifying JSON documents with JsonPath expressions, plus assertion and matcher APIs. The principal workflow is a caller providing JSON and a path, parsing the document into a context, compiling/evaluating the expression, then receiving a result or applying a mutation. The README documents path operators, filters, and functions; source excerpts show context caching, result mapping, and updates. Many implementation links are inferred only from the SOURCE INDEX, so unsampled links are omitted or marked unverified.

Main entry points: [`json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java`](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java) (Document Context), [`json-path/src/main/java/com/jayway/jsonpath/JsonPath.java`](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/JsonPath.java) (JsonPath API), [`json-path/src/main/java/com/jayway/jsonpath/internal/path`](https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/internal/path) (Path Evaluation), [`json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java`](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java) (Evaluation Context)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["Public APIs"]
  node_parse_api["Parse API<br/>[ParseContext.java]"]
  node_read_api["Read Context<br/>[ReadContext.java]"]
  node_write_api["Write Context<br/>[WriteContext.java]"]
  node_configuration["Configuration<br/>[Configuration.java]"]
  node_jsonpath_api["JsonPath API<br/>[JsonPath.java]"]
end

subgraph group_runtime["Query Runtime"]
  node_json_context["Document Context<br/>[JsonContext.java]"]
  node_parse_impl["Parse Context Impl"]
  node_path_compiler["Path Compiler<br/>[PathCompiler.java]"]
  node_filter_compiler["Filter Compiler"]
  node_path_tokens["Path Evaluation"]
  node_evaluation["Evaluation Context"]
  node_path_ref["Update Operations<br/>[PathRef.java]"]
  node_functions["Path Functions"]
  node_cache["Path Cache<br/>[CacheProvider.java]"]
end

subgraph group_providers["JSON Providers"]
  node_json_provider["JSON Providers"]
  node_mapping_provider["Mapping Providers"]
end

subgraph group_assertions["Assertions"]
  node_assert_api["JSON Assertions<br/>[JsonAssert.java]"]
  node_asserter["Asserter Impl"]
  node_matchers["Hamcrest Matchers"]
  node_json_matcher["JSON Matcher<br/>[IsJson.java]"]
  node_path_matchers["Path Matchers<br/>[WithJsonPath.java]"]
end

node_caller(("Library Caller"))

node_caller -->|"supplies JSON"| node_parse_api
node_caller -->|"requests paths"| node_read_api
node_caller -->|"requests edits"| node_write_api
node_parse_api -->|"delegates parsing"| node_parse_impl
node_parse_impl -->|"creates context"| node_json_context
node_read_api -.->|"implemented by"| node_json_context
node_write_api -.->|"implemented by"| node_json_context
node_json_context -->|"gets compiled paths"| node_cache
node_json_context -->|"compiles paths"| node_jsonpath_api
node_jsonpath_api -->|"evaluates expression"| node_evaluation
node_path_compiler -.->|"builds path"| node_path_tokens
node_filter_compiler -.->|"builds predicates"| node_path_tokens
node_path_tokens -.->|"evaluates tokens"| node_evaluation
node_evaluation -->|"records updates"| node_path_ref
node_evaluation -->|"accesses JSON model"| node_json_provider
node_json_context -->|"maps typed results"| node_mapping_provider
node_configuration -.->|"configures provider"| node_json_provider
node_configuration -.->|"configures mapping"| node_mapping_provider
node_path_tokens -.->|"applies functions"| node_functions
node_caller -->|"asserts JSON"| node_assert_api
node_assert_api -->|"creates asserter"| node_asserter
node_asserter -->|"evaluates assertions"| node_jsonpath_api
node_caller -->|"uses matchers"| node_matchers
node_matchers -->|"constructs matcher"| node_json_matcher
node_matchers -->|"constructs matcher"| node_path_matchers
node_json_matcher -->|"parses JSON"| node_jsonpath_api
node_path_matchers -->|"evaluates path"| node_jsonpath_api

click node_parse_api "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/ParseContext.java"
click node_read_api "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/ReadContext.java"
click node_write_api "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/WriteContext.java"
click node_configuration "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/Configuration.java"
click node_jsonpath_api "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/JsonPath.java"
click node_json_context "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java"
click node_parse_impl "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java"
click node_path_compiler "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/path/PathCompiler.java"
click node_filter_compiler "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java"
click node_path_tokens "https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/internal/path"
click node_evaluation "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java"
click node_path_ref "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java"
click node_functions "https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/internal/function"
click node_cache "https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/spi/cache/CacheProvider.java"
click node_json_provider "https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/spi/json"
click node_mapping_provider "https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/spi/mapper"
click node_assert_api "https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonassert/JsonAssert.java"
click node_asserter "https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonassert/impl/JsonAsserterImpl.java"
click node_matchers "https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonpath/matchers/JsonPathMatchers.java"
click node_json_matcher "https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonpath/matchers/IsJson.java"
click node_path_matchers "https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonpath/matchers/WithJsonPath.java"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_parse_api,node_read_api,node_write_api,node_configuration,node_jsonpath_api toneBlue
class node_json_context,node_parse_impl,node_path_compiler,node_filter_compiler,node_path_tokens,node_evaluation,node_path_ref,node_functions,node_cache toneAmber
class node_json_provider,node_mapping_provider toneMint
class node_assert_api,node_asserter,node_matchers,node_json_matcher,node_path_matchers toneRose
class node_caller toneIndigo
```

## Components

### Public APIs

- [Parse API](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/ParseContext.java): `json-path/src/main/java/com/jayway/jsonpath/ParseContext.java`
- [Read Context](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/ReadContext.java): `json-path/src/main/java/com/jayway/jsonpath/ReadContext.java`
- [Write Context](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/WriteContext.java): `json-path/src/main/java/com/jayway/jsonpath/WriteContext.java`
- [Configuration](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/Configuration.java): `json-path/src/main/java/com/jayway/jsonpath/Configuration.java`
- [JsonPath API](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/JsonPath.java): `json-path/src/main/java/com/jayway/jsonpath/JsonPath.java`

### Query Runtime

- [Document Context](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java): `json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java`
- [Parse Context Impl](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java): `json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java`
- [Path Compiler](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/path/PathCompiler.java): `json-path/src/main/java/com/jayway/jsonpath/internal/path/PathCompiler.java`
- [Filter Compiler](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java): `json-path/src/main/java/com/jayway/jsonpath/internal/filter/FilterCompiler.java`
- [Path Evaluation](https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/internal/path): `json-path/src/main/java/com/jayway/jsonpath/internal/path`
- [Evaluation Context](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java): `json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java`
- [Update Operations](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java): `json-path/src/main/java/com/jayway/jsonpath/internal/PathRef.java`
- [Path Functions](https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/internal/function): `json-path/src/main/java/com/jayway/jsonpath/internal/function`
- [Path Cache](https://github.com/json-path/jsonpath/blob/master/json-path/src/main/java/com/jayway/jsonpath/spi/cache/CacheProvider.java): `json-path/src/main/java/com/jayway/jsonpath/spi/cache/CacheProvider.java`

### JSON Providers

- [JSON Providers](https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/spi/json): `json-path/src/main/java/com/jayway/jsonpath/spi/json`
- [Mapping Providers](https://github.com/json-path/jsonpath/tree/master/json-path/src/main/java/com/jayway/jsonpath/spi/mapper): `json-path/src/main/java/com/jayway/jsonpath/spi/mapper`

### Assertions

- [JSON Assertions](https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonassert/JsonAssert.java): `json-path-assert/src/main/java/com/jayway/jsonassert/JsonAssert.java`
- [Asserter Impl](https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonassert/impl/JsonAsserterImpl.java): `json-path-assert/src/main/java/com/jayway/jsonassert/impl/JsonAsserterImpl.java`
- [Hamcrest Matchers](https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonpath/matchers/JsonPathMatchers.java): `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/JsonPathMatchers.java`
- [JSON Matcher](https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonpath/matchers/IsJson.java): `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/IsJson.java`
- [Path Matchers](https://github.com/json-path/jsonpath/blob/master/json-path-assert/src/main/java/com/jayway/jsonpath/matchers/WithJsonPath.java): `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/WithJsonPath.java`

### Other components

- **Library Caller**

## Connections

- Library Caller → Parse API: supplies JSON (evidence: `README.md`)
- Library Caller → Read Context: requests paths (evidence: `README.md`)
- Library Caller → Write Context: requests edits (evidence: `json-path/src/main/java/com/jayway/jsonpath/WriteContext.java`)
- Parse API → Parse Context Impl: delegates parsing (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java`)
- Parse Context Impl → Document Context: creates context (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/ParseContextImpl.java`)
- Read Context → Document Context: implemented by (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java`)
- Write Context → Document Context: implemented by
- Document Context → Path Cache: gets compiled paths (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java`)
- Document Context → JsonPath API: compiles paths (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java`)
- JsonPath API → Evaluation Context: evaluates expression (evidence: `json-path/src/main/java/com/jayway/jsonpath/JsonPath.java`)
- Path Compiler → Path Evaluation: builds path
- Filter Compiler → Path Evaluation: builds predicates
- Path Evaluation → Evaluation Context: evaluates tokens (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java`)
- Evaluation Context → Update Operations: records updates (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java`)
- Evaluation Context → JSON Providers: accesses JSON model (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/path/EvaluationContextImpl.java`)
- Document Context → Mapping Providers: maps typed results (evidence: `json-path/src/main/java/com/jayway/jsonpath/internal/JsonContext.java`)
- Configuration → JSON Providers: configures provider (evidence: `json-path/src/main/java/com/jayway/jsonpath/Configuration.java`)
- Configuration → Mapping Providers: configures mapping (evidence: `json-path/src/main/java/com/jayway/jsonpath/Configuration.java`)
- Path Evaluation → Path Functions: applies functions
- Library Caller → JSON Assertions: asserts JSON (evidence: `json-path-assert/src/main/java/com/jayway/jsonassert/JsonAssert.java`)
- JSON Assertions → Asserter Impl: creates asserter (evidence: `json-path-assert/src/main/java/com/jayway/jsonassert/JsonAssert.java`)
- Asserter Impl → JsonPath API: evaluates assertions (evidence: `json-path-assert/src/main/java/com/jayway/jsonassert/impl/JsonAsserterImpl.java`)
- Library Caller → Hamcrest Matchers: uses matchers (evidence: `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/JsonPathMatchers.java`)
- Hamcrest Matchers → JSON Matcher: constructs matcher (evidence: `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/JsonPathMatchers.java`)
- Hamcrest Matchers → Path Matchers: constructs matcher (evidence: `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/JsonPathMatchers.java`)
- JSON Matcher → JsonPath API: parses JSON (evidence: `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/IsJson.java`)
- Path Matchers → JsonPath API: evaluates path (evidence: `json-path-assert/src/main/java/com/jayway/jsonpath/matchers/WithJsonPath.java`)
