Work-in-Progress Scala 3 Specification

@sjrd Has recently written this blogpost: Work-in-Progress Scala 3 Specification | The Scala Programming Language

Many thanks for all the tricky and well-needed work on this!

This thread is started for those who want to give general feedback on the spec for Scala 3.4, available here: Scala Language Specification | Scala 3.4

Feedback specific to the SIP on proper specification of match types goes here: Pre-SIP : Proper Specification for Match Types


I’m reading the outline spec 1.1 on Optional Braces
and I have a proposal:

It says that “{ can also be followed by an indented block, without needing an intervening :” and then says colon should not be optional because “conterproductive” because “several ways” etc. I get this when thinking about while do and for do (even if those examples are not given in the explaining text but perhaps should be?).

But the explaining text does not really explain why and when the colon is actually mandatory. Wouldn’t it be rather nice for the reader to get an explanition that the colon is there to open a template body? And also an example could be given with collective extensions that do not allow a colon (which surprises many that does not know that its not a template body allowing other than def members there).


The regular keywords in 1.2.1 come in different colors and shapes, but it is not explained why they have different style. What is the semantics of the different bold, green, rusty color, or just plain?

Also, I think it would be really useful if a pdf with the entire spec in one document can be generated? Or some other format where you can search the whole thing in one CTRL+F

1 Like

The github icon in the top left corner here gives when clicked:

404 - page not found Cannot find a valid ref in 3.4.x/spec

(but I guess that’s because it’s not in the scala repo yet)

1 Like

It would be nice if this were true…

But it’s not.


I really wish all the syntax idiosyncrasies and inconsistency would get fixed before some spec is written.

The current syntax (even I like it mostly) is chaos!

The colon is purely random.

Things like if-then and for-do make no sense. (A colon instead would make sense there…)

End markers are straight form hell, and there is no tooling support to deal with this nonsense…

In the year 2023 Unicode still doesn’t work in Scala.

It’s really sad that one of the best programming languages in the world has issues with syntax, of all things.

Please stay on topic. Pointing out facts is fine. Complaining that the syntax or semantics aren’t what you would have hoped for is a topic for another thread.


It was an example of how the explanation could be enhanced; could be more exhaustive:

  1. open a template body
  2. argument if single parameter
  3. …

Maybe this isn’t the feedback you were hoping for, but imho it’s spot on.

The topic is: “Work-in-Progress Scala 3 Specification”

One of my “complains” is that things that are (imho) sub-optimal are going through some specification processes. In my opinion this is premature as things could be improved before specifying them.

This would make things simpler in the end. Also it would avoid spending more effort on this than needed. (Nobody likes to do the same work twice!)

I’ve kept the actual “complains” extremely brief and used them just to make my point above. I also think going into the concrete details would be a different topic.

I’m very grateful that Scala gets an updated spec! Super hot topic out of my perspective. Thanks for putting effort into that!

But I also think that maybe some things (especially the syntax) aren’t ready for such a commitment.

In case there is interest in discussion this we can open a different thread of course (as this one is clearly for feedback on the current WIP spec draft). I’m not going to spam this one with more “complains”.

The syntax is the way it is. This specification effort is not here to change things. It documents what is already. If you want to see changes, we have a process for that: the Scala Improvement Process (SIP).

Even myself, while working on the spec, I really really wanted to alter what happens about match types. Well I wrote a SIP, and it is under review, like anyone could do. Writing the spec does not give me the power to change things in the process.


Is there a discussion underway somewhere? A ticket?

This would be an example of, “Just the facts, ma’am.”

On the comment that Scala 3 is not ripe enough for a spec, I would say that further progress also requires a specification, so we know what we’re arguing in favor of (or against). In Agile, this would be the moment when that deliverable is requested, even if progress was previously made without it.


I’m also interested in knowing what the issue supposedly is with Unicode, but let’s have that in a separate thread, please.

1 Like
  1. Do we have a separate issue tracker for specification or use a dotty tracker? Then, probably a new issue template for bug “specification” is needed.
  2. Have we a current ticket with the set of missing things for the full version (standard annotations, collection, reflection, staging, etc.) to understand what should be in specs and what not? How deep is the level of detail for which standard library API should be described?
  3. What belongs to the standard library? FFI, runtime reflection, IO: from one side, it should be in specs; from the other - it’s different in scala-jvm, scala-js, and native.

It’s the dotty tracker, since it’s the dotty codebase.

See our process at Apply `` to the Spec by Sporarum · Pull Request #16839 · lampepfl/dotty · GitHub and in particular the bit about the TODOreference directory. You can see here all the things we still need to integrate:

The standard library is mostly a library. It doesn’t belong in the language spec. There are a few critical elements of the standard library that are language-mandated because they have no corresponding source code, or their source code is not enough to describe how they behave. For example, Any has no source code. The FunctionN classes exist for arbitrary values of N. The primitive classes are full of methods whose body is fake in the source code. Et cetera. Run-time reflection and IO have nothing special, so they’re not in the spec.

FFI is not a thing in Scala; we have interoperability at the object model level instead, not interfaces at the function level. Interoperability is not currently in the spec, but maybe one day we’ll add it (and yes, that will mean with variants for JVM, JS and Native).


It was just the syntax highlighter being overly enthusiastic. I removed the colors in those lists, since they were not meaningful.

Fixed as well.


Sorry if I misunderstood the scope of this discussion.

My impression was that “writing the spec” includes “developing the spec”.

Well, that’s most likely another misunderstanding on my side, but I thought that things can be considered still WIP, until they got “officially speced”.

Now you’re saying that changing the not speced stuff (which wasn’t the result of SIPs btw.) requires process…

Please don’t get me wrong, I’m not trying “to rewrite history” here. I’m very satisfied with what we have now! But I thought that there is room for improvements in some details. And my understanding is that it would be better to include the possible outcome before writing some spec and “making things official”.

I didn’t say that.

I think most things are ripe for a spec.

My concrete concerns were about some syntax details. Not a big deal imho, as syntax can be easily rewriten as we know.

Also there is enough other stuff to spec, so I don’t see a big issue in postponing the syntax part.

Just one reason why I think it would be worth to iterate this once more: I for my part love the indentation based syntax. But it has issues with tooling. The tooling people say it’s very hard to deal with the new syntax. So some simplifications and improvements that would make the lives of tooling authors easier would be likely highly welcome, not only for them, but also for end-users like me when the tooling improves. (Just did some Python the other day, and there is really quite some room for improvement in the Scala tooling. In Python the IDE is really smart about the indentation. In Scala, well, it’s something between “could be better” and “it hangs MetaLS”… Iterating once more on that, and rethinking some details while having IDEs in mind could make a significant difference here, imho.)

I’m sorry if my first post in this thread was not clear on what this thread is meant for. I will try to explain better:

Scala 3.3.1 is as it is, defined by its compiler and documented for pedagogical reasons (for learner and users of the language).

The coming spec of Scala 3 is supposed to be a documentation of the language as it is (at the point of 3.4), not for pedagogical reasons, but for reasons of unambiguously defining what it means. Being unambiguous is difficult (and that word unamb… is also difficult for me to spell :)). So we aim at using as precise natural language as good as we can while still being readable to humans. We should write in a way that tries to minimize the risk that two persons interpret the meaning of the text describing a certain language construct in different ways. “The meaning” of a language construct is what happens when a Scala 3 program with that construct is executed.

@sjrd has started the tricky work (based on the Scala 2 spec) to come up with a spec for Scala 3. This thread is about giving feedback on that on-going work, in terms of how the spec can better describe the language as is, in terms of being both a reasonably unambiguous and human readable description of what the language means.

In shorter terms: Write here feedback that can help to make the specification of what Scala 3.4 means ( i.e. how it works when compiled by the Scala 3.4 compiler) more readable and less ambiguous (and also more complete, but completeness is another tricky thing, esp. when using natural language, so I’m not opening that can of worms :slight_smile: …)

Again in other words: A language spec can be seen as a requirement specification for a compiler of that language. This thread is not supposed to come up with new or changed requirements, but supposed to open up for the community to provide some help in the on-going process of re-engineering the up-to-now unspecified requirements of the de-facto implementation of our beloved compiler.

Hope this helped.


I mean, in practice that’s never really been true, even for Scala 2. A fair amount of Scala has always been “It works this way because that’s what the compiler does”, with PRs and SIPs focused more on that rather than on the spec. (And there have always been some grumbles about that.) And it’s certainly not been true of Scala 3, where we’ve had pieces of spec but nothing complete and well-organized.

This project is moving us towards the day where that could hypothetically be true someday, with SIPs focused mainly on the spec. But we have to get to the point of having a comprehensive, descriptive document of the real state of the world (as SĂ©bastien is making progress on here) before we could realistically think in those terms.


This makes sense.

But than I wouldn’t call it “specification”.

Spec sounds so official, and of course first of all authoritative.

But it seems it’s just a rewording in natural language of some implementation details of the compiler at some point X in time. What’s “authoritative” is still solely the implementation (which of course changes constantly).

I don’t say having some documentation of how things were thought to work at some time doesn’t provide value. But it’s not “a spec”, it’s merely some docs than. I would call it like so. Otherwise other people could read (like me) more into this term as it supposedly stands for according to this clarifications here.

This would also make any other “grumbles about that” disappear I think. Clear wording matters!

Of course I highly welcome such kind of documentation. It could become the base for some language specification in the future.

I think we must still be able to call it a “specification”, even if it is not a fully proved formalization using a fully formalized meta-language… One meaning of “specification” is something that we have written in a way that is not too ambiguous and represents what we have decided to be required of the thing that we specify. (here “thing” = a member of the set of all possible “correct” compilers for our beloved language)

1 Like