It might be better if capability constraints / caveats / extras had their own named field

[Gozala]

Right now spec defines structure of capability as follows

A JSON capability MUST include the with and can fields and MAY have additional fields needed to describe the capability.

{
 "with": $RESOURCE,
 "can": $ABILITY
}

I have been running into various limitations that I would like to surface

1. Capturing constraints in types

Right now capability type in TS can be expressed more or less as:

export interface Capability<Can extends Ability = Ability, With extends Resource = Resource> {
  with: With
  can: Can
}

export type Ability = `${string}/${string}` | "*"
export type Resource = `${string}:${string}`

But there is no simple way to capture capability constraints as there is no placeholder field for them. So in TS I find myself resorting to types like:

type Constraints<C extends Capability> = Omit<C, 'with'|'can'>

It would have been a lot simpler if constraints were under dedicated field e.g.

export interface Capability<Can extends Ability = Ability, With extends Resource = Resource, Caveats = unknown> {
  with: With
  can: Can
  caveats?: Caveats  
}

2. IPLD Schemas

In less powerful type systems like IPLD schemas you simply cant specify open ended types with arbitrary fields so you either have to treat Capability as a key value map (and have uphold with and can invariants out of bound) or just add a comment like

type Capability struct {
  with Resource
  can Ability
  -- can have arbitrary other fields
}

Unfortunately comments aren't going to help with schema validators (as they structs must match exactly) or parser generators.

On the other hand if constraints had dedicated field it would be possible to express that without any problems

type Capability struct {
  with Resource
  can Ability
  caveats optional Any
}

[expede]

@Gozala Thanks for surfacing this! I'm not totally clear on why there's no good way to type this in TS. It's true that the caveats are KV by design. For the required fields, is it not possible to use intersection types in TypeScript? We have no problem capturing this information in the Haskell or Rust type systems, but we also have an actual parser in between rather than relying directly on JSON 🤔

[expede]

I find myself resorting to types like
type Constraints<C extends Capability> = Omit<C, 'with'|'can'>

For example, is this not isomorphic to subtyping (with either intersection or subclass). For example:

interface Capability {
  with: Resource
  can: Ability
}

interface MyFields {
  foo: string
  bar: number
}

type MyCap = Capability & MyFields

Having it built up from parts like this lets you avoid the Omit, no?

Is this not isomorphic to the following?

interface Capability<cav> {
  with: Resource
  can: Ability
  caveats?: cav
}

interface MyFields {
  foo: string
  bar: number
}

type MyCap = Capability<MyFields>

The intersection version still lets you express precisely that you will not have any capabilities (without needing to pass in a null/undefined), and express arbitrary parts, and lets those be further subtyped:

type DownstreamCap = Capability & MyFields & MoreExtendedFields & EvenMoreExtended

If you prefer generics, I believe that you can wrap the same around this:

interface CapabilityBase {
  with: Resource
  can: Ability
}

interface MyFields {
  foo: string
  bar: number
}

type Cap<cav> = CapabilityBase & cav

const foo: Cap<MyFields> = {with: "foo:bar", can: "baz/quux", foo: "hi", bar: 42}

// Perhaps worth noting:
// CapabilityBase ~ Cap<{}>
//
// Which admittedly is different your initial version, which always looks something like
// Capability<undefined>

[expede]

Mentioned this in Discord: I think I missed that this is possibly a constraint of IPLD, not TS! Reviewing the IPLD the docs now! Yes, we definitely want to support this in IPLD

[expede]

Ah, I see. IPLD does not have type variables at all, hence your comment about needing to treat it as an otherwise untyped KV map.

@Gozala quick clarification purely for my own understanding: in JSON parsers, you can run multiple parsers over the same data to extract data (e.g. the standard with/can fields, and then the additional fields). I'm guessing since IPLD need to be able to roundtrip, you need to force them into the same representation. Using the raw KV maps, you need to handle validating that shape outside of IPLD, correct?

I'm guessing that you've already started on this. We should create a ucan-wg/ucan-ipld spec. It would probably be good to also maintain a GraphQL schema, too.

[Gozala]

To be clear it is not that it's impossible in TS it's just bit more annoying to deal with. You are right when you do know the types of the constraints you can easily intersect types and be done however it's bit more trick in cases where you have generic function working with capabilities like in the example below, there intersection types and destructuring starts to confuse TS inference in various ways (writing UCAN based RPC layer attempting to capture types I end up writing too many complex types that I think could have been avoided)

const execute = <Constraints>({ can, with as res, ...capabilities }: Capability & Constraints) => { ... }

[Gozala]

@Gozala quick clarification purely for my own understanding: in JSON parsers, you can run multiple parsers over the same data to extract data (e.g. the standard with/can fields, and then the additional fields). I'm guessing since IPLD need to be able to roundtrip, you need to force them into the same representation. Using the raw KV maps, you need to handle validating that shape outside of IPLD, correct?

Yeah it has no generics but then also when e.g. validate struct with a schema if underlying data has more fields it will not validate. alternatively you could type capability not as a struct but a KV map in which case it would validate but then it may not have can / with.

Although your comment got me an idea that in IPLD I don't have to map 1:1 with JSON structure e.g. I could type it as:

type Capability struct {
  with Resource
  can Ability
  caveats optional {String: Any}
}

When formatting it into JWT caveats could be hoisted into capability. Not ideal but no longer impossible