recap SPEC 0.1.0

[cpard]

Aliases

I'd suggest to make the Aliases documentation a bit more clear.

• Write a few lines for why aliases are important, a practical use case here would be amazing and it would help people to quickly realize why Aliases are supported.
• It might be just me but I found the example a little bit unclear. Previous and Next could be the same type, they are pages after all. From quickly going through the example it seems like Next is of type Page while Previous is of type int. Does the alias make Previous and Next to have the same type? If yes then what the type:int for Previous means?
• Also the cyclical references together with references under Aliases is also confusing. Is the cyclical references a desirable by product of aliases?
• Cyclic references is another case where an example of a practical use case would help a lot.

Logical Types

My understanding here is that aliases can be used to construct logical types, but this is not very obvious with the current wording.
Also, the assignment of "timestamp64" to the alias keyword is mentioned but it doesn't appear in the code snippet.

By the way, the above become less of an issue when someone continues reading the spec and goes through the supported aliases.
I think a small editing and slight restructuring of the document will make it much more easier to consume.

Overall it's a great spec!

[criccomini]

Thanks! I've addressed some of this in a recent PR. I'll address the rest shortly.

[criccomini]

Okay, I've updated the spec a bit. I've tried to address the logical type feedback and some of the alias stuff as well:

https://github.com/recap-cloud/recap/blob/main/SPEC.md