Anatomy of a policy document

Anatomy of a policy document

One JSON schema for open and sealed carriers: a subject-wide global set, the deny gates, and permissions in eight categories. Every top-level key is optional; {} is a valid document.

global — the subject-wide gate

global — the subject-wide gate

An array. Each element is either a restriction entry written inline, or a restriction-driving profile reference:
{"profile": {"id": "…", "relays": […]}}
Joins the one global set — the union over every guardian's binding carriers — and gates both directions, the guardians' own line included.
A harvested carrier's global section never applies.

An array. Each element is either a restriction entry writteninline, or a restriction-driving profile reference:{"profile": {"id": "…", "relays": […]}}Joins the one global set — the union over every guardian'sbinding carriers — and gates both directions, the guardians'own line included.A harvested carrier's global section never applies.

deny — the deny gates

deny — the deny gates

pubkeys people
events things, by id or coordinate — the thing, never its author
relays places
lists shared blocklists, read one level deep
Unioned over every guardian's binding carriers; over-rules every grant.
A deny value naming a current guardian refuses the assembly.

pubkeys peopleevents things, by id or coordinate — the thing, never itsauthorrelays placeslists shared blocklists, read one level deepUnioned over every guardian's binding carriers; over-rulesevery grant.A deny value naming a current guardian refuses theassembly.

permissions — eight categories

permissions — eight categories

interact/npub

view/npub

interact/relay

view/relay

interact/event

view/event

extend/npub

extend/relay

Each holds an array of permissions.
Admission composes 1-of-N across all guardians.

Each holds an array of permissions.Admission composes 1-of-N across all guardians.

A permission — one card

A permission — one card

label a name for prompts and the trace; never evaluated
restrictions its own entries — they narrow this permission alone
profile one grant-scoping profile, joined conjunctively
pubkeys | relays | events direct members, matching the category's scope
lists members by reference: NIP-51 lists
interactionRelays where exchanges with its members happen
monitorRelays an oversight copy of what the subject signs under it
extend {via, map}: its members become sources (via: npub categories only)

Routing is carried per permission, never per member. Which fields a category admits is fixed by a matrix; a field in the wrong place invalidates the permission. One exception to 'alone': a direct interact/relay permission keeps the relay whitelist on even when it is void or invalid.

label a name for prompts and the trace; never evaluatedrestrictions its own entries — they narrow this permission aloneprofile one grant-scoping profile, joined conjunctivelypubkeys | relays | events direct members, matching the category's scopelists members by reference: NIP-51 listsinteractionRelays where exchanges with its members happenmonitorRelays an oversight copy of what the subject signs under itextend {via, map}: its members become sources (via: npub categoriesonly)Routing is carried per permission, never per member. Which fields acategory admits is fixed by a matrix; a field in the wrong place invalidatesthe permission. One exception to 'alone': a direct interact/relaypermission keeps the relay whitelist on even when it is void or invalid.

A restriction entry

A restriction entry

Six predicate fields, always all present — * is the wildcard, never absence:

polarity   allow | deny
kinds      * | 1,7,…
weekdays   * | 1,…,7
time       * | 21:00-07:00
direction  * | input | output
opacity    * | opaque | plain

One optional demand, on allow entries only:
rebroadcast  "deny"

Inside a permission, a malformed entry costs the whole permission: dropping it alone could loosen the grant.

A list reference

A list reference

{"a": "30000:<pk>:classmates"}
live — follows the list at that address

{"a": "…", "id": "<event id>"}
pinned — exactly that one event

Read by the site's scope: p for people, relay/r for places, e/a for things; deny.lists reads them all.

A live list is followed only when its owner is a current guardian — or, inside a harvested carrier, that carrier's author.
Members are third-party material, read leniently: a malformed one is skipped.

{"a": "30000:<pk>:classmates"}live — follows the list at that address{"a": "…", "id": "<event id>"}pinned — exactly that one eventRead by the site's scope: p for people, relay/r forplaces, e/a for things; deny.lists reads them all.A live list is followed only when its owner is a currentguardian — or, inside a harvested carrier, thatcarrier's author.Members are third-party material, read leniently: amalformed one is skipped.

Example (abridged from the specification)

Example (abridged from the specification)

{
  "global": [
    { "polarity": "deny", "kinds": "*",
      "weekdays": "*", "time": "21:00-07:00",
      "direction": "*", "opacity": "*" },
    { "profile": { "id": "<event id>",
        "relays": ["wss://relay.example"] } }
  ],
  "deny": {
    "pubkeys": ["<pubkey>"],
    "events": ["<event id>", "30023:<pubkey>:an-article"],
    "relays": ["wss://denied.example"],
    "lists": [{ "a": "30000:<pk>:blocklist", "id": "<id>" }]
  },
  "permissions": {
    "interact/npub": [
      { "label": "school friends",
        "restrictions": [
          { "polarity": "allow", "kinds": "1,7",
            "weekdays": "1,2,3,4,5",
            "time": "07:00-20:00",
            "direction": "*", "opacity": "*",
            "rebroadcast": "deny" } ],
        "monitorRelays": ["wss://family.example"],
        "pubkeys": ["<pubkey>"],
        "lists": [{ "a": "30000:<guardian>:classmates" }] }
    ],
    "extend/npub": [
      { "pubkeys": ["<pubkey>"],
        "extend": { "via": "curator",
          "map": { "interact/npub": "view",
                   "view/npub": "view" } } }
    ]
  }
}

{"global": [{ "polarity": "deny", "kinds": "*","weekdays": "*", "time": "21:00-07:00","direction": "*", "opacity": "*" },{ "profile": { "id": "<event id>","relays": ["wss://relay.example"] } }],"deny": {"pubkeys": ["<pubkey>"],"events": ["<event id>", "30023:<pubkey>:an-article"],"relays": ["wss://denied.example"],"lists": [{ "a": "30000:<pk>:blocklist", "id": "<id>" }]},"permissions": {"interact/npub": [{ "label": "school friends","restrictions": [{ "polarity": "allow", "kinds": "1,7","weekdays": "1,2,3,4,5","time": "07:00-20:00","direction": "*", "opacity": "*","rebroadcast": "deny" } ],"monitorRelays": ["wss://family.example"],"pubkeys": ["<pubkey>"],"lists": [{ "a": "30000:<guardian>:classmates" }] }],"extend/npub": [{ "pubkeys": ["<pubkey>"],"extend": { "via": "curator","map": { "interact/npub": "view","view/npub": "view" } } }]}}

Strict where TEPP writes, lenient where others do

Strict where TEPP writes, lenient where others do

Unknown or duplicate key, null, odd numbers, a bad map mode
The whole payload is invalid (numbers must be plain integers). In a binding carrier the assembly refuses — loud and local; a harvested carrier drops.

Unknown or duplicate key, null, odd numbers, a bad map modeThe whole payload is invalid (numbers must be plain integers). Ina binding carrier the assembly refuses — loud and local; aharvested carrier drops.

A malformed entry or field inside a permission
That whole permission is invalid: it grants nothing and vetoes nothing; the rest of the carrier stands.

A malformed entry or field inside a permissionThat whole permission is invalid: it grants nothing and vetoesnothing; the rest of the carrier stands.

A list or profile that cannot be loaded
Absent, retried and reported: a grant-side failure leaves its permission inert; a deny list lapses, visibly.

A list or profile that cannot be loadedAbsent, retried and reported: a grant-side failure leaves itspermission inert; a deny list lapses, visibly.

{} — the empty document
Valid. Republished at a coordinate, it retires the carrier: policy shrinks only by a signed act.

{} — the empty documentValid. Republished at a coordinate, it retires the carrier: policyshrinks only by a signed act.

TEPP Zeta · diagram 07 · statements: POL-001–POL-135 (schema, grammar, degradation, matrix), LIST-001–LIST-026, CONS-003, CONS-095, ADDR-022