Writing rules with attributes

When roles are not enough

Three requirements from the newsroom show where that leads. Unpublished photos should not end up on personal laptops, so a picture editor may download one only on a device the Gazette manages. Some photos arrive under embargo: a picture of the regatta winner at the Riverside festival cannot be used before the result is announced, so no one may download it before its release time. And some wire photos are licensed only for certain countries, so they must not be downloaded from anywhere else.

Try writing the first requirement as a role. A "Picture editor on a managed device" role would have to be assigned to Omar while Omar sits at the newsroom laptop and removed when Omar opens a personal laptop at home. The device is a fact about the request, not about Omar, and roles describe people. The embargo fits even worse. It depends on which photo is requested and on the time, so a role that kept Omar away from the regatta photo would have to change at the moment of release, and every embargoed photo would need its own.

Even the differences that do describe people multiply quickly. Two desks and two contract types already make four versions of Picture editor. Add three licensing regions and there are twelve, before the device or the embargo has been expressed at all. The next requirement doubles the list again.

A rule says it once. "No one may download a photo before its embargo ends" covers every person, every photo and every moment, and it needs no change when a photographer joins or a new embargo arrives. The rule does not name anyone. It names properties of the person, the photo and the request, and the service looks up their values when each decision is made. Those properties are attributes.

Four kinds of attributes

Deciding what someone can do named four kinds of attributes: those of the subject, the resource, the action and the environment. For one request in the Gazette's picture library, Omar downloading photo 9001 from the Riverside festival album on a newsroom laptop, they look like this:

subject
  id: user-1187
  employment: staff
  desk: sports
  roles: ["picture-editor"]

resource: photo 9001
  status: approved
  embargo_until: 2026-06-13T22:00:00Z
  license_regions: ["worldwide"]
  uploaded_by: user-1450
  legal_hold: false

action
  name: photo.download

environment
  time: 2026-06-14T13:30:00Z
  device.managed: true
  network: newsroom
  country: US

The subject attributes describe Omar, account user-1187: a staff member on the sports desk who holds the Picture editor role where this photo lives. They change when Omar's job changes, which is not often.

The resource attributes describe photo 9001, and they change as the photo moves through the newsroom. A draft becomes approved and then published. An embargo passes. Raj, on the legal team, places a hold. Some resource attributes are useful mainly in comparison with the subject. uploaded_by holds Maya's account, user-1450. A rule can require that it differs from subject.id before anyone approves the photo, which turns the separation of duties from Administering roles safely into a single condition: photographers cannot approve their own pictures.

The action is usually just its name, but actions have properties too. photo.view and photo.download both read a photo, yet only one hands over the full-resolution file, which can then be copied anywhere. A rule can name one action, or apply to every action that shares a property, such as every action that changes a photo.

The environment attributes describe this one request: when it arrived, from what kind of device, over which network and from which country. The licensing requirement compares that country with the photo's license_regions. The Gazette's own pictures, such as Maya's, may be used anywhere, while a wire photo lists only the countries its agency allows. Unlike the subject and the photo, the environment can change between two requests a minute apart, when Omar closes the newsroom laptop and opens a personal one.

From a sentence to a rule

A good rule starts as a sentence the newsroom would agree with. Here is the device requirement, with the embargo added because both apply to downloads:

A picture editor may download a photo that has not been published yet, but only on a managed device. No one may download a photo before its embargo ends.

Each phrase becomes a test of one attribute. "A picture editor" means the subject's roles include Picture editor. "Not been published yet" means the photo's status is draft or approved. "On a managed device" means the request came from a managed device. "Before its embargo ends" compares the time of the request with the photo's embargo_until. In the small illustrative format this series uses for policy, the two sentences become three rules:

permit photo.download
  when "picture-editor" in subject.roles
   and resource.status in ["draft", "approved"]
   and environment.device.managed is true

permit photo.download
  when "picture-editor" in subject.roles
   and resource.status is "published"

forbid photo.download
  when environment.time is before resource.embargo_until

The second rule is easy to miss. The sentence restricts unpublished photos, which implies that picture editors may download published ones on any device, and a rule grants only what it says. The embargo became a forbid because it applies to everyone. If the Gazette later lets another role download photos, the embargo still holds without anyone remembering to repeat it.

The Gazette combines its rules the same way throughout this series. A request is allowed only when at least one permit matches and no forbid does. When nothing matches, the answer is no: the default deny from Designing permissions.

Here are three requests from Omar on the last afternoon of the festival. Photo 9001 is approved, and its embargo ended the night before. Photo 9002, the regatta winner, is in the same album, also approved, and embargoed until 14:00 UTC.

At 14:00 the third request succeeds, with no change to a role, a rule, or the code that asks the question. Only the time moved. Lena's requests never get that far. Lena holds Contributor, not Picture editor, so each permit fails at its first condition on any device and at any time.

Roles as attributes

The role did not disappear from the rules. It became one condition, "picture-editor" in subject.roles, alongside the photo's status and the device. This is how most systems combine roles with attributes. Roles still answer the question they are good at, what job a person does here, and Theo still assigns them in the usual way. Attributes answer a different question: under what conditions that job may be done.

The value of subject.roles is not a fixed list stored on Omar's account. It is worked out for each request from the assignments that apply where the photo lives. Photo 9001 is in the Sports library, where Omar's group, Sports desk editors, holds Picture editor, so the role is in the list. For photo 7310 in the News library, where Omar holds only Viewer, the same rules see ["viewer"], and neither permit can match on any device. The scoped assignments from Roles, assignments, and scope keep working. The rules read their result.

The role list shrinks as a result. Desk and contract type no longer need to be part of a role's name, because a rule can test subject.desk or subject.employment directly. The twelve versions of Picture editor become one role and a few rules, and the next requirement adds a rule instead of doubling the roles.

The cost is visibility. With roles alone, "who can download photo 9001?" has an answer you can read from the assignments: everyone who holds Picture editor in the Sports library. With rules, the honest answer is "those people, on a managed device, after the embargo, and for a wire photo from a licensed country", and whether a particular download succeeds depends on facts that exist only when the request arrives. Nobody can print a list of who has access, which makes audits and reviews harder. Rules need to stay few and readable, and they need tests that show which requests they refuse as well as which they allow.

Every rule here also trusted its inputs: that Omar really holds the role, that the laptop really is managed, that the embargo time is right. Where attributes come from asks where those values come from, and what a rule should do when one of them is missing.