Namespace Configuration

This document describes how to configure a Prism namespace. Namespaces are the primary way to request data access patterns in Prism.

Auto-Generated Documentation

This page is automatically generated from the JSON Schema definition at schemas/config/namespace-request.schema.json. Any changes should be made to the schema, then regenerated using:

uv run tooling/config_schema_tools.py docs schemas/config/namespace-request.schema.json

Overview

A namespace configuration declares WHAT you need, not HOW it should be implemented. The Prism platform automatically selects the appropriate patterns, backends, and resource allocations based on your declared requirements.

Configuration Layer: Layer 1 (User Request) from RFC-056

References:

RFC-056 - Unified Configuration Model
ADR-002 - Client-Originated Configuration
ADR-022 - Dynamic Client Configuration
ADR-050 - Topaz Policy Authorization

Configuration Fields

`namespace` (required)

Type: string

Unique namespace identifier within your team. Must be lowercase alphanumeric with hyphens, 3-63 characters.

Validation Pattern: ^[a-z][a-z0-9-]{2,62}$

Examples:

order-processing
user-sessions
analytics-events

`team` (required)

Type: string

Team that owns this namespace. Must be lowercase alphanumeric with hyphens, 3-63 characters.

Validation Pattern: ^[a-z][a-z0-9-]{2,62}$

Examples:

payments-team
identity-team
analytics-team

`pattern` (required)

Type: string (enum)

High-level data access pattern type. The platform will select specific implementation patterns based on this choice combined with your functional requirements.

Available Patterns:

Pattern	Description	Use Case
`queue`	Point-to-point messaging with exactly-once delivery	Order processing, task queues
`pubsub`	Broadcast messaging with fan-out to multiple consumers	Event notifications, real-time updates
`keyvalue`	Fast key-value lookups with optional TTL	Session storage, caching
`reader`	Read-only access to data streams	Analytics, data consumers
`transact`	Multi-operation transactions with ACID guarantees	Financial transactions
`multicast-registry`	Service discovery with pub/sub notifications (RFC-017)	Service mesh, discovery
`event-sourcing`	Event log with replay and projections	Audit trails, event stores
`mailbox`	Searchable event store with query capabilities (RFC-037)	Message archives

`needs` (required)

Type: object

Functional requirements that describe what you need from the data access layer. These are declarative, not implementation details.

`durability` (required)

Type: string (enum: strong, eventual, best-effort)

Data loss tolerance level.

Values:

strong: Sync disk writes before ack (no data loss, slowest)
eventual: Async disk writes (minimal data loss window, balanced)
best-effort: In-memory only (data loss on restart, fastest)

Permission Level Restrictions:

Guided: All levels allowed
Advanced: All levels allowed
Expert: All levels allowed

`replay`

Type: boolean (default: false)

Enable replay capability (ability to read from the beginning of the stream).

Pattern Trigger

Setting replay: true triggers the replay-store pattern implementation.

`write_rps`

Type: integer (min: 0, max: 10,000,000)

Estimated write throughput in requests per second. Used for capacity planning.

Permission Level Limits:

Guided: Max 50,000 RPS
Advanced: Max 500,000 RPS
Expert: Unlimited

Quota: Counts against team's max_total_write_rps quota.

Examples: 5000, 50000, 500000

`read_rps`

Type: integer (min: 0, max: 10,000,000)

Estimated read throughput in requests per second.

Permission Level Limits:

Guided: Max 100,000 RPS
Advanced: Max 1,000,000 RPS
Expert: Unlimited

Examples: 10000, 100000, 1000000

`data_size`

Type: string

Estimated total data size in GB, TB, or PB format.

Format: <number><unit> where unit is GB, TB, or PB

Examples: 100GB, 1TB, 10TB

`retention`

Type: string

Data retention period using simplified format or ISO 8601 duration.

Format: <number><unit> where unit is days, hours, or minutes

Permission Level Limits:

Guided: Max 90 days
Advanced: Max 365 days
Expert: Unlimited

Examples: 30days, 90days, 365days, P30D

`max_message_size`

Type: string

Maximum message/record size in KB, MB, or GB format.

Format: <number><unit> where unit is KB, MB, or GB

Pattern Trigger

Messages larger than 1MB trigger the claim-check pattern (RFC-033) automatically.

Permission Level Limits:

Guided: Max 10MB
Advanced: Max 100MB
Expert: Unlimited

Examples: 1MB, 10MB, 100MB

`ordered`

Type: boolean (default: false)

Preserve message ordering. Affects partitioning strategy.

`consistency` (required)

Type: string (enum)

Read consistency guarantee level.

Values:

Consistency	Description	Preferred Backends
`eventual`	Reads may see stale data (fastest)	Kafka, NATS, S3
`bounded-staleness`	Reads within N seconds of latest write	Kafka, Redis
`strong`	Reads always see latest committed write	Postgres, Redis
`linearizable`	Reads respect real-time ordering (slowest)	Postgres

`partition_count`

Type: integer (min: 1, max: 256)

Partitioning hint. Platform may override based on throughput requirements.

Permission Level Access:

Guided: Not allowed to specify
Advanced: Can specify 1-256
Expert: Can specify 1-256

References: RFC-048 - Cross-Proxy Partition Strategies

`ttl`

Type: string

Time-to-live for individual records. Overrides retention period if shorter.

Format: <number><unit> where unit is s (seconds), m (minutes), h (hours), or d (days)

Examples: 30s, 5m, 24h, 7d

References: ADR-031 - TTL Defaults Client Data

`access`

Type: object

Access control declarations enforced by Topaz (ADR-050).

`owners` (required)

Type: array (min items: 1)

Teams with administrative access to this namespace.

Example:

owners:
  - team: payments-team
    permissions: [read, write, admin]

`consumers`

Type: array

Services or users that can consume this namespace.

Example:

consumers:
  - service: order-api
    permissions: [read, write]
  - service: analytics-pipeline
    permissions: [read]

`cross_namespace`

Type: array

Cross-namespace access grants for data flows between namespaces.

Permission Required

Requires Advanced or Expert permission level.

Example:

cross_namespace:
  - namespace: order-events
    permissions: [read]
    purpose: "Read order events for analytics aggregation"

`policies`

Type: object

Compliance and security policy requirements.

`pii_handling`

Type: boolean (default: false)

Enable PII detection, encryption, and masking (ADR-029).

`audit_logging`

Type: boolean (default: false)

Enable audit logging for all data access operations (ADR-008).

`compliance`

Type: array (enum)

Compliance categories that apply to this namespace.

Available Categories:

Code	Description
`pci`	Payment Card Industry Data Security Standard
`soc2`	Service Organization Control 2
`hipaa`	Health Insurance Portability and Accountability Act
`gdpr`	General Data Protection Regulation (EU)
`sox`	Sarbanes-Oxley Act (financial reporting)

Examples: [pci, sox], [gdpr]

`regions`

Type: array

Data residency requirements (AWS region format: xx-xxxx-N).

Examples: [us-east-1, us-west-2], [eu-west-1]

`encryption`

Type: object

Encryption requirements.

`at_rest` (default: `true`)

Encrypt data at rest.

`in_transit` (default: `true`)

Encrypt data in transit (always true in production).

`key_rotation`

Key rotation period (e.g., 90days, 180days).

`metadata`

Type: object

Optional metadata for documentation and discovery.

Example:

metadata:
  owner: payments-team
  slack_channel: "#payments-ops"
  runbook: "https://wiki.example.com/payments/order-processing"

`description`

Type: string (max 500 characters)

Human-readable description for documentation purposes.

Example: "Order processing queue for e-commerce transactions with strong durability guarantees"

Complete Example

namespace: order-processing
team: payments-team
pattern: queue

needs:
  durability: strong
  replay: false
  write_rps: 5000
  read_rps: 10000
  data_size: 100GB
  retention: 30days
  max_message_size: 1MB
  ordered: true
  consistency: strong

access:
  owners:
    - team: payments-team
  consumers:
    - service: order-api
      permissions: [read, write]
    - service: analytics-pipeline
      permissions: [read]

policies:
  pii_handling: true
  audit_logging: true
  compliance: [pci, sox]
  encryption:
    at_rest: true
    in_transit: true
    key_rotation: 90days

description: Order processing queue with PCI compliance and strong durability

Validation

To validate your configuration:

uv run tooling/config_schema_tools.py validate your-config.yaml

For more information on the configuration schema system, see MEMO-082.

Overview​

Configuration Fields​

namespace (required)​

team (required)​

pattern (required)​

needs (required)​

durability (required)​

replay​

write_rps​

read_rps​

data_size​

retention​

max_message_size​

ordered​

consistency (required)​

partition_count​

ttl​

access​

owners (required)​

consumers​

cross_namespace​

policies​

pii_handling​

audit_logging​

compliance​

regions​

encryption​

at_rest (default: true)​

in_transit (default: true)​

key_rotation​

metadata​

description​

Complete Example​

Validation​

See Also​

Overview

Configuration Fields

`namespace` (required)

`team` (required)

`pattern` (required)

`needs` (required)

`durability` (required)

`replay`

`write_rps`

`read_rps`

`data_size`

`retention`

`max_message_size`

`ordered`

`consistency` (required)

`partition_count`

`ttl`

`access`

`owners` (required)

`consumers`

`cross_namespace`

`policies`

`pii_handling`

`audit_logging`

`compliance`

`regions`

`encryption`

`at_rest` (default: `true`)

`in_transit` (default: `true`)

`key_rotation`

`metadata`

`description`

Complete Example

Validation

See Also