core: decide on the words ergo policies and reports use

@tooky

When we started ergo, we picked words for things as we went: "policy", "requirement", "check", "subject" and so on. They worked well enough to get going, but nobody sat down and chose them on purpose. ergo is still early, so now is a good time to ask whether they're the right ones, before more people start writing policies with them.

This issue is a place to talk about that. Any thought is welcome, from "this word confuses me" to "the whole shape should be different".

The words we use today

Here's the example from the README:

requirements:
  prod_deploy:
    subject_type: deployment
    from: [deployments]
    id: [id]
    applies_to:
      is_prod:
        op: equals
        path: [environment]
        value: prod
    checks:
      approved:
        description: Someone approved the deployment
        op: non_empty_string
        path: [approved_by]

In the policy:

policy: the file that holds the requirements and asks ergo for a report
requirement: one thing that must be true, like prod_deploy
subject: one of the things a requirement is about, like a deployment, with subject_type, from and id
applies_to: the filters that pick which subjects the requirement covers
check: one rule each subject must pass, like approved
op: the operator a check or filter uses, like equals or non_empty_string

In the report:

compliant: the overall yes or no
satisfied: whether a requirement passed
results: one row per subject and check
cause: why a check failed, like absent or value
violations: the failed rows that are real problems
the checks ergo adds itself: $well_formed, $min_subjects and $applies

The `requirements` wrapper

Every policy starts with a requirements: key that holds a map of requirements. It doesn't tell the reader much, and it's there mostly because OPA turns the YAML file into data.requirements. Could we drop it, so the top-level keys are the requirements themselves? Or go further and have one requirement per file?

An idea from @tooky: start with what the policy means

Tooky suggested a policy that opens with the requirement in plain words and fills in the details after, so you can understand it before reading how it's checked:

prod_deploy:
  description: Production deployments must be approved by someone
  subject: deployment
  where:
    is_prod: { environment: { equals: prod } }

  requirements:
    approved:
      description: Someone approved the deployment
      approved_by: { is: present }

subjects:
  deployment:
    from: deployments
    id: id

Compared with today, this:

gives the top-level requirement its own description
calls the filters where instead of applies_to
calls the checks requirements, which reads more like what a control owner would write
moves from and id into a separate subjects section, so several requirements can share one definition of "deployment"
writes conditions as field: { operator: value } instead of op, path and value

Some questions it raises: how would we write a path into nested fields, or a field whose name is also an operator name? And if checks become "requirements", what do we call the top level?

Things worth asking

Do these words mean the same thing to an engineer, a control owner and an auditor? Those are the people we want reading ergo policies and reports.
Do any of them clash with words people already use in compliance, in OPA, or at Kosli? "Policy" means something in OPA already, and "control" or "evidence" might fit some ideas better.
Is the shape right? For example, should a requirement hold its checks the way it does now, or should they be split differently?
Are there words we're missing, or words we use for two different things?

If you'd rename something, say what you'd call it and why, ideally with an example of how a policy or report would read with your word.

ergo is still alpha, so breaking changes are fine if they make it clearer.

@mbevc1

@mbevc1 @meekrosoft @pbeckham @jumboduck @JonJagger @ToreMerkely everyone's input is welcome here :) feel free to tag other people

Tooky's separate subjects section would be a good home for the subject's plural:

subjects:
  deployment:
    from: deployments
    id: id
  person:
    from: people
    id: email
    plural: people

The checks ergo adds need it. #116 asked for plain descriptions like "At least 2 deployments are required", but a plural guessed from the word's ending turns person into "persons", and English has too many exceptions to list (child, index, criterion, analysis...). So #119 says "The deployment count is at least 2" for now, which reads right for any word. With a plural on the subject, every requirement using it could say "At least 2 people are required" instead.

plural would be optional, with a default for common English words: an -s, -x, -z, -ch or -sh ending takes -es, a consonant before -y becomes -ies, and anything else takes -s. That covers deployment, batch, repository and pull request. The author only writes plural for an irregular word, and the default rules are short enough for any implementation to copy.

If subjects get their own section, a subject's name can't be empty or only whitespace, the same as subject_type today (#121). JSON and YAML both allow "" as a key, so the check on the subjects section needs that rule, next to "every requirement's subject exists".

core: describe the checks ergo adds in plain words (#119)

core: fail $well_formed when subject_type is empty or only whitespace (…

Changes we'd like in ergo

Several of these are already possible in a Rego policy, by building the requirements or the document in Rego. They are gaps for policies written as YAML or JSON data.

Words and shape

SUB-ISSUE core: decide how policies and reports carry extra data, like notes on checks and labels on inputs #114: Add a control id, title and description at the top level, with the requirement's fields beside them. Keep requirements: only for a control with more than one.
- DEV-0501, segregation of duties: a change must not be deployed by the person who made it.
  
  Today the control text only fits in a comment, and a control with one requirement still needs the wrapper and a name for the requirement:
```
# DEV-0501: A change must not be deployed by the person who made it.
requirements:
  segregation_of_duties:
    subject_type: production deployment
    from: [deployments]
    ...
```
  With the control at the top level, the text is part of the policy and can appear in the report:
```
id: DEV-0501
title: Segregation of duties
description: A change must not be deployed by the person who made it.
subject_type: production deployment
from: [deployments]
...
```
- DEV-0401: security testing, code review and vulnerability scanning are done, and vulnerabilities are fixed in time.
  
  A control that needs several requirements keeps them under requirements::
```
id: DEV-0401
title: Security testing and code review
description: Security testing, code review and vulnerability scanning are done, and vulnerabilities are fixed within a deadline set by their severity.
requirements:
  security_scans_performed:
    ...
  code_reviewed:
    ...
  vulnerabilities_remediated_in_time:
    ...
```
- A Rego policy can put these in OPA's # METADATA annotations. See also core: decide how policies and reports carry extra data, like notes on checks and labels on inputs #114.

OPEN: Add a shared subjects section that can hold filters.

DEV-0502: new features need approval before they reach production.

DEV-0403: testing must be finished before production.

Today DEV-0102, DEV-0504, DEV-0502 and DEV-0703 all repeat the same subject and filters:

subject_type: production deployment
from: [deployments]
id: [id]
applies_to:
  production: { op: equals, path: [environment], value: prod }
  new_development: { op: equals, path: [change_type], value: new_development }

Defined once, each control names it:

subjects:
  new_development_in_production:
    from: [deployments]
    id: [id]
    applies_to:
      production: { op: equals, path: [environment], value: prod }
      new_development: { op: equals, path: [change_type], value: new_development }

id: DEV-0502
subject: new_development_in_production

DEFERRED: Add dotted paths.
- DEV-0405: a data migration must be shown to be complete and correct.
```
# today
left: [migration_test, migrated_records]
right: [migration_test, source_records]
# proposed
left: migration_test.migrated_records
right: migration_test.source_records
```
  Keys that contain a dot, like app.kubernetes.io/name, need an escape, for example metadata.labels."app.kubernetes.io/name".

Operators

SUB-ISSUE core: add a within operator that checks a time is at most N days before another #140: Add a date arithmetic operator, like within: {days: N}, with N from params or a lookup by severity.

DEV-0401: vulnerabilities must be fixed within a deadline set by their severity.

DEV-0705: security tests must run at regular intervals.

Today a Rego wrapper computes a deadline for each subject, so a YAML policy can't express it:

with_deadline(v) := object.union(v, {"remediate_by": time.format(time.add_date(
    time.parse_rfc3339_ns(v.first_seen), 0, 0, data.params.sla_days[v.severity]))})

within_sla:
  op: compare_time
  left: [remediate_by]
  right: [$$input, evaluated_at]
  cmp: gte

With the operator, the YAML holds the rule, and the number of days can depend on a field of the subject:

within_sla:
  description: The vulnerability is still within the remediation timeframe for its severity
  op: within
  path: [first_seen]
  of: [$$input, evaluated_at]
  days: { lookup: [$$params, sla_days], key: [severity] }

ALREADY SUPPORTED: Add a not_in operator.
- DEV-0406: acceptance testing is done by someone outside the development team.
  
  Today it takes all and compare:
```
independent_tester:
  op: all
  path: [$$input, artifact, developers]
  check: { op: compare, left: [], right: [$$input, artifact, attestations, uat, tested_by], cmp: ne }
```
  which the report renders as every $$input.artifact.developers: $$input.artifact.developers[] ne $$input.artifact.attestations.uat.tested_by. With not_in:
```
independent_tester:
  description: The tester is not on the development team
  op: not_in
  path: [tested_by]
  values: { ref: [$$input, artifact, developers] }
```
  which could render as tested_by not in $$input.artifact.developers.

Scope and reuse

SUB-ISSUE core: skip a requirement, and report it as not applicable, when a condition on the input doesn't hold #141: Add a way to skip a requirement on an input-level condition. In Rego, leave the requirement out of requirements.
- DEV-0403: new features must be tested.
  
  Today each test run is filtered on the deployment's type, and min_subjects: 0 keeps a normal change from failing. As a side effect, an empty required_tests param also passes:
```
min_subjects: 0
applies_to:
  new_development: { op: equals, path: [$$input, deployment, change_type], value: new_development }
```
  A requirement-level condition would skip the whole requirement, report it as not applicable, and keep min_subjects at 1:
```
when:
  new_development: { op: equals, path: [$$input, deployment, change_type], value: new_development }
```

DEFERRED: Add reusable checks or requirements with parameters. In Rego, a function that returns a requirement already does this, for example suite_requirement(name) called once per suite.

DEV-0502: the business owner approves, with sign-off from QA and development.

Today the check is written three times, once per role. With a list of values:

signed_off:
  description: "$role signed it off before it went to production"
  for_each: { role: [business_owner, qa, development] }
  op: any
  path: [approvals]
  check:
    op: any_of
    options:
      before_deploy:
        - { op: equals, path: [role], value: $role }
        - { op: equals, path: [decision], value: approved }
        - { op: compare_time, left: [approved_at], right: [$deploy, started_at], cmp: lt }

Each role would still get its own row in the report.

DEV-0103 and DEV-0102: the same impact analysis rule, once for normal changes and once for new features.

Today DEV-0103 is a copy of DEV-0102 with new_development replaced by normal. With a parameterized requirement:

# impact_analysis.yaml
impact_analysis_approved:
  params: [change_type]
  applies_to:
    in_scope: { op: equals, path: [change_type], value: $change_type }
  ...

id: DEV-0103
uses: impact_analysis_approved
with: { change_type: normal }

SUB-ISSUE core: let from iterate at any step and name what it iterates over #52: Add a way to name a single object without turning its fields into subjects. See also core: let from iterate at any step and name what it iterates over #52.
- DEV-0406: acceptance testing is documented and approved before production.
  
  Today each_as on the uat object makes each of its fields a subject, so a nested check has to reach the tester through $$input:
```
from: [artifact, attestations, uat]
...
right: [$$input, artifact, attestations, uat, tested_by]
```
  With a name for the single object:
```
from: [artifact, attestations, uat, { as: uat }]
...
right: [$uat, tested_by]
```

Report

SUB-ISSUE core: show which item failed in the rows of all and any checks #68: Say which item failed in all / any (core: show which item failed in the rows of all and any checks #68).
- DEV-0501: a change must not be deployed by the person who made it.
  
  Today the violation lists every commit, and the reader has to find bob's:
```
"inputs": [
  { "name": "pull_requests[].commits", "value": [[{ "sha": "b1", "author": "ann" }, { "sha": "b2", "author": "bob" }]] },
  { "name": "$deploy.deployed_by", "value": "bob" }
]
```
  With the failing items named:
```
"failed_items": [
  { "path": "pull_requests[0].commits[1]", "value": { "sha": "b2", "author": "bob" } }
]
```
ALREADY SUPPORTED: Leave $applies failures out of violations, or label them as a scope problem.
- DEV-0405: applies to new features and to changes that migrate data.
  
  Today a deployment that doesn't say whether it migrates data appears next to the real failures:
```
{ "subject": { "id": "dep-4" }, "check": "$applies", "cause": "absent" }
```
  It still has to fail the control, but under its own heading:
```
"scope_unknown": [
  { "subject": { "id": "dep-4" }, "inputs": [{ "name": "includes_data_migration", "value": null }] }
]
```

@ToreMerkely

@ToreMerkely I went through each request against main. Three of them work today, two I'd leave for now, and the rest go to issues of their own so this one can stay about words and shape.

Already works

not_in for DEV-0406. excludes with a ref does it in one check:

independent_tester:
  description: The tester is not on the development team
  op: excludes
  path: [$$input, artifact, developers]
  value: { ref: [$$input, artifact, attestations, uat, tested_by] }

With developers: [ann, bob] and tested_by: bob, it fails with:

{
  "check": "independent_tester",
  "expression": "not contains($$input.artifact.developers, $$input.artifact.attestations.uat.tested_by)",
  "inputs": [
    { "name": "$$input.artifact.developers", "value": ["ann", "bob"] },
    { "name": "$$input.artifact.attestations.uat.tested_by", "value": "bob" }
  ],
  "cause": "value"
}

That also removes the need to name the uat object for this control.

DEV-0102 and DEV-0103 as one requirement. Read the change type from the params, and ship the same policy with two params files:

applies_to:
  in_scope: { op: equals, path: [change_type], value: { ref: [$$params, change_type] } }

With deployments d1 (normal) and d2 (new_development), both failing, change_type: new_development reports d2 and change_type: normal reports d1.

$applies failures in violations. violations already leaves out the subjects that are simply out of scope, the $applies rows with cause value. It only keeps the ones where the filter couldn't be read. For DEV-0405, with dep-1 saying includes_data_migration: false and dep-4 not saying anything:

[null,    "$min_subjects", "value"]
["dep-4", "$applies",      "absent"]

dep-1 isn't there. dep-4 has to stay, because the control fails because of it, and without that row nothing would say which deployment is missing the field. A reporting tool can put these rows under their own heading already: their check is $applies and their cause isn't value.

Not now

Dotted paths. Quoting keys the way the report does, like metadata.labels."app.kubernetes.io/name", would work, but then every policy path is a string ergo has to parse, with its own rules for quotes, escapes inside quotes, and list indexes like xs.0 against the key xs."0". Every implementation would have to parse them exactly the same way, or the same policy would read different fields. The report only writes that form, it never reads it back. In YAML the list form is about as short, and there's nothing to parse: [migration_test, migrated_records]. So I'd hold off until the list form gets in someone's way.

Reuse with for_each and uses / with. Six of your new-feature controls have a normal-change twin with the same rule (0102/0103, 0403/0404, 0406/0407, 0409/0410, 0502/0503, 0504/0505). Each pair is one policy with value: {ref: [$$params, change_type]} and two params files, as above. 0703 and 0704 differ in what they require, so they stay two policies anyway. The three DEV-0502 sign-offs give the same three rows as three checks written out. Sharing requirements between controls would mean one policy file including another, which ergo has nothing for. So I'd hold off until a control needs more than params.

Sections next to `requirements`

A shared subjects section, and maybe a section for the control's id, title and description, would sit next to requirements in the same file:

subjects:
  new_development_in_production: ...
requirements:
  impact_analysis_approved: { subject: new_development_in_production, ... }

The file's top-level object is the policy, with no root element around it. An implementation in another language reads it as one object. In Rego, OPA loads each section into data next to everything else, and passing data whole doesn't compile, because the calling rule is part of it. So ergo.report(input, data.requirements) stays as it is, and ergo reads data.subjects itself, the way it already reads data.params. A requirement whose subject isn't there fails $well_formed. A policy built in Rego would pass its sections explicitly, as ergo.report_with_params does for params.

As with params, the policy that calls ergo then can't live in a package called subjects, or under one.

Moved elsewhere

Which item failed in all / any: core: show which item failed in the rows of all and any checks #68, with DEV-0501 added as a case.
Control id, title and description: core: decide how policies and reports carry extra data, like notes on checks and labels on inputs #114, which asks where notes like a link to a control go. id beside the requirement's fields would clash with the requirement's own id, the path to the subject's id, so they'd need a section of their own (above).
The deadline looked up by severity: needs refs that start from the subject, the second step of core: let a check read a value from a path with ref #63.
Naming a single object: core: let from iterate at any step and name what it iterates over #52.
within: core: add a within operator that checks a time is at most N days before another #140
when: core: skip a requirement, and report it as not applicable, when a condition on the input doesn't hold #141

The subjects section itself stays here.

A change to the sections part above: rather than have ergo read data.subjects itself, I'd make ergo.report a pure function that gets everything it uses as arguments:

ergo.report(input, policy, params)

policy holds requirements, subjects and any section added later, and a section that isn't there counts as empty. This replaces ergo.report_with_params. ergo.report stops reading data.params, which is the only thing it reads from data today, so the policy that calls it can live in any package, params included.

The catch is Rego's: if an argument is undefined, the whole report is undefined, with no rows to say why. A file with no subjects:, or a run with no params, would do that. So the policy that calls ergo gives each one a default:

package policy

import data.ergo

default params := {}

params := data.params

default subjects := {}

subjects := data.subjects

default requirements := {}

requirements := data.requirements

report := ergo.report(input, {"subjects": subjects, "requirements": requirements}, params)

Each default still fails closed. With no params, every $$params read fails as absent. With no subjects, a requirement that names one fails $well_formed. With no requirements, say a file that spells it requirments:, the policy has nothing to check, and that's never compliant. This wrapper is the same for every YAML policy, so the README can show it once.

It breaks every existing call. ergo.report(input, requirements) becomes ergo.report(input, {"requirements": requirements}, params).

One more for the list: "satisfied" means two different things in a report.

satisfied on a requirement is true or false: whether the whole requirement is met.
"cause": "satisfied" on a row is what a passing check gets, next to value, absent, null and the rest for failures.

So a report can say both of these, about different levels:

"requirements": { "prod_deploy": { "satisfied": true, ... } }

{ "check": "$min_subjects", "passed": true, "cause": "satisfied" }

People reading a report mix them up. The glossary above also says cause is "why a check failed", but passing rows have one too. Maybe a passing row's cause should be called something else, or the requirement field should be renamed, for example met.

🤖 Generated with Claude Code

core: list the items that failed an all or any check (#145)

core: let requirements and checks carry a description and meta (#151)

For the control text Tore asked for: since #151, a requirement can have a description, and a meta object for anything else, like a control id or title. Both are copied into the report. #114 has DEV-0501 written that way. A control with one requirement still needs the requirements: wrapper and a name for the requirement, and fields for the whole policy still wait on the shape decided here.

🤖 Generated with Claude Code

@tooky

Perhaps I'm thinking along the lines of @tooky 's suggestion, but subject_type feel awkward wording, but I don't have a better suggestion yet. I need to think more about this and try different scenarios 😄

@mbevc1

@mbevc1 I think we will drop subject_type altogether.

subjects:
  deployment:
    description: ...
    id: ...
    from: ...
requirements:
  my_req:
    subject: deployment
    ...

I am convinced about this new shape. Define subjects separately, refer to them in the requirements.

No more subject_type 🥳

@jbpros

@jbpros makes sense and reads better now 🚀

core: define subjects once in the policy and name them from requirements

core: take the policy and params as arguments to ergo.report (#163)

core: define subjects once in the policy and name them from requirements

core: define subjects once in the policy and name them from requireme…

How a single check or filter is written has moved to #174: one-line sentences like approved_by must not be empty inside the YAML skeleton being settled here. Tooky's field: { operator: value } and Peter's selector / must / contain examples are answered there. This issue stays about the words and the shape around the checks.

spec: add requirements, scope, statuses, row order and violations

Navigation Menu

Repository navigation

core: decide on the words ergo policies and reports use #113

The words we use today

The `requirements` wrapper

An idea from @tooky: start with what the policy means

Things worth asking

Changes we'd like in ergo

Words and shape

Operators

Scope and reuse

Report

Already works

Not now

Sections next to `requirements`

Moved elsewhere

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

core: decide on the words ergo policies and reports use #113

Description

The words we use today

The requirements wrapper

An idea from @tooky: start with what the policy means

Things worth asking

Activity

jbpros commented on Oct 4, 2026

jbpros commented on Oct 4, 2026

jbpros commented on Oct 4, 2026

ToreMerkely commented on Oct 5, 2026

Changes we'd like in ergo

Words and shape

Operators

Scope and reuse

Report

jbpros commented on Oct 5, 2026

Already works

Not now

Sections next to requirements

Moved elsewhere

jbpros commented on Oct 5, 2026

jbpros commented on Oct 5, 2026

jbpros commented on Oct 7, 2026

mbevc1 commented on Oct 7, 2026

jbpros commented on Oct 7, 2026

mbevc1 commented on Oct 7, 2026

jbpros commented on Oct 9, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

The `requirements` wrapper

Sections next to `requirements`