Cedar Schema Annotations

[aaronjeline]

Rendered

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[john-h-kastner-aws]

If the main use case motivating this RFC is documentation, then I would prefer doc strings over annotations.

In general, I don't find the docs use case too compelling. Is there some other example you have in mind?

[aaronjeline]

No, the docs case was what was asked for by someone in the slack, and I was seeing if people preferred the more general approach

[john-h-kastner-aws]

With the custom schema syntax I do think we'll see more requests for annotations in the schema eventually. It would feel natural to use the same annotation mechanism in policies and schema.

[aaronjeline]

No reason we can't do both annotations and doc comments

[cdisselkoen]

In Rust, doc comments are actually just sugar for Rust's equivalent of annotations. (Specifically, sugar for the #[doc] attribute.) We could consider doing something similar. What that means for this RFC is that we could support just doc comments now, and later if we introduce general annotations we could have doc comments desugar into a special reserved annotation. Or, we could support general annotations now, and later we could introduce doc comments as a sugar on top. We don't have to worry about closing off one or the other path.

[hakanson]

For a doc comment syntax, I think //# is preferable to /# since backwards compatible with valid line comments, and similar to other syntaxes for overloading comments. An example is //! , the esbuild legal comment syntax to preserve in output files .

//! Copyright Cedar Contributors
//! SPDX-License-Identifier: Apache-2.0

[nakedible-p]

Comments below. All my opinions only! I don't want to say IMHO in every step, so I'm just writing them in assertive form.

• Schema is 50% validation, 50% documentation. Simply allowing a single line @doc("This is what this is for") is woefully inadequate to what is actually needed. If we look at GraphQL, OpenAPI, JSON Schema, Rustdoc, etc. then a documentation is usually of the form (regardless of actual syntax):

# Main explanation of the item

More descriptive explanation of the item, with much more detail in a multiline and multi paragraph format.

## Examples

How policies using this usually look.

## Warnings

Here's what to keep in mind when using the item.

• All items need documentation. Your syntax is meant to be compact in defining a set of actions so you don't need to repeat groups and context and attributes on every action, but you still need documentation for each item. Each attribute needs documentation. Each context item needs documentation.
• Think about formatting as well. Schema shouldn't depend on whitespace and you try to make it look nice, but do think how it will actually look when fully formatted out. Right now, you don't allow nearly enough extra commas, grouping parenthesis, etc. to make it natural to write something that isn't just a single line. For example, this is from a WIP schema using comments to document that I've tried to format as convenient and clear as possible:

  // Bootstrap actions that are allowed for both authenticated and enrolling terminals.
  action
    // Can establish an RPC connection
    //
    // This action merely gives permission to establish an RPC connection, but all
    // further access is checked separately.
    ptRpcConnect,

    // Can ask for new authentication tokens
    //
    // Enrolling terminals use this to ask for proper authentication tokens. Access
    // control for this is limited to a shared secret, where as the granted tokens
    // allow full access.
    ptTokenGrant
  in [
    ptBootstrapActions
  ] appliesTo {
    principal: [PaymentApplication, BootstrapApplication]
  } attributes {
    // Terminal hardware this application is running on
    hardware: Hardware,
  };

• Consider if it's better to have the documentation precede the item or to be after the item in question. Both approaches are seen. Python docstrings are after, as are OpenAPI and JSON Schema description fields, where as GraphQL, Rustdoc, etc. have documentation preceding.
• Whatever way is chosen, assume tools need to be able to generate HTML documentation from the schema, so strict syntax and programmatic way to parse that is crucial. Also consider that there is need for a top-level documentation - perhaps top level for a schema file, or just top-level for a certain namespace.

Perhaps a good example on how Cedar schemas with documentation should look like is to look at the GraphQL schema of GitHub: https://docs.github.com/public/schema.docs.graphql

And an example of what kind of documentation generator should exist for Cedar schemas is: https://graphdoc.io/

[max2me]

@aaronjeline, do you have an example of annotations in JSON format of schema?

[Swolebrain]

@nakedible-p
What would you say to the idea of adding cedar functionality to graphql/openAPI doc formats as opposed to re-creating what they have? This is all high-level in my mind but i imagine a world where im defining a graphql schema and i can specify something like:

query GetBooks @cedarAction('GetBooksWithAuthor', resource=Book) {
  books {
    title
    author {
      name
    }
  }
}

That way, as I define my queries and mutations i can define the actions and resources that those queries map to.

[nakedible-p]

You already have this "embed authentication in graphql schema" thing with AWS Amplify: https://docs.amplify.aws/javascript/build-a-backend/graphqlapi/customize-authorization-rules/ It's not Cedar, but a very similar idea. Probably one day it can be Cedar as well.

[nakedible-p]

Here is a basic JSON schema with descriptions: https://json-schema.org/learn/miscellaneous-examples#basic

[max2me]

Am I reading it correctly that this proposal would not support annotation individual attributes?

[mwhicks1]

I'd like to see this fleshed out to consider more use-cases. If doc strings are the only use-case, then a comment-based approach seems best to me. But we surely have other use-cases in mind, too, but we need to see them to evaluate possible designs.

[mwhicks1]

You have a number here as if this is the first of several examples, but it's the only one.

For doc comments, it makes more sense to me to define an opinionated literate format. This is what Rust, Java, etc. all do, and it's nicer to read and perhaps more natural to write (per your Alternative "Doc strings as comments"). But we could still also have arbitrary annotations to handle other use-cases (which it would be nice to see, here).

[max2me]

Can we please consider supporting annotation on individual attributes as well? This would allow integrating tools and services to embed data that helps authoring policies easier.

For example:

@doc("This entity defines our central user type")
entity User { 
    manager : User,

    @doc("Which team user belongs to")    
    @docLink("https://schemaDocs.example.com/User/team")
    team : String
};

[khieta]

I think #63, which proposes to support doc comments in schemas and policies, gives a better solution for the @doc(...) case -- do we still want schema annotations even if we already have schema doc comments?

[emina]

I'd like to see this fleshed out to consider more use-cases. If doc strings are the only use-case, then a comment-based approach seems best to me. But we surely have other use-cases in mind, too, but we need to see them to evaluate possible designs.

One (real customer) use case is to share the same schema among several organizations, while allowing UI builders to display only parts of the schema that are relevant to a specific organization. For example, entity types A and B should show up in UI builders only for members of the organization X. And the UI builder extracts this association from the annotation @VisibleTo("X") on entity types A and B.

[nakedible-p]

Anothere example from AWS Amplify land on GraphQL:

type Customer @model @auth(rules: [{ allow: public }]) {
  id: ID!
  name: String! @index(name: "byNameAndPhoneNumber", sortKeyFields: ["phoneNumber"], queryField: "customerByNameAndPhone")
  phoneNumber: String
  accountRepresentativeID: ID! @index
}

Even though such things are not directly applicable, it doesn't take much imagination to figure out similar things applied to a Cedar schema.

[john-h-kastner-aws]

Based on some recent discussion, we might want to support annotations on the namespace. I don't see a reason not to.

[shaobo-he-aws]

Can we please consider supporting annotation on individual attributes as well? This would allow integrating tools and services to embed data that helps authoring policies easier.

For example:

@doc("This entity defines our central user type")
entity User { 
    manager : User,

    @doc("Which team user belongs to")    
    @docLink("https://schemaDocs.example.com/User/team")
    team : String
};

Sure, we can. Just to double check. Are we looking into supporting entity attributes only? Note that attributes can also be found in context declarations and common type declarations. From the perspective of an implementation, it's better that we allow annotations where a record can legally show up.

[max2me]

I support this proposal as it will streamline the development of improved policy authoring tools while avoiding the need to separate configurations for schema meta data.

[john-h-kastner-aws]

Looks good. I support this extension

[andrewmwells-amazon]

Maybe we could use __annotations if this is a concern since it's more obviously special.

[shaobo-he-aws]

Maybe we can also use reserved __cedar::schema::annotations to be 100% secure.

[emina]

I support this proposal.

[micahhausler]

Should this be

Annotations := {Annotation}

[shaobo-he-aws]

Good catch. Will update it.