From 918f072f4c0832464860eb188ad19cbfdde6e21e Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 24 Mar 2021 10:18:34 +0100 Subject: [PATCH 01/11] Set up for I-D-template --- .gitmodules | 3 + lib | 1 + rfc2629-other.ent | 61 +++++++++ rfc2629-xhtml.ent | 165 ++++++++++++++++++++++++ rfc2629.dtd | 312 ++++++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 542 insertions(+) create mode 100644 .gitmodules create mode 160000 lib create mode 100755 rfc2629-other.ent create mode 100755 rfc2629-xhtml.ent create mode 100644 rfc2629.dtd diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 00000000..b20fa617 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "lib"] + path = lib + url = https://github.com/martinthomson/i-d-template diff --git a/lib b/lib new file mode 160000 index 00000000..1ab2dcb3 --- /dev/null +++ b/lib @@ -0,0 +1 @@ +Subproject commit 1ab2dcb370171438dea8e120773ce67533d74547 diff --git a/rfc2629-other.ent b/rfc2629-other.ent new file mode 100755 index 00000000..0da80b72 --- /dev/null +++ b/rfc2629-other.ent @@ -0,0 +1,61 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/rfc2629-xhtml.ent b/rfc2629-xhtml.ent new file mode 100755 index 00000000..3d4a07dd --- /dev/null +++ b/rfc2629-xhtml.ent @@ -0,0 +1,165 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/rfc2629.dtd b/rfc2629.dtd new file mode 100644 index 00000000..11334ae7 --- /dev/null +++ b/rfc2629.dtd @@ -0,0 +1,312 @@ + + + + + + + + + + + + + +%rfc2629-xhtml; + + +%rfc2629-other; + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + From 362ce19af810a0d813b52ad11c9c4703fda22450 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 24 Mar 2021 10:19:12 +0100 Subject: [PATCH 02/11] Setup repository for draft-ietf-jsonpath-base using https://github.com/martinthomson/i-d-template --- .circleci/config.yml | 100 ++++++++++++++++++++++++++++++++++ .github/CODEOWNERS | 2 + .github/workflows/archive.yml | 32 +++++++++++ .github/workflows/ghpages.yml | 58 ++++++++++++++++++++ .github/workflows/publish.yml | 49 +++++++++++++++++ .gitignore | 17 +++++- .note.xml | 7 +++ CONTRIBUTING.md | 31 +++++++++++ LICENSE.md | 4 ++ Makefile | 11 ++++ README.md | 96 +++++--------------------------- 11 files changed, 324 insertions(+), 83 deletions(-) create mode 100644 .circleci/config.yml create mode 100644 .github/CODEOWNERS create mode 100644 .github/workflows/archive.yml create mode 100644 .github/workflows/ghpages.yml create mode 100644 .github/workflows/publish.yml create mode 100644 .note.xml create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE.md create mode 100644 Makefile diff --git a/.circleci/config.yml b/.circleci/config.yml new file mode 100644 index 00000000..192e849d --- /dev/null +++ b/.circleci/config.yml @@ -0,0 +1,100 @@ +version: 2 +jobs: + build: + docker: + - image: martinthomson/i-d-template:latest + working_directory: ~/draft + + steps: + - run: + name: "Print Configuration" + command: | + xml2rfc --version + gem list -q kramdown-rfc2629 + echo -n 'mmark '; mmark --version + + - restore_cache: + name: "Restoring cache - Git" + keys: + - v2-cache-git-{{ .Branch }}-{{ .Revision }} + - v2-cache-git-{{ .Branch }} + - v2-cache-git- + + - restore_cache: + name: "Restoring cache - References" + keys: + - v1-cache-references-{{ epoch }} + - v1-cache-references- + + # Workaround for https://discuss.circleci.com/t/22437 + - run: + name: Tag Checkout + command: | + if [ -n "$CIRCLE_TAG" ] && [ -d .git ]; then + remote=$(echo "$CIRCLE_REPOSITORY_URL" | \ + sed -e 's,/^git.github.com:,https://github.com/,') + git fetch -f "$remote" "refs/tags/$CIRCLE_TAG:refs/tags/$CIRCLE_TAG" || \ + (echo 'Removing .git cache for tag build'; rm -rf .git) + fi + + - checkout + + # Build txt and html versions of drafts + - run: + name: "Build Drafts" + command: "make 'CLONE_ARGS=--reference ~/git-reference'" + + # Update editor's copy on gh-pages + - run: + name: "Update GitHub Pages" + command: | + if [ "${CIRCLE_TAG#draft-}" == "$CIRCLE_TAG" ]; then + make gh-pages + fi + + # For tagged builds, upload to the datatracker. + - deploy: + name: "Upload to Datatracker" + command: | + if [ "${CIRCLE_TAG#draft-}" != "$CIRCLE_TAG" ]; then + make upload + fi + + # Archive GitHub Issues + - run: + name: "Archive GitHub Issues" + command: "make archive || make archive DISABLE_ARCHIVE_FETCH=true && make gh-archive" + + # Create and store artifacts + - run: + name: "Create Artifacts" + command: "make artifacts CI_ARTIFACTS=/tmp/artifacts" + + - store_artifacts: + path: /tmp/artifacts + + - run: + name: "Prepare for Caching" + command: "git reflog expire --expire=now --all && git gc --prune=now" + + - save_cache: + name: "Saving Cache - Git" + key: v2-cache-git-{{ .Branch }}-{{ .Revision }} + paths: + - ~/draft/.git + + - save_cache: + name: "Saving Cache - Drafts" + key: v1-cache-references-{{ epoch }} + paths: + - ~/.cache/xml2rfc + + +workflows: + version: 2 + build: + jobs: + - build: + filters: + tags: + only: /.*?/ diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..66ae27a8 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,2 @@ +# Automatically generated CODEOWNERS file. +draft-ietf-jsonpath-base.md glyn.normington@gmail.comesurov.tsp@gmail.commmikulicic@gmail.comstefan.goessner@fh-dortmund.de diff --git a/.github/workflows/archive.yml b/.github/workflows/archive.yml new file mode 100644 index 00000000..fb0e0d1d --- /dev/null +++ b/.github/workflows/archive.yml @@ -0,0 +1,32 @@ +name: "Archive Issues and Pull Requests" + +on: + schedule: + - cron: '0 0 * * 0,2,4' + repository_dispatch: + types: [archive] + +jobs: + build: + name: "Archive Issues and Pull Requests" + runs-on: ubuntu-latest + steps: + - name: "Checkout" + uses: actions/checkout@v2 + + - name: "Update Archive" + uses: martinthomson/i-d-template@v1 + with: + make: archive + token: ${{ secrets.GITHUB_TOKEN }} + + - name: "Update GitHub Pages" + uses: martinthomson/i-d-template@v1 + with: + make: gh-archive + token: ${{ secrets.GITHUB_TOKEN }} + + - name: "Save Archive" + uses: actions/upload-artifact@v2 + with: + path: archive.json diff --git a/.github/workflows/ghpages.yml b/.github/workflows/ghpages.yml new file mode 100644 index 00000000..ddd6e1a0 --- /dev/null +++ b/.github/workflows/ghpages.yml @@ -0,0 +1,58 @@ +name: "Update Editor's Copy" + +on: + push: + paths-ignore: + - README.md + - CONTRIBUTING.md + - LICENSE.md + - .gitignore + pull_request: + paths-ignore: + - README.md + - CONTRIBUTING.md + - LICENSE.md + - .gitignore + +jobs: + build: + name: "Update Editor's Copy" + runs-on: ubuntu-latest + steps: + - name: "Checkout" + uses: actions/checkout@v2 + + - name: "Cache Setup" + id: cache-setup + run: | + mkdir -p "$HOME"/.cache/xml2rfc + echo "::set-output name=path::$HOME/.cache/xml2rfc" + date -u "+::set-output name=date::%FT%T" + + - name: "Cache References" + uses: actions/cache@v2 + with: + path: | + ${{ steps.cache-setup.outputs.path }} + .targets.mk + key: refcache-${{ steps.cache-setup.outputs.date }} + restore-keys: | + refcache-${{ steps.cache-setup.outputs.date }} + refcache- + + - name: "Build Drafts" + uses: martinthomson/i-d-template@v1 + + - name: "Update GitHub Pages" + uses: martinthomson/i-d-template@v1 + if: ${{ github.event_name == 'push' }} + with: + make: gh-pages + token: ${{ secrets.GITHUB_TOKEN }} + + - name: "Archive Built Drafts" + uses: actions/upload-artifact@v2 + with: + path: | + draft-*.html + draft-*.txt diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml new file mode 100644 index 00000000..f9dbcabb --- /dev/null +++ b/.github/workflows/publish.yml @@ -0,0 +1,49 @@ +name: "Publish New Draft Version" + +on: + push: + tags: + - "draft-*" + +jobs: + build: + name: "Publish New Draft Version" + runs-on: ubuntu-latest + steps: + - name: "Checkout" + uses: actions/checkout@v2 + + # See https://github.com/actions/checkout/issues/290 + - name: "Get Tag Annotations" + run: git fetch -f origin ${{ github.ref }}:${{ github.ref }} + + - name: "Cache Setup" + id: cache-setup + run: | + mkdir -p "$HOME"/.cache/xml2rfc + echo "::set-output name=path::$HOME/.cache/xml2rfc" + date -u "+::set-output name=date::%FT%T" + + - name: "Cache References" + uses: actions/cache@v2 + with: + path: | + ${{ steps.cache-setup.outputs.path }} + .targets.mk + key: refcache-${{ steps.date.outputs.date }} + restore-keys: | + refcache-${{ steps.date.outputs.date }} + refcache- + + - name: "Build Drafts" + uses: martinthomson/i-d-template@v1 + + - name: "Upload to Datatracker" + uses: martinthomson/i-d-template@v1 + with: + make: upload + + - name: "Archive Submitted Drafts" + uses: actions/upload-artifact@v2 + with: + path: "draft-*-[0-9][0-9].xml" diff --git a/.gitignore b/.gitignore index 4bc92383..b6657300 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,16 @@ -.refcache/ \ No newline at end of file +*.html +*.pdf +*.redxml +*.swp +*.txt +*.upload +*~ +.refcache +.tags +.targets.mk +/*-[0-9][0-9].xml +archive.json +report.xml +venv/ +lib +draft-ietf-jsonpath-base.xml diff --git a/.note.xml b/.note.xml new file mode 100644 index 00000000..26803a4a --- /dev/null +++ b/.note.xml @@ -0,0 +1,7 @@ + +Discussion of this document takes place on the + JSON Path Working Group mailing list (jsonpath@ietf.org), + which is archived at . +Source for this draft and an issue tracker can be found at + . + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..0201e9ef --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,31 @@ +# Contributing + +This repository relates to activities in the Internet Engineering Task Force +([IETF](https://www.ietf.org/)). All material in this repository is considered +Contributions to the IETF Standards Process, as defined in the intellectual +property policies of IETF currently designated as +[BCP 78](https://www.rfc-editor.org/info/bcp78), +[BCP 79](https://www.rfc-editor.org/info/bcp79) and the +[IETF Trust Legal Provisions (TLP) Relating to IETF Documents](http://trustee.ietf.org/trust-legal-provisions.html). + +Any edit, commit, pull request, issue, comment or other change made to this +repository constitutes Contributions to the IETF Standards Process +(https://www.ietf.org/). + +You agree to comply with all applicable IETF policies and procedures, including, +BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being +subject to a Simplified BSD License) in Contributions. + + +## Other Resources + +Discussion of this work occurs on the +[jsonpath working group mailing list](https://mailarchive.ietf.org/arch/browse/jsonpath/) +([subscribe](https://www.ietf.org/mailman/listinfo/jsonpath)). In addition to +contributions in GitHub, you are encouraged to participate in discussions there. + +**Note**: Some working groups adopt a policy whereby substantive discussion of +technical issues needs to occur on the mailing list. + +You might also like to familiarize yourself with other +[working group documents](https://datatracker.ietf.org/wg/jsonpath/documents/). diff --git a/LICENSE.md b/LICENSE.md new file mode 100644 index 00000000..be523916 --- /dev/null +++ b/LICENSE.md @@ -0,0 +1,4 @@ +# License + +See the +[guidelines for contributions](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/blob/main/CONTRIBUTING.md). diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..de46d564 --- /dev/null +++ b/Makefile @@ -0,0 +1,11 @@ +LIBDIR := lib +include $(LIBDIR)/main.mk + +$(LIBDIR)/main.mk: +ifneq (,$(shell grep "path *= *$(LIBDIR)" .gitmodules 2>/dev/null)) + git submodule sync + git submodule update $(CLONE_ARGS) --init +else + git clone -q --depth 10 $(CLONE_ARGS) \ + -b main https://github.com/martinthomson/i-d-template $(LIBDIR) +endif diff --git a/README.md b/README.md index d436035e..a0d856fa 100644 --- a/README.md +++ b/README.md @@ -1,92 +1,24 @@ -# JSONPath Internet Draft Development +# JavaScript Object Notation (JSON) Path -This repository is for the development of an Internet Draft for JSONPath. The draft is currently a work in progress. +This is the working area for the IETF [JSONPATH Working Group](https://datatracker.ietf.org/wg/jsonpath/documents/) Internet-Draft, "JavaScript Object Notation (JSON) Path". -See the latest rendered version of the draft [here](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/). +* [Editor's Copy](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/#go.draft-ietf-jsonpath-base.html) +* [Working Group Draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base) +* [Compare Editor's Copy to Working Group Draft](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/#go.draft-ietf-jsonpath-base.diff) -Christoph Burgmer's [JSONPath Comparison project](https://github.com/cburgmer/json-path-comparison) -publishes a [comparison](https://cburgmer.github.io/json-path-comparison/) of many existing -implementations of JSONPath, calculates a consensus on various features, and proposes at least one -implementation which will inform the Internet Draft. +## Building the Draft -## Community +Formatted text and HTML versions of the draft can be built using `make`. -All official discussion is on the [jsonpath@ietf.org mailing list](https://www.ietf.org/mailman/listinfo/jsonpath). -See the [archive](https://mailarchive.ietf.org/arch/browse/jsonpath/) for previous posts. - -## License - -See the draft for the copyright which is repeated in [LICENSE](./LICENSE). - -## Authoring - -The source of the Internet Draft is in markdown and corresponding `.xml`, `.txt`, and `.html` files are generated and checked in. - -So that the HTML version can be viewed via github pages, it is copied to `docs/index.html`. - -See [RFC 7991](https://tools.ietf.org/html/rfc7991) for rfc XML syntax information. - -The XML document was created from this [template](https://tools.ietf.org/tools/templates/draft-davies-template-bare-07.xml). - -In the markdown file, the convention is to start a new line when starting a new sentence. - -### Install [kramdown-rfc2629](https://github.com/cabo/kramdown-rfc2629) -``` -gem install kramdown-rfc2629 -``` -You may need to prefix the above command with `sudo` if it doesn't have sufficient permissions to complete the installation. - -### Install [xml2rfc](https://xml2rfc.tools.ietf.org/): -``` -pip3 install xml2rfc --user -``` -This will place the executable in `~/.local/bin` - -### Install [xmlstarlet](http://xmlstar.sourceforge.net/) -On macOS, issue: +```sh +$ make ``` -brew install xmlstarlet -``` -On Linux, issue something like: -``` -apt-get install -y xmlstarlet -``` - -### Install `aex` and `bap` -`aex` is an ABNF extractor and `bap` an ABNF syntax checker. +This requires that you have the necessary software installed. See +[the instructions](https://github.com/martinthomson/i-d-template/blob/master/doc/SETUP.md). -1. Clone https://github.com/fenner/bap -2. In the cloned directory execute - 1. `./configure` - 2. `make` -3. `aex` and `bap` binaries should now exist in the directory -4. Add them to your path -### Re-generate files - - This will: - - re-generate the `.txt` and `.html` files - - check the ABNF syntax - - copy the HTML file for use by github pages: - -``` -xml2rfc ./draft-ietf-jsonpath-base.xml --text --html && aex draft-ietf-jsonpath-base.txt | bap -S path -q && cp draft-ietf-jsonpath-base.html docs/index.html -``` +## Contributing -A script [gen.sh](scripts/gen.sh) is provided for convenience. You can also use [docker-gen.sh](scripts/docker-gen.sh) -version that installs and runs all utilities within a Docker container. - -### Conventions - -Basic conventions around source files formatting are captured in the `.editorconfig` file. -Many editors support that file natively. Others (such as VS code) require a plugin, see https://editorconfig.org/. - -### Pull Requests - -For ease of reading pull requests, push the PR branch to `master` of your fork. For instance, if your -github username/organisation is `xxx`, then rendered HTML will be available at: - -``` -https://xxx.github.io/draft-ietf-jsonpath-jsonpath/ -``` +See the +[guidelines for contributions](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/blob/main/CONTRIBUTING.md). From d081b82ea8cd21e1cc743e2f6349a8289abbdd73 Mon Sep 17 00:00:00 2001 From: Glyn Normington Date: Wed, 24 Mar 2021 10:10:49 +0000 Subject: [PATCH 03/11] Merge README information Merge information from the previous README. --- CONTRIBUTING.md | 6 ++++++ README.md | 16 ++++++++++++++++ 2 files changed, 22 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0201e9ef..ec4642b5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -16,6 +16,12 @@ You agree to comply with all applicable IETF policies and procedures, including, BCP 78, 79, the TLP, and the TLP rules regarding code components (e.g. being subject to a Simplified BSD License) in Contributions. +## Conventions + +Basic conventions around source files formatting are captured in the `.editorconfig` file. +Many editors support that file natively. Others (such as VS code) require a plugin, see https://editorconfig.org/. + +In the markdown file, the convention is to start a new line when starting a new sentence. ## Other Resources diff --git a/README.md b/README.md index a0d856fa..836b5146 100644 --- a/README.md +++ b/README.md @@ -17,8 +17,24 @@ $ make This requires that you have the necessary software installed. See [the instructions](https://github.com/martinthomson/i-d-template/blob/master/doc/SETUP.md). +## Community + +All official discussion is in [issues](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/issues), +[pull requests](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/pulls), and the [jsonpath@ietf.org mailing list](https://www.ietf.org/mailman/listinfo/jsonpath). +See the [archive](https://mailarchive.ietf.org/arch/browse/jsonpath/) for previous posts. + +## License + +See the draft for the copyright which is repeated in [LICENSE](./LICENSE). ## Contributing See the [guidelines for contributions](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/blob/main/CONTRIBUTING.md). + +## Comparing JSONPath Implementations + +Christoph Burgmer's [JSONPath Comparison project](https://github.com/cburgmer/json-path-comparison) +publishes a [comparison](https://cburgmer.github.io/json-path-comparison/) of many existing +implementations of JSONPath, calculates a consensus on various features, and proposes at least one +implementation which will inform the Internet Draft. From ec03574fcaf19ea50bdef084b64822e86d2799f1 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 24 Mar 2021 11:24:59 +0100 Subject: [PATCH 04/11] Update xpath script to "sourcecode" (was "artwork") --- scripts/gen.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/gen.sh b/scripts/gen.sh index d15a281e..46c1f975 100755 --- a/scripts/gen.sh +++ b/scripts/gen.sh @@ -8,7 +8,7 @@ readonly script_dir="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" cd "$script_dir/.." kdrfc -h3 draft-ietf-jsonpath-base.md && \ -xmlstarlet sel -T -t -v '//artwork[@type="abnf"]' ./draft-ietf-jsonpath-base.xml 2>/dev/null \ +xmlstarlet sel -T -t -v '//sourcecode[@type="abnf"]' ./draft-ietf-jsonpath-base.xml 2>/dev/null \ | aex \ | bap -S path -q && cp draft-ietf-jsonpath-base.html docs/index.html ) From 49d7d2c6b28a8f84f8e784d2b4bcbf6af4274ad6 Mon Sep 17 00:00:00 2001 From: Glyn Normington Date: Wed, 24 Mar 2021 10:27:46 +0000 Subject: [PATCH 05/11] Avoid copying HTML to docs directory --- docs/index.html | 2614 ----------------------------------------------- scripts/gen.sh | 2 +- 2 files changed, 1 insertion(+), 2615 deletions(-) delete mode 100644 docs/index.html diff --git a/docs/index.html b/docs/index.html deleted file mode 100644 index 8de21526..00000000 --- a/docs/index.html +++ /dev/null @@ -1,2614 +0,0 @@ - - - - - - -JavaScript Object Notation (JSON) Path - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Internet-DraftJSONPathMarch 2021
Normington, et al.Expires 4 September 2021[Page]
-
-
-
-
Workgroup:
-
JSONPath WG
-
Internet-Draft:
-
draft-ietf-jsonpath-base-latest
-
Published:
-
- -
-
Intended Status:
-
Standards Track
-
Expires:
-
-
Authors:
-
-
-
G. Normington, Ed. -
-
VMware, Inc.
-
-
-
E. Surov, Ed. -
-
TheSoul Publishing Ltd.
-
-
-
M. Mikulicic, Ed. -
-
InfluxData, Inc.
-
-
-
S. Gössner
-
Fachhochschule Dortmund
-
-
-
-
-

JavaScript Object Notation (JSON) Path

-
-

Abstract

-

JSONPath defines a string syntax for identifying values -within a JavaScript Object Notation (JSON) document.

-
-
-

-Contributing -

-

This document picks up the popular JSONPath specification dated -2007-02-21 and provides a normative definition for it. -In its current state, it is a strawman document showing what needs to -be covered.

-

Comments and issues may be directed to this document's -github repository.

-
-
-
-

-Status of This Memo -

-

- This Internet-Draft is submitted in full conformance with the - provisions of BCP 78 and BCP 79.

-

- Internet-Drafts are working documents of the Internet Engineering Task - Force (IETF). Note that other groups may also distribute working - documents as Internet-Drafts. The list of current Internet-Drafts is - at https://datatracker.ietf.org/drafts/current/.

-

- Internet-Drafts are draft documents valid for a maximum of six months - and may be updated, replaced, or obsoleted by other documents at any - time. It is inappropriate to use Internet-Drafts as reference - material or to cite them other than as "work in progress."

-

- This Internet-Draft will expire on 4 September 2021.

-
-
- - -
-
-

-1. Introduction -

-

This document picks up the popular JSONPath specification dated -2007-02-21 [JSONPath-orig] and provides a normative definition for it. -In its current state, it is a strawman document showing what needs to -be covered.

-

JSON is defined by [RFC8259].

-

JSONPath is not intended as a replacement, but as a more powerful -companion, to JSON Pointer [RFC6901]. [insert reference to section -where the relationship is detailed. The purposes of the two syntaxes -are different. Pointer is for isolating a single location within a -document. Path is a query syntax that can also be used to pull multiple locations.]

-
-
-

-1.1. Terminology -

-

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL -NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", -"MAY", and "OPTIONAL" in this document are to be interpreted as -described in BCP 14 [RFC2119] [RFC8174] when, and only when, they -appear in all capitals, as shown here.

-

The grammatical rules in this document are to be interpreted as ABNF, -as described in [RFC5234]. -ABNF terminal values in this document define Unicode code points rather than -their UTF-8 encoding. -For example, the Unicode PLACE OF INTEREST SIGN (U+2318) would be defined -in ABNF as %x2318.

-

The terminology of [RFC8259] applies.

-
-
Data Item:
-
- A structure complying to the generic data model of JSON, i.e., -composed of containers, namely JSON objects and arrays, and -of atomic data, namely null, true, false, numbers, and text strings. -Also called a JSON value. -
-
-
Object:
-
- A JSON object as defined in [RFC8259]. -Never used in its generic sense, e.g., for programming language objects. -
-
-
Member:
-
- A name/value pair in a JSON object. (Not itself a JSON value.) -
-
-
Name:
-
- The name in a name/value pair constituting a member. (Also known as -"key", "tag", or "label".) -
-
-
Element:
-
- An item in an array. (Also used with a distinct meaning in XML -context for XML elements.) -
-
-
Query:
-
- Short name for JSONPath expression. -
-
-
Argument:
-
- Short name for the JSON data item a JSONPath expression is applied to. -
-
-
Output Path:
-
- A simple form of JSONPath expression that identifies a Position by -providing a query that results in exactly that position. Similar -to, but syntactically different from, a JSON Pointer [RFC6901]. -
-
-
Position:
-
- A JSON data item identical to or nested within the JSON data item to -which the query is applied to, expressed either by the value of that -data item or by providing a Normalized Path Expression as a JSONPath Output Path. -
-
-
Normalized Path Expression:
-
- A query in a normalized form that identifies exactly one Position in -an Argument; see Section 1.3. -
-
-
-
-
-
-
-

-1.2. Inspired by XPath -

-

A frequently emphasized advantage of XML is the availability of -powerful tools to analyse, transform and selectively extract data from -XML documents. -[XPath] is one of these tools.

-

In 2007, the need for something solving the same class of problems for -the emerging JSON community became apparent, specifically for:

-
    -
  • Finding data interactively and extracting them out of [RFC8259] -data items without special scripting. -
    • -
  • Specifying the relevant parts of the JSON data in a request by a -client, so the server can reduce the amount of data in its response, -minimizing bandwidth usage. -
    • -
-

So what does such a tool look like for JSON? -When defining a JSONPath, how should expressions look?

-

The XPath expression

-
-
-/store/book[1]/title
-
-
-

looks like

-
-
-x.store.book[0].title
-
-
-

or

-
-
-x['store']['book'][0]['title']
-
-
-

in popular programming languages such as JavaScript, Python and PHP, -with a variable x holding the JSON data item. Here we observe that -such languages already have a fundamentally XPath-like feature built -in.

-

The JSONPath tool in question should:

-
    -
  • be naturally based on those language characteristics. -
    • -
  • cover only essential parts of XPath 1.0. -
    • -
  • be lightweight in code size and memory consumption. -
    • -
  • be runtime efficient. -
    • -
-
-
-
-
-

-1.3. Overview of JSONPath Expressions -

-

JSONPath expressions always apply to a JSON data item in the same way -as XPath expressions are used in combination with an XML document. -Since a JSON data item is anonymous, JSONPath uses the abstract name $ to -refer to the top level data item of the argument.

-

JSONPath expressions can use the dot-notation

-
-
-$.store.book[0].title
-
-
-

or the bracket-notation

-
-
-$['store']['book'][0]['title']
-
-
-

for paths input to a JSONPath processor. -[1] -Where a JSONPath processor uses JSONPath expressions as output paths, -these will always be converted to normalized JSONPath expressions -which employ the more general bracket-notation. -[2] -Bracket notation is more general than dot notation and can serve as a -canonical form when a JSONPath processor uses JSONPath expressions as -output paths.

-

JSONPath allows the wildcard symbol * for member names and array -indices. It borrows the descendant operator .. from [E4X] and -the array slice syntax proposal [start:end:step] [SLICE] from ECMASCRIPT 4.

-

JSONPath was originally designed to employ an underlying scripting -language for computing expressions. The present specification -defines a simple expression language that is independent from any -scripting language in use on the platform.

-

JSONPath can use expressions, written in parentheses: (<expr>), as -an alternative to explicit names or indices as in:

-
-
-$.store.book[(@.length-1)].title
-
-
-

The symbol @ is used for the current item. -Filter expressions are supported via the syntax ?(<boolean expr>) as in

-
-
-$.store.book[?(@.price < 10)].title
-
-
-

Here is a complete overview and a side by side comparison of the JSONPath syntax elements with their XPath counterparts.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Table 1: -Overview over JSONPath, comparing to XPath -
XPathJSONPathDescription
- / - - $ -the root element/item
- . - - @ -the current element/item
- / - - . or [] -child operator
- .. -n/aparent operator
- // - - .. -nested descendants (JSONPath borrows this syntax from E4X)
- * - - * -wildcard: All elements/items regardless of their names
- @ -n/aattribute access: JSON data items do not have attributes
- [] - - [] -subscript operator: XPath uses it to iterate over element collections and for predicates; native array indexing as in JavaScript here
- | - - [,] -Union operator in XPath (results in a combination of node sets); JSONPath allows alternate names or array indices as a set
n/a - [start:end:step] -array slice operator borrowed from ES4
- [] - - ?() -applies a filter (script) expression
n/a - () -expression engine
- () -n/agrouping in Xpath
-
-

XPath has a lot more to offer (location paths in unabbreviated syntax, -operators and functions) than listed here. Moreover there is a -significant difference how the subscript operator works in Xpath and -JSONPath:

-
    -
  • Square brackets in XPath expressions always operate on the node set resulting from the previous path fragment. Indices always start at 1. -
    • -
  • With JSONPath, square brackets operate on the object or array -addressed by the previous path fragment. Array indices always start at 0. -
    • -
-
-
-
-
-
-
-

-2. JSONPath Examples -

-

This section provides some more examples for JSONPath expressions. -The examples are based on a simple JSON data item patterned after a -typical XML example representing a bookstore (that also has bicycles):

-
-
-
-{ "store": {
-    "book": [
-      { "category": "reference",
-        "author": "Nigel Rees",
-        "title": "Sayings of the Century",
-        "price": 8.95
-      },
-      { "category": "fiction",
-        "author": "Evelyn Waugh",
-        "title": "Sword of Honour",
-        "price": 12.99
-      },
-      { "category": "fiction",
-        "author": "Herman Melville",
-        "title": "Moby Dick",
-        "isbn": "0-553-21311-3",
-        "price": 8.99
-      },
-      { "category": "fiction",
-        "author": "J. R. R. Tolkien",
-        "title": "The Lord of the Rings",
-        "isbn": "0-395-19395-8",
-        "price": 22.99
-      }
-    ],
-    "bicycle": {
-      "color": "red",
-      "price": 19.95
-    }
-  }
-}
-
-
-
Figure 1: -Example JSON data item -
-

The examples in Table 2 use the expression mechanism to obtain -the number of items in an array, to test for the presence of a -member in a object, and to perform numeric comparisons of member values with a -constant.

-
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Table 2: -Example JSONPath expressions applied to the example JSON data item -
XPathJSONPathResult
- /store/book/author - - $.store.book[*].author -the authors of all books in the store
- //author - - $..author -all authors
- /store/* - - $.store.* -all things in store, which are some books and a red bicycle
- /store//price - - $.store..price -the prices of everything in the store
- //book[3] - - $..book[2] -the third book
- //book[last()] - - $..book[(@.length-1)]
$..book[-1] -		the last book in order
- //book[position()<3] - - $..book[0,1]
$..book[:2] -		the first two books
- //book[isbn] - - $..book[?(@.isbn)] -filter all books with isbn number
- //book[price<10] - - $..book[?(@.price<10)] -filter all books cheaper than 10
- //* - - $..* -all elements in XML document; all members of JSON data item
-
-
-
-
-
-

-3. JSONPath Syntax and Semantics -

-
-
-

-3.1. Overview -

-

A JSONPath is a string which selects zero or more nodes of a piece of JSON. -A valid JSONPath conforms to the ABNF syntax defined by this document.

-

A JSONPath MUST be encoded using UTF-8. To parse a JSONPath according to -the grammar in this document, its UTF-8 form SHOULD first be decoded into -Unicode code points as described -in [RFC3629].

-
-
-
-
-

-3.2. Terminology -

-

A JSON value is logically a tree of nodes.

-

Each node holds a JSON value (as defined by [RFC8259]) of one of the -types object, array, number, string, or one of the literals true, -false, or null. -The type of the JSON value held by a node is -sometimes referred to as the type of the node.

-
-
-
-
-

-3.3. Implementation -

-

An implementation of this specification, from now on referred to simply as -"an implementation", SHOULD takes two inputs, a JSONPath and a JSON value, -and produce -a possibly empty list of nodes of the JSON value which are selected by -the JSONPath or an error (but not both).

-

If no node is selected and no error has occurred, an implementation MUST -return an empty list of nodes.

-

Syntax errors in the JSONPath SHOULD be detected before selection is attempted -since these errors do not depend on the JSON value. -Therefore, an implementation SHOULD take a JSONPath and produce an optional -syntax error and then, -if and only if an error was not produced, SHOULD take a JSON value and -produce a list of nodes or an error (but not both).

-

Alternatively, an implementation MAY take a JSONPath and a JSON value -and produce a list of nodes or an optional error (but not both).

-

For any implementation, if a syntactically invalid JSONPath is provided, -the implementation MUST return an error.

-

If a syntactially invalid JSON value is provided, any implementation SHOULD -return an error.

-
-
-
-
-

-3.4. Syntax -

-

Syntactically, a JSONPath consists of a root selector ($), which -selects the root node of a JSON value, followed by a possibly empty -sequence of selectors.

-
-
-json-path = root-selector *selector
-root-selector = "$"               ; $ selects document root node
-
-
-

The syntax and semantics of each selector is defined below.

-
-
-
-
-

-3.5. Semantics -

-

The root selector $ not only selects the root node of the input -document, but it also produces as output a list consisting of one -node: the input document.

-

A selector may select zero or more nodes for further processing. -A syntactically valid selector MUST NOT produce errors. -This means that some -operations which might be considered erroneous, such as indexing beyond the -end of an array, -simply result in fewer nodes being selected.

-

But a selector doesn't just act on a single node: each selector acts on a -list of nodes and produces a list of nodes, as follows.

-

After the root selector, the remainder of the JSONPath is processed by passing -lists of nodes from one selector to the next ending up with a list of nodes -which is the result of -applying the JSONPath to the input JSON value.

-

Each selector acts on its input list of nodes as follows. -For each node in -the list, the selector selects zero or more nodes, each of which is a descendant -of the node or the node itself. -The output list of nodes of a selector is the concatenation of the lists -of selected nodes for each input node.

-

A specific, non-normative example will make this clearer. -Suppose the input -document is: {"a":[{"b":0},{"b":1},{"c":2}]}. -As we will see later, the JSONPath $.a[*].b selects the following list of nodes: 0, 1. -Let's walk through this in detail.

-

The JSONPath consists of $ followed by three selectors: .a, [*], and .b.

-

Firstly, $ selects the root node which is the input document. -So the result is a list -consisting of just the root node.

-

Next, .a selects from any input node of type object and selects any value of the input -node corresponding to the member name "a". -The result is again a list of one node: [{"b":0},{"b":1},{"c":2}].

-

Next, [*] selects from any input node which is an array and selects all the elements -of the input node. -The result is a list of three nodes: {"b":0}, {"b":1}, and {"c":2}.

-

Finally, .b selects from any input node of type object with a member name -b and selects the value of the input node corresponding to that name. -The result is a list containing 0, 1. -This is the concatenation of three lists, two of length one containing 0, 1, respectively, and one of length zero.

-

As a consequence of this approach, if any of the selectors selects no nodes, -then the whole JSONPath selects no nodes.

-

In what follows, the semantics of each selector are defined for each type -of node.

-
-
-
-
-

-3.6. Selectors -

-
-
-

-3.6.1. Dot Child Selector -

-
-
-
-Syntax -
-

A dot child selector has a member name known as a dot child name or a single asterisk -(*).

-

A dot child name corresponds to a name in a object.

-
-
-selector = dot-child              ; see below for alternatives
-dot-child = "." dot-child-name / ; .<dot-child-name>
-            "." "*"             ; .*
-dot-child-name = 1*(
-                   "-" /         ; -
-                   DIGIT /
-                   ALPHA /
-                   "_" /         ; _
-                   %x80-10FFFF    ; any non-ASCII Unicode character
-                 )
-DIGIT =  %x30-39                  ; 0-9
-ALPHA = %x41-5A / %x61-7A         ; A-Z / a-z
-
-
-

More general child names, such as the empty string, are supported by "Union -Child" (Section 3.6.2.3).

-

Note that the dot-child-name rule follows the philosophy of JSON strings and is -allowed to contain bit sequences that cannot encode Unicode characters (a -single unpaired UTF-16 surrogate, for example). -The behaviour of an implementation is undefined for child names which do -not encode Unicode characters.

-
-
-
-
-
-Semantics -
-

A dot child name which is not a single asterisk (*) is considered to -have a member name. -It selects the value corresponding to the name from any object node. -It selects -no nodes from a node which is not a object.

-

The member name of a dot child name is the sequence of Unicode characters contained -in that name.

-

A dot child name consisting of a single asterisk is a wild card. It selects -all the values of any object node. -It also selects all the elements of any array node. -It selects no nodes from -number, string, or literal nodes.

-
-
-
-
-
-
-

-3.6.2. Union Selector -

-
-
-
-3.6.2.1. Syntax -
-

A union selector consists of one or more union elements.

-
-
-selector =/ union
-union = "[" ws union-elements ws "]" ; [...]
-ws = *" "                             ; zero or more spaces
-union-elements = union-element /
-                 union-element ws "," ws union-elements
-                                       ; ,-separated list
-
-
-
-
-
-
-
-3.6.2.2. Semantics -
-

A union selects any node which is selected by at least one of the union selectors -and selects the concatenation of the -lists (in the order of the selectors) of nodes selected by the union elements.

-
-
-
-
-
-3.6.2.3. Child -
-
-
-
-Syntax -
-

A child is a quoted string.

-
-
-union-element = child ; see below for more alternatives
-child = %x22 *double-quoted %x22 / ; "string"
-        "'" *single-quoted "'"   ; 'string'
-
-double-quoted = dq-unescaped /
-          escape (
-              %x22 /         ; "    quotation mark  U+0022
-              "/" /          ; /    solidus         U+002F
-              "\" /          ; \    reverse solidus U+005C
-              "b" /          ; b    backspace       U+0008
-              "f" /          ; f    form feed       U+000C
-              "n" /          ; n    line feed       U+000A
-              "r" /          ; r    carriage return U+000D
-              "t" /          ; t    tab             U+0009
-              "u" 4HEXDIG )  ; uXXXX                U+XXXX
-
-
-dq-unescaped = %x20-21 / %x23-5B / %x5D-10FFFF
-
-single-quoted = sq-unescaped /
-          escape (
-              "'" /          ; '    apostrophe      U+0027
-              "/" /          ; /    solidus         U+002F
-              "\" /          ; \    reverse solidus U+005C
-              "b" /          ; b    backspace       U+0008
-              "f" /          ; f    form feed       U+000C
-              "n" /          ; n    line feed       U+000A
-              "r" /          ; r    carriage return U+000D
-              "t" /          ; t    tab             U+0009
-              "u" 4HEXDIG )  ; uXXXX                U+XXXX
-
-sq-unescaped = %x20-26 / %x28-5B / %x5D-10FFFF
-
-escape = "\"                 ; \
-
-HEXDIG =  DIGIT / "A" / "B" / "C" / "D" / "E" / "F"
-                              ; case insensitive hex digit
-
-
-

Notes: -1. double-quoted strings follow JSON in [RFC8259]. - Single-quoted strings follow an analogous pattern. -2. HEXDIG includes A-F and a-f.

-
-
-
-
-
-Semantics -
-

If the child is a quoted string, the string MUST be converted to a -member name by removing the surrounding quotes and -replacing each escape sequence with its equivalent Unicode character, as -in the table below:

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
-Table 3: -Escape Sequence Replacements -
Escape SequenceUnicode Character
"" %x22U+0022
"" "'"U+0027
"" "/"U+002F
"" ""U+005C
"" "b"U+0008
"" "f"U+000C
"" "n"U+000A
"" "r"U+000D
"" "t"U+0009
"" uXXXXU+XXXX
-

The child selects the value corresponding to the member name from any object -node that has a member with that name. -It selects no nodes from a node which is not a object.

-
-
-
-
-
-
-
-3.6.2.4. Array Selector -
-
-
-
-Syntax -
-

An array selector selects zero or more elements of an array node. -An array selector takes the form of an index, which selects at most one element, -or a slice, which selects zero or more elements.

-
-
-union-element =/ array-index / array-slice
-
-
-

An array index is an integer (in base 10).

-
-
-array-index = integer
-
-integer = ["-"] ("0" / (DIGIT1 *DIGIT))
-                            ; optional - followed by 0 or
-                            ; sequence of digits with no leading zero
-DIGIT1 = %x31-39            ; non-zero digit
-
-
-

Note: the syntax does not allow integers with leading zeros such as 01 and -01.

-

An array slice consists of three optional integers (in base 10) separated by colons.

-
-
-array-slice = [ start ] ws ":" ws [ end ]
-                   [ ws ":" ws [ step ] ]
-start = integer
-end = integer
-step = integer
-
-
-

Note: the array slices : and :: are both syntactically valid, as are :2:2, 2::2, and 2:4:.

-
-
-
-
-
-Semantics -
-
-
-
-Informal Introduction -
-

This section is non-normative.

-

Array indexing is a way of selecting a particular element of an array using -a 0-based index. -For example, the expression [0] selects the first element of a non-empty array.

-

Negative indices index from the end of an array. -For example, the expression [-2] selects the last but one element of an array with at least two elements.

-

Array slicing is inspired by the behaviour of the Array.prototype.slice method -of the JavaScript language as defined by the ECMA-262 standard [ECMA-262], -with the addition of the step parameter, which is inspired by the Python slice expression.

-

The array slice expression [start:end:step] selects elements at indices starting at start, -incrementing by step, and ending with end (which is itself excluded). -So, for example, the expression [1:3] (where step defaults to 1) -selects elements with indices 1 and 2 (in that order) whereas -[1:5:2] selects elements with indices 1 and 3.

-

When step is negative, elements are selected in reverse order. Thus, -for example, [5:1:-2] selects elements with indices 5 and 3, in -that order and [::-1] selects all the elements of an array in -reverse order.

-

When step is 0, no elements are selected. -This is the one case which differs from the behaviour of Python, which -raises an error in this case.

-

The following section specifies the behaviour fully, without depending on -JavaScript or Python behaviour.

-
-
-
-
-
-Detailed Semantics -
-

An array selector is either an array slice or an array index, which is defined -in terms of an array slice.

-

A slice expression selects a subset of the elements of the input array, in -the same order -as the array or the reverse order, depending on the sign of the step parameter. -It selects no nodes from a node which is not an array.

-

A slice is defined by the two slice parameters, start and end, and -an iteration delta, step. -Each of these parameters is -optional. len is the length of the input array.

-

The default value for step is 1. -The default values for start and end depend on the sign of step, -as follows:

- - - - - - - - - - - - - - - - - - - - - -
-Table 4: -Default array slice start and end values -
Conditionstartend
step >= 00len
step < 0len - 1-len - 1
-

Slice expression parameters start and end are not directly usable -as slice bounds and must first be normalized. Normalization is defined as:

-
-
-FUNCTION Normalize(i):
-  IF i >= 0 THEN
-    RETURN i
-  ELSE
-    RETURN len + i
-  END IF
-
-
-

The result of the array indexing expression [i] is defined to be the result of the array -slicing expression [i:Normalize(i)+1:1].

-

Slice expression parameters start and end are used to derive slice bounds lower and upper. -The direction of the iteration, defined -by the sign of step, determines which of the parameters is the lower bound and which -is the upper bound:

-
-
-FUNCTION Bounds(start, end, step, len):
-  n_start = Normalize(start)
-  n_end = Normalize(end)
-
-  IF step >= 0 THEN
-    lower = MIN(MAX(n_start, 0), len)
-    upper = MIN(MAX(n_end, 0), len)
-  ELSE
-    upper = MIN(MAX(n_start, -1), len-1)
-    lower = MIN(MAX(n_end, -1), len-1)
-  END IF
-
-  RETURN (lower, upper)
-
-
-

The slice expression selects elements with indices between the lower and -upper bounds. -In the following pseudocode, the a(i) construct expresses the -0-based indexing operation on the underlying array.

-
-
-IF step > 0 THEN
-
-  i = lower
-  WHILE i < upper:
-    SELECT a(i)
-    i = i + step
-  END WHILE
-
-ELSE if step < 0 THEN
-
-  i = upper
-  WHILE lower < i:
-    SELECT a(i)
-    i = i + step
-  END WHILE
-
-END IF
-
-
-

When step = 0, no elements are selected and the result array is empty.

-

An implementation MUST raise an error if any of the slice expression parameters -does not fit in -the implementation's representation of an integer. -If a successfully parsed slice expression is evaluated against an array whose -size doesn't -fit in the implementation's representation of an integer, the implementation -MUST raise an error.

-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

-4. IANA Considerations -

-

TBD: Define a media type for JSON Path expressions.

-
-
-
-
-

-5. Security Considerations -

-

This section gives security considerations, as required by [RFC3552].

-
-
-
-

-6. References -

-
-

-6.1. Normative References -

-
-
[RFC2119]
-
-Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
-
-
[RFC3629]
-
-Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, DOI 10.17487/RFC3629, , <https://www.rfc-editor.org/info/rfc3629>.
-
-
[RFC5234]
-
-Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, , <https://www.rfc-editor.org/info/rfc5234>.
-
-
[RFC8174]
-
-Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
-
-
[RFC8259]
-
-Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", STD 90, RFC 8259, DOI 10.17487/RFC8259, , <https://www.rfc-editor.org/info/rfc8259>.
-
-
-
-
-

-6.2. Informative References -

-
-
[E4X]
-
-ISO, "Information technology — ECMAScript for XML (E4X) specification", ISO/IEC 22537:2006 , .
-
-
[ECMA-262]
-
-Ecma International, "ECMAScript Language Specification, Standard ECMA-262, Third Edition", , <http://www.ecma-international.org/publications/files/ECMA-ST-ARCH/ECMA-262,%203rd%20edition,%20December%201999.pdf>.
-
-
[JSONPath-orig]
-
-Gössner, S., "JSONPath – XPath for JSON", , <https://goessner.net/articles/JsonPath/>.
-
-
[RFC3552]
-
-Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, , <https://www.rfc-editor.org/info/rfc3552>.
-
-
[RFC6901]
-
-Bryan, P., Ed., Zyp, K., and M. Nottingham, Ed., "JavaScript Object Notation (JSON) Pointer", RFC 6901, DOI 10.17487/RFC6901, , <https://www.rfc-editor.org/info/rfc6901>.
-
-
[SLICE]
-
-"Slice notation", n.d., <https://github.com/tc39/proposal-slice-notation>.
-
-
[XPath]
-
-Berglund, A., Boag, S., Chamberlin, D., Fernandez, M., Kay, M., Robie, J., and J. Simeon, "XML Path Language (XPath) 2.0 (Second Edition)", World Wide Web Consortium Recommendation REC-xpath20-20101214, , <https://www.w3.org/TR/2010/REC-xpath20-20101214>.
-
-
-
-
-
-
-

-Acknowledgements -

-

This specification is based on Stefan Gössner's -original online article defining JSONPath [JSONPath-orig].

-

The books example was taken from -http://coli.lili.uni-bielefeld.de/~andreas/Seminare/sommer02/books.xml --- a dead link now.

-
-
-
-
-

-Contributors -

-
-
Carsten Bormann
-
Universität Bremen TZI
-
Postfach 330440
-
-D-28359 Bremen -
-
Germany
-
-Phone: -+49-421-218-63921 -
- -
-
-
-
-
-

-Authors' Addresses -

-
-
Glyn Normington (editor)
-
VMware, Inc.
-
Winchester
-
United Kingdom
- -
-
-
Edward Surov (editor)
-
TheSoul Publishing Ltd.
-
Limassol
-
Cyprus
- -
-
-
Marko Mikulicic (editor)
-
InfluxData, Inc.
-
-Pisa
-
Italy
- -
-
-
Stefan Gössner
-
Fachhochschule Dortmund
-
Sonnenstraße 96
-
-D-44139 Dortmund -
-
Germany
- -
-
-
- - - diff --git a/scripts/gen.sh b/scripts/gen.sh index 46c1f975..862133df 100755 --- a/scripts/gen.sh +++ b/scripts/gen.sh @@ -10,5 +10,5 @@ cd "$script_dir/.." kdrfc -h3 draft-ietf-jsonpath-base.md && \ xmlstarlet sel -T -t -v '//sourcecode[@type="abnf"]' ./draft-ietf-jsonpath-base.xml 2>/dev/null \ | aex \ -| bap -S path -q && cp draft-ietf-jsonpath-base.html docs/index.html +| bap -S path -q ) From 7f74b297d1fdb09967be8dde2b83b777c946822a Mon Sep 17 00:00:00 2001 From: Glyn Normington Date: Wed, 24 Mar 2021 10:31:41 +0000 Subject: [PATCH 06/11] Do not copy HTML and leave ABNF around Ref https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base/issues/81 --- .gitignore | 1 + scripts/gen.sh | 1 + 2 files changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index b6657300..6a3e5300 100644 --- a/.gitignore +++ b/.gitignore @@ -4,6 +4,7 @@ *.swp *.txt *.upload +*.abnf *~ .refcache .tags diff --git a/scripts/gen.sh b/scripts/gen.sh index 862133df..3341cada 100755 --- a/scripts/gen.sh +++ b/scripts/gen.sh @@ -10,5 +10,6 @@ cd "$script_dir/.." kdrfc -h3 draft-ietf-jsonpath-base.md && \ xmlstarlet sel -T -t -v '//sourcecode[@type="abnf"]' ./draft-ietf-jsonpath-base.xml 2>/dev/null \ | aex \ +| tee draft-ietf-jsonpath-base.abnf \ | bap -S path -q ) From e74d02b929ce8162473c001c0eb1c56fc287fd65 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Wed, 24 Mar 2021 15:11:43 +0100 Subject: [PATCH 07/11] Update README to new repo name --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 836b5146..bb535c0a 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,9 @@ This is the working area for the IETF [JSONPATH Working Group](https://datatracker.ietf.org/wg/jsonpath/documents/) Internet-Draft, "JavaScript Object Notation (JSON) Path". -* [Editor's Copy](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/#go.draft-ietf-jsonpath-base.html) +* [Editor's Copy](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-base/#go.draft-ietf-jsonpath-base.html) * [Working Group Draft](https://datatracker.ietf.org/doc/html/draft-ietf-jsonpath-base) -* [Compare Editor's Copy to Working Group Draft](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-jsonpath/#go.draft-ietf-jsonpath-base.diff) +* [Compare Editor's Copy to Working Group Draft](https://ietf-wg-jsonpath.github.io/draft-ietf-jsonpath-base/#go.draft-ietf-jsonpath-base.diff) ## Building the Draft @@ -19,8 +19,8 @@ This requires that you have the necessary software installed. See ## Community -All official discussion is in [issues](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/issues), -[pull requests](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/pulls), and the [jsonpath@ietf.org mailing list](https://www.ietf.org/mailman/listinfo/jsonpath). +All official discussion is in [issues](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base/issues), +[pull requests](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base/pulls), and the [jsonpath@ietf.org mailing list](https://www.ietf.org/mailman/listinfo/jsonpath). See the [archive](https://mailarchive.ietf.org/arch/browse/jsonpath/) for previous posts. ## License @@ -30,7 +30,7 @@ See the draft for the copyright which is repeated in [LICENSE](./LICENSE). ## Contributing See the -[guidelines for contributions](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-jsonpath/blob/main/CONTRIBUTING.md). +[guidelines for contributions](https://github.com/ietf-wg-jsonpath/draft-ietf-jsonpath-base/blob/main/CONTRIBUTING.md). ## Comparing JSONPath Implementations From e0e85990eed55af2885b7133e597e9cfb64a3bdd Mon Sep 17 00:00:00 2001 From: Tim Bray Date: Mon, 22 Mar 2021 11:36:28 -0700 Subject: [PATCH 08/11] Change title per #68 --- draft-ietf-jsonpath-base.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-jsonpath-base.md b/draft-ietf-jsonpath-base.md index 2e101a03..a46421a8 100644 --- a/draft-ietf-jsonpath-base.md +++ b/draft-ietf-jsonpath-base.md @@ -14,7 +14,7 @@ pi: symrefs: 'true' sortrefs: 'true' comments: true -title: JavaScript Object Notation (JSON) Path +title: "JSONPath: Query expressions for JSON" abbrev: JSONPath area: ART wg: JSONPath WG From 558fdf23cf7063ce5565f63aa93f7c396d180d90 Mon Sep 17 00:00:00 2001 From: Glyn Normington Date: Wed, 24 Mar 2021 18:48:27 +0000 Subject: [PATCH 09/11] Glyn Normington has retired --- draft-ietf-jsonpath-base.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-jsonpath-base.md b/draft-ietf-jsonpath-base.md index a46421a8..18644966 100644 --- a/draft-ietf-jsonpath-base.md +++ b/draft-ietf-jsonpath-base.md @@ -25,7 +25,7 @@ author: - role: editor ins: G. Normington name: Glyn Normington - org: VMware, Inc. + org: Retired street: '' city: Winchester region: '' From 3bf8a0338bf49270b11c7002a386c19a4ded7957 Mon Sep 17 00:00:00 2001 From: Glyn Normington Date: Wed, 24 Mar 2021 19:15:41 +0000 Subject: [PATCH 10/11] Blank org for Glyn Normington Thanks to @cabo, I don't need to publicise my retirement quite so starkly. --- draft-ietf-jsonpath-base.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-jsonpath-base.md b/draft-ietf-jsonpath-base.md index 18644966..d4cac71c 100644 --- a/draft-ietf-jsonpath-base.md +++ b/draft-ietf-jsonpath-base.md @@ -25,7 +25,7 @@ author: - role: editor ins: G. Normington name: Glyn Normington - org: Retired + org: '' street: '' city: Winchester region: '' From 7460193d63726e43992892a466c46699e627e949 Mon Sep 17 00:00:00 2001 From: Carsten Bormann Date: Sat, 13 Mar 2021 18:47:22 +0100 Subject: [PATCH 11/11] Use second parameter, len, of Normalize throughout --- draft-ietf-jsonpath-base.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/draft-ietf-jsonpath-base.md b/draft-ietf-jsonpath-base.md index d4cac71c..5b70be22 100644 --- a/draft-ietf-jsonpath-base.md +++ b/draft-ietf-jsonpath-base.md @@ -795,7 +795,7 @@ as slice bounds and must first be normalized. Normalization for this purpose is defined as: ~~~~ -FUNCTION Normalize(i): +FUNCTION Normalize(i, len): IF i >= 0 THEN RETURN i ELSE @@ -803,8 +803,9 @@ FUNCTION Normalize(i): END IF ~~~~ -The result of the array indexing expression `[i]` is defined to be the result of the array -slicing expression `[i:Normalize(i)+1:1]`. +The result of the array indexing expression `[i]` applied to an array +of length `len` is defined to be the result of the array +slicing expression `[i:Normalize(i, len)+1:1]`. Slice expression parameters `start` and `end` are used to derive slice bounds `lower` and `upper`. The direction of the iteration, defined @@ -813,8 +814,8 @@ is the upper bound: ~~~~ FUNCTION Bounds(start, end, step, len): - n_start = Normalize(start) - n_end = Normalize(end) + n_start = Normalize(start, len) + n_end = Normalize(end, len) IF step >= 0 THEN lower = MIN(MAX(n_start, 0), len)