Hey Maintainers!

[TotalTechGeek]

Hey folks; this type of community management is a bit new to me, so I'm open to feedback.

I've opened a project here to try and track our current goals, which are to help set community guidelines & licensing, and also try to decide on communication approach -
https://github.com/orgs/json-logic/projects/2

This should hopefully not take very long.

While I generally prefer to communicate over Slack / Discord, where possible I'd like to try to keep these discussions as open and transparent as possible, so I figured GitHub might be an effective forum.

However, these decisions should be driven by the community.

[TotalTechGeek]

In the spirit of transparency and openness, I'm also going to link to some of the convos that have taken place on other repos:

A ton of conversation took place here:

• Checking on Maintenance / Would you be interested in contributing to a spec? diegoholiveira/jsonlogic#89 (Go)

Some of the other conversations:

• Checking on Maintenance / Would you be interested in contributing to a spec?  panzi/panzi-json-logic#1 (Python + C)
• Would you be interested in collaborating to develop a JSON Logic Specification? Viicos/jsonlogic#34 (Python)
• Some Non-Standard Recommendations & Request to Collaborate datalogic-rs#3 (Rust)
• Discrepency compared to https://jsonlogic.com/play.html json-everything/json-everything#820 (C# -- I kinda hijacked an issue to discuss the possibility of working together)

No response (yet):

• Checking on Maintenance / Would you be interested in contributing to a spec? allegro/json-logic-kmp#127 (JVM + Swift, written in Kotlin Multiplatform)
• Checking on Maintenance / Would you be interested in contributing to a spec? useful-libs/json_logic_ruby#22 (Ruby)

[codetiger]

I would like to include naming conventions standardization as part of the governance. When I started with JSONLogic, I found each library having a different notation, like LogicEngine.apply, JSONLogic.apply, JSONLogic.Run etc.

[TotalTechGeek]

That might help folks when switching between libraries and ecosystems; so that might be on the table! Though perhaps aliases are allowed for backwards compatibility reasons.

If we go down that route, I think I'd encourage us to separate the library conventions governance from the logic specification

[codetiger]

Makes sense, our initial focus should be on spec governance rather than conventions.

[gregsdennis]

I think we do need a more informal place to chat. Things like "I'm at work right now and can't properly respond" doesn't really belong in a GH discussion, but it could still be good information to convey.

[TotalTechGeek]

Slack? Discord? Some sort of third party Git IRC?

[beeme1mr]

I can create a dedicated channel in the CNCF Slack workspace.

[TotalTechGeek]

Let's go ahead and do that for now.

This is where you can get an invite to the Slack: https://communityinviter.com/apps/cloud-native/cncf

Within the CNCF Slack, you can join the #json-logicchannel.

[josephdpurcell]

PHP FIG is an excellent resource on how to organize specifications and the supporting community: https://www.php-fig.org/. I would be happy to reach out to the group to see if a Q&A could be done if there were well defined questions.

Community driven efforts are a highly complex endeavor, but worthwhile. The impact of FIG extends beyond PHP, for example.

[Viicos]

Hello there,

I maintain https://github.com/Viicos/jsonlogic (a Python implementation). I don't know if I'll have much spare time, but I can provide some help from time to time.

I see that there is already some discussion going on to sort out specific details of the implementation (e.g. https://github.com/orgs/json-logic/discussions/10). I think that before doing so, there is some value in:

• discussing how the spec should be worked out? Should this take the form of an RFC ¹?
• discussing how much the spec should cover.

Regarding the second point, I'm going to introduce briefly some design decisions I made in my implementation.

Whenever possible, I've tried to keep things extensible/abstract:

• I don't define a fixed set of operators, but rather a registry mechanism to allow arbitrary operators to be defined and used.
• I don't define a single way to resolve variables, but rather an interface that should be implemented by end users (and still provide two implementations — the JSON Pointer RFC and existing dot syntax). Simplified (this doesn't work as is if you try using my implementation), the interface looks like this:

  # I hope you don't mind a basic Python example ;)
  
  class BaseReferenceParser(ABC):  # This is an abstract class
      @abstractmethod
      def parse(self, reference: str) -> list[str]:
          pass
  
  # Here is an implementation of the original "dot" format:
  class DotReferenceParser(BaseReferenceParser):
      def parse(self, reference: str) -> list[str]:
          if reference == "":
              return []
          else:
              return reference.split(".")
  
  from jsonlogic.evaluation import evaluate
  
  value = evaluate(
      {"var": "some.data"},
      data={"some": {"data": 1}},
      reference_resolver=DotReferenceParser(),
  )
  print(value)
  #> 11

In other words: whenever possible, I've tried to make things as generic as possible. So what could be done (but of course this is only a suggestion) is to first have a specification describing the general JSON Logic syntax: how operators can be created, how to use them in a JSON Logic expression, etc. We can also define a variable reference parsing/resolving abstract interface, like in the Python example I gave.

A second specification, based on the first one, would be more specific and can/should make opinionated choices when it comes to:

• the set of defined operators, how they behave with different data types (e.g. should we allow </>/<=/>= on strings?).
• the default variable reference format.

---

Additional note: I my implementation, I kind of already have a distinction between the two previous paragraphs. Given a raw JSON Logic expression, I first parse it into a JSONLogicExpression:

expr = JSONLogicExpression.from_json(
    {
        "*": [
            {"var": "some_var"},
            2
        ]
    }
)
print(expr)
>>> JSONLogicExpression(
>>>     expression={'*': [
>>>             JSONLogicExpression(expression={'var': ['some_var']}),
>>>             2,
>>>         ]
>>>     }
>>> )

The parsing doesn't do much, but notice that it makes sure single operand operators (like "var") have their arguments wrapped in a list if necessary. However, no operator definition is involved here at this stage.

Footnotes

1. Drafting an RFC is a long process, so might not be worth going this way. But at least the RFC redacting guidelines could be used. ↩

[TotalTechGeek]

for me the only topic is what will be the future, a stack on legacy lack of agreements or a shared agreements.

I believe that most of the community will agree on most of the existing operators; becoming a shared agreement.

I believe that var, missing and missing_some might be the more controversial operators because they're more difficult to retrofit, because they have additional pathing syntax baked into them (and several arguments), and are less "AST-like".

We can address this easily by describing these as legacy, deprecated operators that we expect implementations to continue supporting for the foreseeable future, and encourage folks to use val or some replacement operator that the community does agree upon.

This also gives plenty of time for folks to implement a migration path, if we inevitably do remove some of these operators.

Defining new operators for some of these controversial behaviors from the original is a much cleaner path than redefining an existing one. It also makes implementing a migration easier.

With this path, we can even take the path of labeling var, missing, etc. as a "legacy extension"

But I don't want to break var for users.

---

There's room to discuss whether var and such should be left out of the RFC, if we take the path of defining replacement operators.

But for the compatibility suite, I think it's necessary.

[rmannibucau]

But I don't want to break var for users.

We agree on that for the migration time but where we are not yet aligned I guess is that the spec needs to mention anythingl egacy. Understand me, the spec doesn't exist and would start by defining legacy operators, this is starting with debt and I don't think it helps the goal since users will start looking at already deprecated stuff so I think it is worth not mentionning it in the spec - but having a dedicated page on implementation vendors or a doc page explaining how to migrate in the spec makes sense to me, but no assumption it must be supported by a vendor.

So I'm clearly in favor of not trying to be strictly backward compatible with something which doesn't exist (previous version of the spec) but documentation what had been the replacements (like JPA explains what replaces hibernates specific annotations for ex).

[TotalTechGeek]

is that the spec needs to mention anything legacy

I'm potentially okay with leaving var (and similar) out of the RFC / formal specification for core JSON Logic.

I'm also okay with defining those other operators as a legacy "extension". We would test all accepted community extensions in our compatibility tables, and make it easy for folks to look up what operators are generally well supported, similar to "Can I Use"

The extensions would be their own specs.

Once we solidify things with the base, I'd like for this community to be a channel for folks to propose common community extensions & use this as a hub for helping developers with resources needed to get the extensions implemented.

[rmannibucau]

I like the caniuse idea using the spec and the original impl as comparison points 👍

[gregsdennis]

When we were writing RFC9535, our primary problem was implementation alignment. Implementations only had a blog post and a reference implementation as their source material. As a result, many implementations kinda did their own thing. We needed the JSON Path Comparison Project to see how diverse the implementations really were. Backward incompatibility was inevitable for that project, despite our efforts to minimize it.

I think the JSON Logic implementations should be significantly more aligned given the (more, yet still incomplete) documentation, at least two reference implementations, and a moderate (though also incomplete) test suite. It's reasonable that we can find a large compatible intersection of support.

[dslmeinte]

For the specification of CertLogic I didn't use a specific, pre-existing format.

One advice: it's probably better to first specify the basics and 1 or 2 operators completely to bits (including defining a good test suite), than it is to try and specify everything including all operators all at once.

[JTeeuwissen]

Before developing a rigorous test suite, might it be beneficial to draft and discuss some ground rules for json logic?

For example:
Which operators are included and which ones are not. (E.g. do we really want to use js equality? And what is the name for ternary?)
How do these operators function (e.g. should + work on more than two arguments?)
And how to deal with invalid input (e.g. more parameters than allowed, do we ignore them?)

Some decisions might make sense for the js implementation, but should be reconsidered in this wider ecosystem.

[rmannibucau]

Agree. Ideally we could get multiple flavors, a) no-operator defined but how it works (useful for product integration where the security - wide sense - is key and operators must be strictly controlled and potentially their behavior changed), b) minimal set (built-in safe operators), c) maybe a core set (common operators), d) (unspecified) implementation/language specific.

I fear we'l lneed the falsy/truthy impl - js style or not - cause otherwise it becomes very verbose to use it and makes it harder to integrate and welcome new users but what is important is the extensibility - custom operators - will stay a key feature of all impl even if it can't be strictly specified outside a language/API.

Hope it makes sense.

[JTeeuwissen]

Personally I have never felt the need for truthy values or equality type conversion, an explicit conversion seems easier to understand. But it's a great example of something that should be discussed before writing a spec.

[rmannibucau]

Agree, maybe you can open a ticket/discussion about it?

side note: i'm interested in an explicit conversion seems easier to understand, so you prefer to add a wrapper in json logic to test null or lengths? I can see cases it is better, fully agree on that but also most cases where it makes the json more verbose for almost no gain so I'm not 100% sure. Maybe it could be some shortcut in "c" but not in "a" and "b" - thinking out loud.

[TotalTechGeek]

Hey there; there are some closed discussions as well as this guy to kick off ground rules -
https://github.com/orgs/json-logic/discussions/16

For now -
JSON Logic "Core" is the end goal of this initiative; and compatibility with the current tests.json is required for core*

* at least in the sense that any changes made to Core do not break tests.json

We may end up deprecating a few operators to be considered legacy extensions, and not part of "Core".

I think we'll end up making good on "a", "b" and "c" as described by @rmannibucau,

Where "b" is JSON Logic Core and "c" is Core + Community extensions.

"a" would just be the AST specification, and users would define their own operators and parsing rules.

This means of course, folks could change how truthiness works for their app, but it would diverge from core.

--

How we handle invalid input is within scope of the discussions, also variadic nature of the comparison operators.

The TC will help organize a lot of these thoughts into a consolidated document