Respecting Backwards Compatibility

[TotalTechGeek]

Background

This is the first topic I'd like for @json-logic/tc to address.

Essentially, we've had some extended discussions over the past two weeks with regards to respecting backwards compatibility and the goal of this initiative. Some operators in JSON Logic have been deemed controversial, and are difficult to retrofit with new capabilities.

I believe very strongly that respecting backwards compatibility is necessary to build a stable community and ecosystem, and to give credibility to this initiative.

Because of this, I'd like to propose the following:

Proposal

• The primary outcome of this initiative will be designated "JSON Logic Core".
• The test suite from https://jsonlogic.com/tests.json (as of 2024-12-19) is recognized to be the first accepted phase 3 test suite.
  (We, however, intend to break down the above test suite into smaller collections. As we review each operator.)
• No operators will be modified in a way that breaks backwards compatibility with any accepted phase 3 tests, without unanimous approval of the TC*.
• We recognize community extensions are within the scope of this organization.
• As part of this initiative, we will create a "Legacy" extension. This extension can be used to deprecate controversial operators during this initiative that we may not want to include in Core.
• All approved extensions will be evaluated in our compatibility tables.
• Replacement operators may be defined for the "Core" specification.

* If TC Members have not cast a vote for a week after a supermajority has been reached, the proposal may proceed.

Reasoning

I'd prefer to avoid invalidating all 19 implementations of JSON Logic under this umbrella organization; but we do want to allow JSON Logic to evolve and grow, and address issues many users have encountered.

To avoid fragmenting the ecosystem and harming JSON Logic Core adoption, and to retain community trust, I'd prefer an approach that respects backwards compatibility.

For this reason, I believe it'd be a safer route to deprecate certain operators to a "Legacy" extension, and agree upon replacement operators for the core specification that do not interfere with existing logic.

This will give folks a larger window to create migrations (mapping old operators to new ones), and it should allow for a seamless upgrade.

Out of Scope

Which Operators?

This proposal does not specify which operators will be deprecated to legacy status.

However, some of the current contenders are:

• var
• missing
• missing_some

I believe we may want to replace var with a val operator, which does not embed pathing semantics in a parsed string argument, and instead opts for a more AST-like approach.

This would potentially allow for a custom operator like rfc6901 to be introduced, which would allow for

{ "val": { "rfc6901": "/hello/world" } }

Or more simply

{ "val": ["hello", "world"] }

However, the val operator is not what is being voted on here.

Additional Tests

What is also out of scope are other tests.

If your implementation has additional tests outside of tests.json from mainline, that you would like to be incorporated, then we will review those in another proposal 😄

[TotalTechGeek]

A reminder: https://github.com/orgs/json-logic/discussions/15#discussioncomment-11620756

For this proposal to be accepted by the TC, it needs 3 TC votes (self-votes count for now) and no vetoes.

Members of the community are also invited to voice input (we're also looking for another TC seat). If there are objections, then we will try to reach consensus or expand TC involvement.

I'm hoping for this decision to be unanimous though.

[dslmeinte]

(Not a TC member, but nevertheless I've got the following questions:)

1. What, exactly, does it mean for an operator to be “controversial”? (I think “controversial” and “legacy” mean different things.)
2. Is there going to be a specification for behavior on invalid input, like passing a non-array to map?

[TotalTechGeek]

1. Controversial and Legacy do indeed mean different things -- I'm describing certain operators like var, missing and missing_some as controversial as it has elicited a ton of community feedback, with vastly differing opinions.

Opinions have varied from:

• Replace it with RFC6901 semantics (breaking)
• Leave it alone (prevents access to certain keys)
• Add dot-prop notation (complicates var, makes the spec more complex, kinda reinvents RFC6901)
• No pathing semantics, make it AST-like (breaking)

I think if an operator has significant controversy, or problems that are difficult to overcome with a clean retrofit, it's a sign we might want to deprecate it in favor of something simpler that adheres to JSON Logic being more of an AST.

Right now, I think it's mainly just those 3 operators that would be moved to legacy.

So far, nothing is legacy, I think it's up to the community to decide what should be.

2. I would think so.

[TotalTechGeek]

And addressing a previous question you asked elsewhere + appending the question you did ask:

We will be breaking down that tests.json into distinct suites of operators that will be re-evaluated by the TC, and make things much more "atomic"

Each operator more rigorously defined, ideally with specifications for error cases.

We also may upgrade some of the operators to make them more consistent, like the comparison operators.

For example, in json-logic-js, < and <= can accept 3 arguments to check for x <= y <= z. None of the other comparison operators work that way; it's also a bit odd that it stops at three.

One topic that might come up is whether we want to make that consistent across all comparison operators, and make it more variadic.

(And again, these decisions are out of the scope of this proposal, which merely exists to say, "Hey, let's respect backwards compat, let's recognize this guy as a baseline, and let's agree that we can have a concept of Legacy Operators if we don't want certain behaviors to be considered 'Core'")

[beeme1mr]

@TotalTechGeek I advise against requiring a unanimous approval from the TC in favor of a supermajority since it may not be possible to get a response from everyone in a reasonable amount of time.

[TotalTechGeek]

😉

[TotalTechGeek]

Jokes aside; we could add a timeliness clause if there is significant concern here.

[rmannibucau]

Not sure it helps but a process like Apache Software Foundation one can work with the remote issue of such group: https://www.apache.org/foundation/voting.html. Main functonal alternative I saw is a leader which more or less decides alone.

[TotalTechGeek]

@rmannibucau Oh huh! The voting schemes ended up with some surprising similarities,

I might give this more of a read and perhaps we'll shift the language bit more towards the Apache standard 🤔.

[codetiger]

Agreeing 100% on not breaking backward compatibility at this point and defining extension categories. We need to also publish extension categories like:

1. Core
2. Legacy
3. Optional / Experimental (Potential candidates to be part of core in future)
4. 3rd party

These categorization might give more clarity for users on what it means to use an optional extension or legacy.

[TotalTechGeek]

With 3 TC Votes; I believe that makes this "Accepted".

We will keep the discussion open for a bit to allow other members of the community to voice thoughts / give TC members time to object.

Action item:

The .github repo should have a document added to reflect & document this. Issue #6 seems like it would be relevant for this.