[FEATURE] Shorthand way to define `service.ports`

[Abhishek9639]

Detailed description

Right now every published port has to be written as an object, even when the only thing I'm setting is the port number:

service:
  ports:
    web:
      port: 8080

targetPort already defaults to port, and protocol already defaults to TCP, so for the common case that nested object isn't carrying any information I didn't already give it. I keep writing three lines where one would do.

#196 added a string shorthand for files and volumes, and mentioned in passing that a few other properties could get the same treatment. service.ports feels like the most obvious next one:

service:
  ports:
    web: 8080

Same idea as the files shorthand: the full object form stays exactly as it is, this is just an extra accepted form for the simple single-port case. web: 8080 would mean the same thing as web: { port: 8080 }.

I think resources could take the same treatment (db: postgres instead of db: { type: postgres }), but that one is less clear-cut because the shorthand would drop class/id/params. I've left it as an open question at the bottom instead of bundling it in here.

Context

Most of the Score files I write are small, and the ports block is one of the spots where the boilerplate-to-content ratio is worst. A single published port is by far the common case, so this shorthand would cover the majority of real files people write.

It also lines up with the v1b1 to v1 ergonomics direction: keep the simple cases short, and only reach for the full object form when you actually need protocol or a different targetPort.

It's low risk for existing users. The object form keeps working unchanged, so nobody has to touch their files. This is purely an additional way to express the simple case, the same way files and volumes behave after #196.

Possible implementation

Same mechanism as #198: wrap the existing additionalProperties in a oneOf and add a scalar branch. For ports the scalar is an integer in the valid port range, and it maps to { port: <n> }.

"additionalProperties": {
  "oneOf": [
    { "$ref": "#/$defs/servicePort" },
    {
      "description": "Shorthand for the published port. Equivalent to '{ port: <value> }'.",
      "type": "integer",
      "minimum": 1,
      "maximum": 65535
    }
  ]
}

One nice property here: servicePort is an object and the shorthand is an integer, so the two oneOf branches can never both match. There's no ambiguity to guard against, which means this doesn't even need the not/required guard that files and volumes need to keep their deprecated array form out.

Rollout would follow the same path as #196:

• schema change here, plus a short example in samples/score-full.yaml
• score-go to parse the shorthand into the existing struct
• score-compose and score-k8s to handle it (should mostly fall out of the score-go change)

One alternative I considered and would lean against: also accepting a quoted string like "8080" to match how Compose writes ports. servicePort.port is an integer today, so keeping the shorthand an integer stays consistent and avoids two spellings of the same number.

Additional information

Prior art in the repo: #123 (map form for files/volumes) and #198 (the string shorthand this is modeled on).

The one thing I'd like to settle before writing a PR is whether resources should get the same shorthand:

resources:
  db: postgres

mapping to { type: postgres }. It reads well and matches the "I want a database of type X" framing in the README. Unlike ports, though, it loses information: class, id, params, and metadata all disappear in the short form (the same tradeoff as files only carrying content). So two things worth deciding:

• Do we want the resource shorthand in v1 at all, or keep this to service.ports for now?
• If we do want it, should the string be allowed to carry a class too (e.g. postgres.large), or strictly type only?

Happy to walk through this at a community meeting first. I can start on the service.ports PR right away if the approach looks right, and we can treat resources as a separate follow-up once the question above is settled.

[Abhishek9639]

Opened this as a follow-up to #196, since the files/volumes shorthand came out so clean. I'd like to take the service.ports part if it's free.

cc @mathieu-benoit @chris-stephenson, would scoping this PR to just service.ports work for you? Like #196 it's backward compatible, so I think it can stay in v1b1 rather than waiting on v1. Tell me if you'd rather hold it for the v1 batch instead.

@lekaf974, you're doing the score-go side for files/volumes in #198, and the ports change would basically reuse your approach. I'm happy to wait until that merges so I can follow the same pattern, or work in parallel if that's easier for you. Mainly I don't want to collide with your PR.

The one place I'd like a steer before I write anything is the resources question at the bottom of the issue. My instinct is to leave it out and keep this PR to ports only, but if you'd rather lock down the resources shape now, I can put both on the agenda for the next community meeting.

[mathieu-benoit]

Good idea and good call out, more consistencies. Let's keep this one open until this #196 is fully implemented. Assigning this to you, @Abhishek9639, in order for you to pick it up then.

Makes sense for ports and resources in v1b1, more simplifications for the Developers.

[Abhishek9639]

Thanks @mathieu-benoit. Happy to wait until #196 is fully in before I start, and good to hear resources is in scope too.

I'll keep this assigned and pick it up once the files/volumes shorthand has landed across score-go, score-compose and score-k8s, then follow the same pattern @lekaf974 sets there for both ports and resources.

One small thing I'll want to settle when I get to the resources part: whether the string form is type only (db: postgres) or can also carry a class (db: postgres.large). Fine to leave that until then, just noting it so it doesn't get lost.