MeiliSearch/permissive-json-pointer
Tamo 1ef87cc6d0
chore: move permissive-json-pointer in the meilisearch repository
Update permissive-json-pointer/src/lib.rs

Co-authored-by: Clément Renault <clement@meilisearch.com>
2022-04-20 19:24:41 +02:00
..
src chore: move permissive-json-pointer in the meilisearch repository 2022-04-20 19:24:41 +02:00
Cargo.toml chore: move permissive-json-pointer in the meilisearch repository 2022-04-20 19:24:41 +02:00
README.md chore: move permissive-json-pointer in the meilisearch repository 2022-04-20 19:24:41 +02:00

README.md

Permissive json pointer

This crate provide an interface a little bit similar to what you know as “json pointer”. But its actually doing something quite different.

The API

The crate provide only one function called [select_values]. It takes one object in parameter and a list of selectors. It then returns a new object containing only the fields you selected.

The selectors

The syntax for the selector is easier than with other API. There is only ONE special symbol, its the ..

If you write dog and provide the following object;

{
  "dog": "bob",
  "cat": "michel"
}

Youll get back;

{
  "dog": "bob",
}

Easy right?

Now the dot can either be used as a field name, or as a nested object.

For example, if you have the following json;

{
  "dog.name": "jean",
  "dog": {
    "name": "bob",
    "age": 6
  }
}

What a crappy json! But never underestimate your users, they WILL somehow base their entire workflow on this kind of json. Here with the dog.name selector both fields will be selected and the following json will be returned;

{
  "dog.name": "jean",
  "dog": {
    "name": "bob",
  }
}

And as you can guess, this crate is as permissive as possible. Itll match everything it can! Consider this even more crappy json;

{
  "pet.dog.name": "jean",
  "pet.dog": {
    "name": "bob"
  },
  "pet": {
    "dog.name": "michel"
  },
  "pet": {
    "dog": {
      "name": "milan"
    }
  }
}

If you write pet.dog.name everything will be selected.

Matching arrays

With this kind of selectors you cant match a specific element in an array. Your selector will be applied to all the element in the array.

Consider the following json;

{
  "pets": [
    {
      "animal": "dog",
      "race": "bernese mountain",
    },
    {
      "animal": "dog",
      "race": "golden retriever",
    },
    {
      "animal": "cat",
      "age": 8,
    }
  ]
}

With the filter pets.animal youll get;

{
  "pets": [
    {
      "animal": "dog",
    },
    {
      "animal": "dog",
    },
    {
      "animal": "cat",
    }
  ]
}

The empty element in an array gets removed. So if you were to look for pets.age you would only get;

{
  "pets": [
    {
      "age": 8,
    }
  ]
}

And I think thats all you need to know 🎉