Schema linking

Topics on this page

• Linking schemas
• Linking entity types with ancestors
• Linking actions with ancestors
• Validation using external declarations

Starting with Cedar version 4.6, we introduced external entity types and actions. This allows a schema to declare entity types and actions without defining them. Schemas can resolve their external declarations by linking to other schemas that contain the corresponding definitions.

Linking takes any number of schemas and resolves each external declaration against a definition of the same name. The output of linking is another schema that may contain unresolved external declarations. The result does not depend on the order of the schemas, or on how they are grouped.

Linking schemas

Linking combines schemas and resolves external declarations with concrete definitions.

In the following example, the Documents schema declares User, and the Users schema defines it.

Documents schema

external entity User;
entity Document {
    owner: User,
};

Users schema

entity User;

Linked result

entity Document {
    owner: User,
};
entity User;

Schemas can also resolve each other’s declarations, as below:

Documents schema

external entity User;
entity Document {
    owner: User,
};

Users schema

external entity Document;
entity User {
    lastRead: Document,
};

Linked result

entity Document {
    owner: User,
};
entity User {
    lastRead: Document,
};

external declarations stay external when none of the linked schemas define it.

Documents schema

external entity User;
entity Document {
    owner: User,
};

Folders schema

external entity User;
entity Folder {
    owner: User,
};

Linked result

external entity User;
entity Document {
    owner: User,
};
entity Folder {
    owner: User,
};

An external action is resolved the same way.

Readers schema

entity User;
entity Document;
external action viewDocument;

Actions schema

external entity User;
external entity Document;
action viewDocument appliesTo {
    principal: User,
    resource: Document,
};

Linked result

entity Document;
entity User;
action viewDocument appliesTo {
    principal: User,
    resource: Document,
};

Linking entity types with ancestors

External entity types may declare parents, and linking combines them.

Documents schema

external entity Account;
external entity Folder in Account;

Shares schema

external entity Team;
external entity Folder in Team;

Linked result

external entity Account;
external entity Team;
external entity Folder in [Account, Team];

To avoid unsound validation behavior caused by linking, schema linking requires the ancestors of every defined entity type to remain unchanged after linking.

In the following example, Document is defined with Folder as its only ancestor. The Shares schema then places an Account above Folder, which would make Account an ancestor of Document as well. That would change a definition, so the link fails.

Documents schema

external entity Folder;
entity Document in Folder;

Shares schema

external entity Account;
external entity Folder in Account;

Linking actions with ancestors

Unlike the case of entity types, when linking schemas, all declarations of the same action must declare the same ancestors.

For example, linking the following schemas results in an error because the parents of viewDocument do not match.

Documents schema

external action viewDocument;

Shares schema

external action readActions;
external action viewDocument in readActions;

Validation using external declarations

A schema with external declarations is still useful for validation.

A schema can:

• Validate an entity of a defined type, even when its attributes, tags, or ancestors refer to external types.
• Validate an action, external or defined.
• Validate a request for a defined action.

A schema cannot:

• Validate policies.
• Validate an entity of an external type.
• Validate a request for an external action.