Ability to specify comments for scopes when going JSON -> Cedar

[max2me]

Category

User level API features/changes

Describe the feature you'd like to request

I would like to have ability to provide comments for policy scopes like these:

permit(
    principal in UserGroup::"1234-abcde-fghijkl-5678", // "Finance"
    action,
    resource in Category::"a83b5298-0633-460f-ad0b-311ff23acd2b" // Critical resources
);

Describe alternatives you've considered

• Including comments like this into annotations (pollutes annotations and leaves valuable info further away from the context)
• Not including human-friendly names
• Using human-friendly names instead of unique non-recoverably IDs

Additional context

No response

Is this something that you'd be interested in working on?

• 👋 I may be able to implement this feature request
• ⚠️ This feature might incur a breaking change

[john-h-kastner-aws]

Some additional context which I think makes this feature request more compelling.

We explicitly recommend using this sort of unique identifier instead of human readable names. The linked example further recommends using comments to include a human readable alternative in exactly this way. It then seems odd that you can't annotate the policy EST in the same way.

I'm still not convinced we should be adding comments into the EST. You want to associate some additional structured data with entities, so perhaps we should just enable that directly by giving entities a "friendly" identifier in additional to their unique identifier.

[john-h-kastner-aws]

I wrote an RFC for adding doc-comments to Cedar which would support this use case: cedar-policy/rfcs#63

[john-h-kastner-aws]

Noting that with #1233 you could use the entity literal substitution to programmatically replace the uuids with a human readable representation before displaying policies to humans.