[Feature Request]: Create a Lexicon Generator

[MasterJ93]

Summary

Create a solution for not only creating lexicons, but also converting them into Swift models and methods.

Pain points

At this time, all lexicon models and methods need to be written by hand. This can cause issues with missing out features, duplicating code, making mistakes, and sloppy implementations. Creating a lexicon generator would solve all of these problems.

The idea is to create an app and CLI tool that will do the following:

• Create and validate the lexicon in a JSON format.
• Take all of the AT Protocol-provided and Bluesky-provided lexicons and convert them into validated Swift models and methods.
• Give proper syntax and clean code for each model and method, which would also conform to the ATProtoKit API Design Guidelines and the Swift API Design Guidelines.

There will be some limitations:

• Some lexicons in Bluesky and AT Protocol are built into some places and will be treated differently. For example, all of the lexicons related to creating and managing sessions must be in ATProtocolConfiguration, and com.atproto.repo.uploadBlob is required to be in APIClientService.
• The first version may not implement any lexicons that have the subscription value, due to their special nature and still-highly-moldable structure of the models and methods.

The app and CLI tool will simply allow you to insert the lexicon JSON files, as well as an optional configuration file of adding extra information (such as comments). The app will specifically show common errors among any JSON errors when creating or viewing a lexicon file (not available in version 1.0).

Considered Alternatives

N/A

Is this a breaking change?

No

Library Examples

The repo swift-atproto has a good understanding of what could be done in terms of the lexicon generator. However, using it as-is isn't ideal: a better one would need to be made that better fits with the design goals of ATProtoKit.

Additional Context

This will most likely be in another repository, so progress will be followed over there instead of here. When it's completed its goals, this issue will close.

[MasterJ93]

It appears that OpenAPI Generator from Apple may be the most likely candidate for this. Will have to research further...

[knotbin]

This would be incredibly helpful for working on Spark. Please let me know if there's anything I could do to help or contribute or if there's any updates on this.

[knotbin]

@MasterJ93 could you elaborate on what makes https://github.com/andooown/lexicon-gen not a good fit for the design goals of ATProtoKit and how it could be changed to do so?

[MasterJ93]

A fundamental shift in how it generates the code is needed in order for it to conform to the design goals of ATProtoKit:

• It needs to be fully compatible to handle UnknownType.
• At the moment, there's a bunch of duplicated code with ATProtoKit has it currently stands, and the upcoming lexicon generator is supposed to address this in ways lexicon-gen doesn't.
• One of ATProtoKit's design goals is to strictly adhere to the Swift API Design Guidelines. One of the guidelines deals with how it handles grammar. lexicon-gen, at this time, doesn't handle this as I understand it.
• Apple's OpenAPI generator will soon be implemented into ATProtoKit, and I don't recall seeing lexicon-gen using that at all.

These are just a few things off the top of my head. This isn't a knock on the Swift package: it's a very well-made package. However, for the goals that ATProtoKit has, it's not sufficient enough. Though, if you're able to tweak it to fit ATProtoKit's goals, I'm perfectly okay with that.

[knotbin]

Apple's OpenAPI generator will soon be implemented into ATProtoKit, and I don't recall seeing lexicon-gen using that at all.

Is the plan to change the OpenAPI generator to be compatible with atproto lexicon instead of OpenAPI schemas (they are similar in many ways) or to just use the generator as-is and convert lexicon into OpenAPI schemas?

I personally would prefer the former (forking the OpenAPI generator and making it compatible with atproto lexicon) but curious what your thoughts are and what you're planning to do.

[MasterJ93]

The plan is to use the OpenAPI generator as-is and to use the "curated library" approach that Apple recommended me to do when using it for the AT Protocol. The OpenAPI generator would effectively replace the APIClientService struct for the most part. Forking the OpenAPI generator and tweaking would mean maintaining that repository, including getting the changes in the original repository, which I just don't have the bandwidth to do. Of course, if I had help with doing that, then I would be okay with doing the first option, but as long as I don't have a guarantee that others will pitch in to help with that, I'm uncomfortable in doing that. There's also the fact that the code is too complex to tweak it at this time to conform it to the AT Protocol.