New top-level type for ids

[josh-newman]

Right now Courier records work nicely as resource models in Naptime, but Courier doesn't support non-primitive resource keys well.

The problem

It seems natural to use records for composite resource keys. For example, suppose we have a repositories.v1 resource with key :organization~:repositoryName. We can define a record:

record RepositoryId {
  organization: string
  repositoryName: string
}

and make requests like GET /repositories.v1/coursera~courier.

However, if we use this key in another model, it'll be serialized as an object, not as a URL-usable string like "coursera~courier". For example:

record PullRequest {
  title: string
  repositoryId: RepositoryId
}

may be serialized as:

{
  "title": "Example PR",
  "repositoryId": {
    "organization": "coursera",
    "repositoryName": "courier"
  }
}

For client convenience, it'd be nice to have this instead:

{
  "title": "Example PR",
  "repositoryId": "coursera~courier"
}

because then clients can easily pull out the repositoryId field and construct a repositories.v1 request.

A possible workaround right now is to define all ids as typeref RepositoryId = string, which produces the desired serialization, but requires language-specific coercion to preserve type safety.

Proposed solution

Proposed new syntax:

id RepositoryId {
  organization: string
  repositoryName: string
}

where id objects are string-serialized when used in other record or id objects, using one of the string codecs Courier already supports.