# Capability Schema — Layer 3 Reusable Entity Type # KNO Schema Version: 0.2.0 # CHANGELOG: # 0.2.0 (M52 P4.1, #2139): Add `visibility: public` collection default per REQ-18. # Codifies that capability entities are public reference # knowledge consumed via the four-surface contract. # # Layer 3 reusable schema that formalizes what a CAPABILITY is. # # A capability is a structured permission: {action, resource, constraints}. # Capabilities are defined INLINE within role files (content/roles/*.kno), # not as separate standalone entities. This schema defines the shape and # vocabulary of capabilities. # # RELATIONSHIP TO ROLE-SCHEMA: # role-schema.kno already has a `capabilities` field with # `[{action, resource}]` objects. This schema formalizes that structure # by adding `constraints` and `description`, and by defining the standard # vocabulary of actions, resources, and constraint types. # # KEY DESIGN DECISIONS (Phase 0): # - Capabilities are inline in role files, NOT separate entities # - This schema defines the SHAPE, not instances # - Constraints field adds scoping: own | assigned | all # - Standard action vocabulary: create, read, update, delete, provision, manage, invite # # THREE-GATE TEST: # Gate 1 (Distinctness): YES — a capability is structurally different from # a role (a role HAS capabilities, a capability is a {action, resource, constraints} tuple) # Gate 2 (Reusability): YES — used by every role definition # Gate 3 (Clarity): YES — formalizing the informal structure adds clarity # ============================================================================= # SCHEMA DECLARATION (RFC-007) # ============================================================================= $schema: kno@0.0.9 # ============================================================================= # IDENTITY (Layer 1) # ============================================================================= id: 01KGXP5R2V4YN8WK6T3QJDM7FH slug: capability-schema type: spec version: 0.2.0 # ============================================================================= # VISIBILITY DECLARATION (REQ-18) — collection default # ============================================================================= # Capability entities (content/capabilities/*.kno) are public reference # knowledge by default. Per REQ-18, individual entities MAY override with # their own `visibility:` field (last-write-wins at the entity level). # Drives the four-surface contract per kno-system_architecture.md # § Agent Surface Integration and public-surface-parity.instructions.md. visibility: public # ============================================================================= # STANDARD TIER # ============================================================================= title: "Capability Schema" purpose: | Define the schema for capability objects — structured permission tuples that describe what an actor can do, to what, and under what constraints. **What is a Capability?** A capability is the atomic unit of permission in the Possibility platform. It is a structured tuple of: - **action** — The verb (what can be done) - **resource** — The noun (what it applies to) - **constraints** — The scope (under what conditions) Example: `{action: "edit", resource: "content", constraints: {scope: "assigned"}}` means "can edit content that is assigned to this actor." **Inline, Not Standalone:** Capabilities are defined inline within role files (`content/roles/*.kno`). There are NO standalone capability entity files. This schema defines the shape and vocabulary — role files USE that shape. ```yaml # In a role file (content/roles/contributor.kno): capabilities: - action: create resource: possibility description: "Create new possibilities" - action: provision resource: services constraints: scope: own description: "Provision services for own possibilities" ``` **Relationship to Role Schema:** The role-schema already has `capabilities: [{action, resource}]`. This schema extends that with `constraints` and `description`, and defines the standard vocabulary of values. **Constraint Model:** The `constraints` field provides scoping: | Scope | Meaning | |-------|---------| | own | Only resources owned by this actor | | assigned | Resources assigned to this actor | | all | All resources of this type (admin-level) | | possibility | Scoped to a specific possibility context | # ============================================================================= # RICH TIER — Provenance & Taxonomy # ============================================================================= provenance: origin: id: 01KGXP5R2V4YN8WK6T3QJDM7FH timestamp: "2026-02-17T00:00:00Z" tool: manual taxonomy: topics: - permissions - capabilities - authorization - access-control - roles keywords: - capability - action - resource - constraints - scope - permission - authorization - rbac # ============================================================================= # RICH TIER — Relationships # ============================================================================= relationships: depends_on: - xri: "kno://specs/kno-spec" reason: "Conforms to KNO format specification v0.0.9" related_to: - xri: "kno://specs/role-schema" reason: "Roles contain capabilities[] arrays that conform to this schema" - xri: "kno://specs/possibility-schema" reason: "Many capabilities are scoped to possibility resources" - xri: "kno://specs/service-config-schema" reason: "provision_services capability gates service-config creation" enables: - xri: "kno://content/roles/*" reason: "Role files use capabilities conforming to this schema" # ============================================================================= # RICH TIER — Quality # ============================================================================= quality: completeness: 0.80 last_reviewed: "2026-02-17" review_status: draft reviewed_by: "claude" # ============================================================================= # HISTORY (P9 Temporal) # ============================================================================= _history: retention: full format: changelog changelog: - version: "0.1.0" date: "2026-02-17" author: "claude" summary: "Initial capability schema" changes: - "Created for auth-as-a-service-v1 milestone (Phase 1)" - "Formalizes role-schema's {action, resource} with constraints + description" - "Defines standard vocabulary for actions, resources, and scopes" - "Inline model — capabilities live in role files, not standalone entities" # ============================================================================= # SPECIFICATION CONTENT # ============================================================================= spec: status: Draft description: | ## Capability Object Structure A capability is an inline object within a role's `capabilities[]` array. It is NOT a standalone entity — there are no capability .kno files. ### Shape ```yaml capabilities: - action: "create" # required — the verb resource: "possibility" # required — the noun constraints: # optional — scoping scope: "own" description: "Create new possibilities" # optional — human context ``` ### Standard Action Vocabulary | Action | Meaning | Typical Resources | |--------|---------|-------------------| | create | Create new instances | possibility, content, invitation | | read | View/access | content, secrets, interpretations | | update | Modify existing | content, possibility, profile | | delete | Remove/archive | content, possibility | | provision | Create service bindings | services | | manage | Full lifecycle control | project, members, services | | invite | Send invitations | members | | approve | Approve pending items | content, membership | | assign | Assign to others | tasks, content, roles | ### Standard Resource Vocabulary | Resource | What It Refers To | |----------|-------------------| | possibility | Possibility entities | | content | Content within a possibility | | services | Service bindings (auth, storage, etc.) | | secrets | Secret references in Infisical | | members | Possibility membership | | project | Project-level settings | | interpretations | Analysis interpretations | | roles | Role assignments | | invitation | Membership invitations | | profile | User profile data | ### Constraint Scoping Constraints narrow a capability. Without constraints, the capability applies to all instances of the resource the actor has access to. ```yaml # No constraints — edit any content visible to this role - action: edit resource: content # Scoped — edit only content assigned to this actor - action: edit resource: content constraints: scope: assigned # Scoped — manage only own possibilities - action: manage resource: project constraints: scope: own ``` ### Two-Axis Role Model (6-Tier) Roles operate on two independent axes: ``` ┌──────────────────────────────────────────────────────────────────┐ │ TWO-AXIS CAPABILITY MODEL │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ PLATFORM AXIS (global, site-wide) │ │ ───────────────────────────────── │ │ │ │ Guest (pspace:guest) │ │ ├── read: homepage, docs/*, specs/*, playground/* │ │ │ │ Member (pspace:member) [inherits Guest] │ │ ├── create: possibility (→ becomes Organizer) │ │ ├── update: profile (scope: own) │ │ ├── connect_accounts: connectors/* (scope: own) │ │ └── read: possibilities/* (public listings) │ │ │ │ Admin (pspace:admin) [inherits Member] │ │ ├── manage: project (scope: all) │ │ ├── manage: members (scope: all) │ │ ├── manage: services (scope: all) │ │ ├── approve: content │ │ ├── assign: roles │ │ └── delete: possibility │ │ │ │ Super Admin (pspace:superadmin) [Keycloak only — no .kno file] │ │ └── (all capabilities, platform override on both axes) │ │ │ │ │ │ POSSIBILITY AXIS (scoped to a specific possibility) │ │ ──────────────────────────────────────────────── │ │ │ │ Contributor (pspace:contributor) │ │ ├── create/update/read: content (scope: possibility) │ │ ├── use: services (scope: possibility) │ │ ├── read: secrets (scope: possibility) │ │ ├── read/write: kno/* (scope: possibility) │ │ ├── read: interpretations (scope: possibility) │ │ └── read: possibility (scope: possibility) │ │ │ │ Organizer (pspace:organizer) [inherits Contributor] │ │ ├── manage: possibility (scope: own) │ │ ├── delete: possibility (scope: own) │ │ ├── transfer: ownership (scope: own) │ │ ├── provision/deprovision: services (scope: own) │ │ ├── configure: auth (scope: own) │ │ ├── invite: contributors, members (scope: own) │ │ ├── remove: members (scope: own) │ │ └── read: secrets (scope: own) │ │ │ │ │ │ AXIS INTERACTION │ │ ──────────────── │ │ • A Member becomes an Organizer by creating a possibility │ │ • A Member becomes a Contributor when invited to a possibility │ │ • Admins have override authority across both axes │ │ • Possibility roles are per-possibility, not global │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` # --------------------------------------------------------------------------- # CAPABILITY OBJECT SCHEMA # --------------------------------------------------------------------------- schema: type: object description: | Schema for individual capability objects as they appear inline within a role's capabilities[] array. required: - action - resource properties: action: type: string required: true description: | The verb — what can be done. Should use standard vocabulary (create, read, update, delete, provision, manage, invite, approve, assign). Custom actions are allowed for domain-specific needs. examples: - "create" - "read" - "update" - "delete" - "provision" - "manage" - "invite" - "approve" - "assign" resource: type: string required: true description: | The noun — what the action applies to. Should use standard vocabulary (possibility, content, services, secrets, members, project, interpretations, roles). Supports glob patterns for sub-resources. examples: - "possibility" - "content" - "services" - "secrets" - "members" - "project" - "interpretations" constraints: type: object description: | Optional scoping constraints. Narrows the capability to a subset of the resource. properties: scope: type: string enum: - own - assigned - all - possibility description: | Ownership/assignment scope. - own: Only resources owned by this actor - assigned: Resources assigned to this actor - all: All resources (admin-level) - possibility: Scoped to possibility context possibility_xri: type: string format: xri description: | When scope is "possibility", specifies which possibility. Example: "pspace://possibility:01KG..." conditions: type: array items: type: string description: | Additional freeform conditions. Example: ["status != archived", "lifecycle == building"] description: type: string description: | Human-readable description of what this capability enables. Helps with documentation and audit. # ============================================================================= # EXAMPLES # ============================================================================= examples: - title: "Simple Capability" description: "A basic create capability with no constraints" content: | action: create resource: possibility description: "Create new possibilities" - title: "Scoped Capability" description: "An edit capability scoped to assigned content" content: | action: update resource: content constraints: scope: assigned description: "Edit content assigned to this contributor" - title: "Provisioning Capability" description: "Capability to provision services for own possibilities" content: | action: provision resource: services constraints: scope: own description: "Provision infrastructure services for own possibilities" - title: "Admin Capability" description: "Full management capability with no scope restrictions" content: | action: manage resource: project constraints: scope: all description: "Full project management across all possibilities" - title: "Capability in Role Context" description: "How capabilities appear inside a role .kno file" content: | # Within content/roles/contributor.kno capabilities: - action: create resource: possibility description: "Create new possibilities" - action: provision resource: services constraints: scope: own description: "Provision services for own possibilities" - action: read resource: secrets constraints: scope: own description: "Read secrets for own service configs" - action: manage resource: project constraints: scope: own description: "Manage own possibility settings" - action: invite resource: members description: "Invite users to own possibilities" - action: update resource: content constraints: scope: assigned description: "Edit content assigned to this contributor" - action: create resource: content description: "Submit new content" # ============================================================================= # VALIDATION RULES # ============================================================================= validation: rules: - name: "action_required" severity: error message: "Capability must have an action" check: "exists(action)" - name: "resource_required" severity: error message: "Capability must have a resource" check: "exists(resource)" - name: "action_vocabulary" severity: warning message: "Action should use standard vocabulary when possible" check: "in(action, ['create', 'read', 'update', 'delete', 'provision', 'manage', 'invite', 'approve', 'assign'])" - name: "resource_vocabulary" severity: warning message: "Resource should use standard vocabulary when possible" check: "in(resource, ['possibility', 'content', 'services', 'secrets', 'members', 'project', 'interpretations', 'roles', 'invitation', 'profile'])" - name: "scope_valid" severity: error message: "Constraint scope must be one of: own, assigned, all, possibility" check: "in(constraints.scope, ['own', 'assigned', 'all', 'possibility'])" when: "exists(constraints) && exists(constraints.scope)" # ============================================================================= # SOURCE (P4) # ============================================================================= source: | # This schema formalizes the {action, resource} capability objects already # used in role-schema.kno's capabilities[] field. It adds: # - constraints.scope for ownership/assignment scoping # - description for human-readable documentation # - Standard vocabulary definitions for actions and resources # # Design decision: capabilities are INLINE in role files, not standalone # entities. This schema defines the shape, not instances. source_format: yaml source_hash: "sha256:tbd" # ============================================================================= # CONTAINER TIER — Navigation Index # ============================================================================= _index: - path: "identity" line: 35 keywords: [id, slug, type, version] - path: "spec/description" line: 130 keywords: [capability, action, resource, constraints, vocabulary] - path: "spec/schema" line: 225 keywords: [action, resource, constraints, scope] - path: "examples" line: 290 keywords: [simple, scoped, provisioning, admin, role-context] - path: "validation" line: 345 keywords: [rules, action, resource, scope] contains: - xri: "#spec" role: section title: "Specification Content" keywords: [capability, action, resource, constraints] - xri: "#spec/schema" role: section title: "Capability Object Schema" keywords: [action, resource, scope, description] - xri: "#examples" role: section title: "Usage Examples" keywords: [simple, scoped, provisioning, role-context] - xri: "#validation" role: section title: "Validation Rules" keywords: [required, vocabulary, scope]